Mercurial > emacs
changeset 40786:7917695c31da
New file.
| author | Eli Zaretskii <eliz@gnu.org> |
|---|---|
| date | Tue, 06 Nov 2001 19:01:01 +0000 |
| parents | 2fb9d407ae73 |
| children | 9f2a09c43f5f |
| files | man/calc.texi |
| diffstat | 1 files changed, 35655 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/calc.texi Tue Nov 06 19:01:01 2001 +0000 @@ -0,0 +1,35655 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header (This is for running Texinfo on a region.) +@c smallbook +@setfilename ../info/calc +@c [title] +@settitle GNU Emacs Calc 2.02 Manual +@setchapternewpage odd +@comment %**end of header (This is for running Texinfo on a region.) + +@tex +% Some special kludges to make TeX formatting prettier. +% Because makeinfo.c exists, we can't just define new commands. +% So instead, we take over little-used existing commands. +% +% Redefine @cite{text} to act like $text$ in regular TeX. +% Info will typeset this same as @samp{text}. +\gdef\goodtex{\tex \let\rm\goodrm \let\t\ttfont \turnoffactive} +\gdef\goodrm{\fam0\tenrm} +\gdef\cite{\goodtex$\citexxx} +\gdef\citexxx#1{#1$\Etex} +\global\let\oldxrefX=\xrefX +\gdef\xrefX[#1]{\begingroup\let\cite=\dfn\oldxrefX[#1]\endgroup} +% +% Redefine @i{text} to be equivalent to @cite{text}, i.e., to use math mode. +% This looks the same in TeX but omits the surrounding ` ' in Info. +\global\let\i=\cite +% +% Redefine @c{tex-stuff} \n @whatever{info-stuff}. +\gdef\c{\futurelet\next\mycxxx} +\gdef\mycxxx{% + \ifx\next\bgroup \goodtex\let\next\mycxxy + \else\ifx\next\mindex \let\next\relax + \else\ifx\next\kindex \let\next\relax + \else\ifx\next\starindex \let\next\relax \else \let\next\comment + \fi\fi\fi\fi \next +} +\gdef\mycxxy#1#2{#1\Etex\mycxxz} +\gdef\mycxxz#1{} +@end tex + +@c Fix some things to make math mode work properly. +@iftex +@textfont0=@tenrm +@font@teni=cmmi10 scaled @magstephalf @textfont1=@teni +@font@seveni=cmmi7 scaled @magstephalf @scriptfont1=@seveni +@font@fivei=cmmi5 scaled @magstephalf @scriptscriptfont1=@fivei +@font@tensy=cmsy10 scaled @magstephalf @textfont2=@tensy +@font@sevensy=cmsy7 scaled @magstephalf @scriptfont2=@sevensy +@font@fivesy=cmsy5 scaled @magstephalf @scriptscriptfont2=@fivesy +@font@tenex=cmex10 scaled @magstephalf @textfont3=@tenex +@scriptfont3=@tenex @scriptscriptfont3=@tenex +@textfont7=@tentt @scriptfont7=@tentt @scriptscriptfont7=@tentt +@end iftex + +@c Fix some other things specifically for this manual. +@iftex +@finalout +@mathcode`@:=`@: @c Make Calc fractions come out right in math mode +@tocindent=.5pc @c Indent subsections in table of contents less +@rightskip=0pt plus 2pt @c Favor short lines rather than overfull hboxes +@tex +\gdef\coloneq{\mathrel{\mathord:\mathord=}} +\ifdim\parskip>17pt + \global\parskip=12pt % Standard parskip looks a bit too large +\fi +\gdef\internalBitem{\parskip=7pt\kyhpos=\tableindent\kyvpos=0pt +\smallbreak\parsearg\itemzzy} +\gdef\itemzzy#1{\itemzzz{#1}\relax\ifvmode\kern-7pt\fi} +\gdef\trademark{${}^{\rm TM}$} +\gdef\group{% + \par\vskip8pt\begingroup + \def\Egroup{\egroup\endgroup}% + \let\aboveenvbreak=\relax % so that nothing gets between vtop and first box + \def\singlespace{\baselineskip=\singlespaceskip}% + \vtop\bgroup +} +% +%\global\abovedisplayskip=0pt +%\global\abovedisplayshortskip=-10pt +%\global\belowdisplayskip=7pt +%\global\belowdisplayshortskip=2pt +\gdef\beforedisplay{\vskip-10pt} +\gdef\afterdisplay{\vskip-5pt} +\gdef\beforedisplayh{\vskip-25pt} +\gdef\afterdisplayh{\vskip-10pt} +% +\gdef\printindex{\parsearg\calcprintindex} +\gdef\calcprintindex#1{% + \doprintindex{#1}% + \openin1 \jobname.#1s + \ifeof1{\let\s=\indexskip \csname indexsize#1\endcsname}\fi + \closein1 +} +\gdef\indexskip{(This page intentionally left blank)\vfill\eject} +\gdef\indexsizeky{\s\s\s\s\s\s\s\s} +\gdef\indexsizepg{\s\s\s\s\s\s} +\gdef\indexsizetp{\s\s\s\s\s\s} +\gdef\indexsizecp{\s\s\s\s} +\gdef\indexsizevr{} +\gdef\indexsizefn{\s\s} +\gdef\langle#1\rangle{\it XXX} % Avoid length mismatch with true expansion +% +% Ensure no indentation at beginning of sections, and avoid club paragraphs. +\global\let\calcchapternofonts=\chapternofonts +\gdef\chapternofonts{\aftergroup\calcfixclub\calcchapternofonts} +\gdef\calcfixclub{\calcclubpenalty=10000\noindent} +\global\let\calcdobreak=\dobreak +\gdef\dobreak{{\penalty-9999\dimen0=\pagetotal\advance\dimen0by1.5in +\ifdim\dimen0>\pagegoal\vfill\eject\fi}\calcdobreak} +% +\gdef\kindex{\def\indexname{ky}\futurelet\next\calcindexer} +\gdef\tindex{\def\indexname{tp}\futurelet\next\calcindexer} +\gdef\mindex{\let\indexname\relax\futurelet\next\calcindexer} +\gdef\calcindexer{\catcode`\ =\active\parsearg\calcindexerxx} +\gdef\calcindexerxx#1{% + \catcode`\ =10% + \ifvmode \indent \fi \setbox0=\lastbox \advance\kyhpos\wd0 \fixoddpages \box0 + \setbox0=\hbox{\ninett #1}% + \calcindexersh{\llap{\hbox to 4em{\bumpoddpages\lower\kyvpos\box0\hss}\hskip\kyhpos}}% + \global\let\calcindexersh=\calcindexershow + \advance\clubpenalty by 5000% + \ifx\indexname\relax \else + \singlecodeindexer{#1\indexstar}% + \global\def\indexstar{}% + \fi + \futurelet\next\calcindexerxxx +} +\gdef\indexstar{} +\gdef\bumpoddpages{\ifodd\calcpageno\hskip7.3in\fi} +%\gdef\bumpoddpages{\hskip7.3in} % for marginal notes on right side always +%\gdef\bumpoddpages{} % for marginal notes on left side always +\gdef\fixoddpages{% +\global\calcpageno=\pageno +{\dimen0=\pagetotal +\advance\dimen0 by2\baselineskip +\ifdim\dimen0>\pagegoal +\global\advance\calcpageno by 1 +\vfill\eject\noindent +\fi}% +} +\gdef\calcindexershow#1{\smash{#1}\advance\kyvpos by 11pt} +\gdef\calcindexernoshow#1{} +\global\let\calcindexersh=\calcindexershow +\gdef\calcindexerxxx{% + \ifx\indexname\relax + \ifx\next\kindex \global\let\calcindexersh=\calcindexernoshow \fi + \ifx\next\tindex \global\let\calcindexersh=\calcindexernoshow \fi + \fi + \calcindexerxxxx +} +\gdef\calcindexerxxxx#1{\next} +\gdef\indexstarxx{\thinspace{\rm *}} +\gdef\starindex{\global\let\indexstar=\indexstarxx} +\gdef\calceverypar{% +\kyhpos=\leftskip\kyvpos=0pt\clubpenalty=\calcclubpenalty +\calcclubpenalty=1000\relax +} +\gdef\idots{{\indrm...}} +@end tex +@newdimen@kyvpos @kyvpos=0pt +@newdimen@kyhpos @kyhpos=0pt +@newcount@calcclubpenalty @calcclubpenalty=1000 +@newcount@calcpageno +@newtoks@calcoldeverypar @calcoldeverypar=@everypar +@everypar={@calceverypar@the@calcoldeverypar} +@ifx@turnoffactive@undefinedzzz@def@turnoffactive{}@fi +@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi +@catcode`@\=0 \catcode`\@=11 +\r@ggedbottomtrue +\catcode`\@=0 @catcode`@\=@active +@end iftex + +@ifinfo +This file documents Calc, the GNU Emacs calculator. + +Copyright (C) 1990, 1991 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' may be +included in a translation approved by the author instead of in the +original English. +@end ifinfo + +@titlepage +@sp 6 +@center @titlefont{Calc Manual} +@sp 4 +@center GNU Emacs Calc Version 2.02 +@c [volume] +@sp 1 +@center January 1992 +@sp 5 +@center Dave Gillespie +@center daveg@@synaptics.com +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1990, 1991 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' may be +included in a translation approved by the author instead of in the +original English. +@end titlepage + +@c [begin] +@ifinfo +@node Top, Getting Started,, (dir) +@ichapter The GNU Emacs Calculator + +@noindent +@dfn{Calc 2.02} is an advanced desk calculator and mathematical tool +that runs as part of the GNU Emacs environment. + +This manual is divided into three major parts: "Getting Started," the +"Calc Tutorial," and the "Calc Reference." The Tutorial introduces all +the major aspects of Calculator use in an easy, hands-on way. The +remainder of the manual is a complete reference to the features of the +Calculator. + +For help in the Emacs Info system (which you are using to read this +file), type @kbd{?}. (You can also type @kbd{h} to run through a +longer Info tutorial.) + +@end ifinfo +@menu +* Copying:: How you can copy and share Calc. + +* Getting Started:: General description and overview. +* Tutorial:: A step-by-step introduction for beginners. + +* Introduction:: Introduction to the Calc reference manual. +* Data Types:: Types of objects manipulated by Calc. +* Stack and Trail:: Manipulating the stack and trail buffers. +* Mode Settings:: Adjusting display format and other modes. +* Arithmetic:: Basic arithmetic functions. +* Scientific Functions:: Transcendentals and other scientific functions. +* Matrix Functions:: Operations on vectors and matrices. +* Algebra:: Manipulating expressions algebraically. +* Units:: Operations on numbers with units. +* Store and Recall:: Storing and recalling variables. +* Graphics:: Commands for making graphs of data. +* Kill and Yank:: Moving data into and out of Calc. +* Embedded Mode:: Working with formulas embedded in a file. +* Programming:: Calc as a programmable calculator. + +* Installation:: Installing Calc as a part of GNU Emacs. +* Reporting Bugs:: How to report bugs and make suggestions. + +* Summary:: Summary of Calc commands and functions. + +* Key Index:: The standard Calc key sequences. +* Command Index:: The interactive Calc commands. +* Function Index:: Functions (in algebraic formulas). +* Concept Index:: General concepts. +* Variable Index:: Variables used by Calc (both user and internal). +* Lisp Function Index:: Internal Lisp math functions. +@end menu + +@node Copying, Getting Started, Top, Top +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 1, February 1989 + +@display +Copyright @copyright{} 1989 Free Software Foundation, Inc. +675 Mass Ave, Cambridge, MA 02139, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The license agreements of most software companies try to keep users +at the mercy of those companies. By contrast, our General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. The +General Public License applies to the Free Software Foundation's +software and to any other program whose authors commit to using it. +You can use it for your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Specifically, the General Public License is designed to make +sure that you have the freedom to give away or sell copies of free +software, that you receive source code or can get it if you want it, +that you can change the software or use pieces of it in new free +programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of a such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must tell them their rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS +@end iftex +@ifinfo +@center TERMS AND CONDITIONS +@end ifinfo + +@enumerate +@item +This License Agreement applies to any program or other work which +contains a notice placed by the copyright holder saying it may be +distributed under the terms of this General Public License. The +``Program'', below, refers to any such program or work, and a ``work based +on the Program'' means either the Program or any work containing the +Program or a portion of it, either verbatim or with modifications. Each +licensee is addressed as ``you''. + +@item +You may copy and distribute verbatim copies of the Program's source +code as you receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice and +disclaimer of warranty; keep intact all the notices that refer to this +General Public License and to the absence of any warranty; and give any +other recipients of the Program a copy of this General Public License +along with the Program. You may charge a fee for the physical act of +transferring a copy. + +@item +You may modify your copy or copies of the Program or any portion of +it, and copy and distribute such modifications under the terms of Paragraph +1 above, provided that you also do the following: + +@itemize @bullet +@item +cause the modified files to carry prominent notices stating that +you changed the files and the date of any change; and + +@item +cause the whole of any work that you distribute or publish, that +in whole or in part contains the Program or any part thereof, either +with or without modifications, to be licensed at no charge to all +third parties under the terms of this General Public License (except +that you may choose to grant warranty protection to some or all +third parties, at your option). + +@item +If the modified program normally reads commands interactively when +run, you must cause it, when started running for such interactive use +in the simplest and most usual way, to print or display an +announcement including an appropriate copyright notice and a notice +that there is no warranty (or else, saying that you provide a +warranty) and that users may redistribute the program under these +conditions, and telling the user how to view a copy of this General +Public License. + +@item +You may charge a fee for the physical act of transferring a +copy, and you may at your option offer warranty protection in +exchange for a fee. +@end itemize + +Mere aggregation of another independent work with the Program (or its +derivative) on a volume of a storage or distribution medium does not bring +the other work under the scope of these terms. + +@item +You may copy and distribute the Program (or a portion or derivative of +it, under Paragraph 2) in object code or executable form under the terms of +Paragraphs 1 and 2 above provided that you also do one of the following: + +@itemize @bullet +@item +accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of +Paragraphs 1 and 2 above; or, + +@item +accompany it with a written offer, valid for at least three +years, to give any third party free (except for a nominal charge +for the cost of distribution) a complete machine-readable copy of the +corresponding source code, to be distributed under the terms of +Paragraphs 1 and 2 above; or, + +@item +accompany it with the information you received as to where the +corresponding source code may be obtained. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form alone.) +@end itemize + +Source code for a work means the preferred form of the work for making +modifications to it. For an executable file, complete source code means +all the source code for all modules it contains; but, as a special +exception, it need not include source code for modules which are standard +libraries that accompany the operating system on which the executable +file runs, or for standard header files or definitions files that +accompany that operating system. + +@item +You may not copy, modify, sublicense, distribute or transfer the +Program except as expressly provided under this General Public License. +Any attempt otherwise to copy, modify, sublicense, distribute or transfer +the Program is void, and will automatically terminate your rights to use +the Program under this License. However, parties who have received +copies, or rights to use copies, from you under this General Public +License will not have their licenses terminated so long as such parties +remain in full compliance. + +@item +By copying, distributing or modifying the Program (or any work based +on the Program) you indicate your acceptance of this license to do so, +and all its terms and conditions. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the original +licensor to copy, distribute or modify the Program subject to these +terms and conditions. You may not impose any further restrictions on the +recipients' exercise of the rights granted herein. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of the license which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +the license, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL +ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT +LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES +SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE +WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN +ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@node Getting Started, Tutorial, Top, Top +@chapter Getting Started + +@noindent +This chapter provides a general overview of Calc, the GNU Emacs +Calculator: What it is, how to start it and how to exit from it, +and what are the various ways that it can be used. + +@menu +* What is Calc:: +* About This Manual:: +* Notations Used in This Manual:: +* Using Calc:: +* Demonstration of Calc:: +* History and Acknowledgements:: +@end menu + +@node What is Calc, About This Manual, Getting Started, Getting Started +@section What is Calc? + +@noindent +@dfn{Calc} is an advanced calculator and mathematical tool that runs as +part of the GNU Emacs environment. Very roughly based on the HP-28/48 +series of calculators, its many features include: + +@itemize @bullet +@item +Choice of algebraic or RPN (stack-based) entry of calculations. + +@item +Arbitrary precision integers and floating-point numbers. + +@item +Arithmetic on rational numbers, complex numbers (rectangular and polar), +error forms with standard deviations, open and closed intervals, vectors +and matrices, dates and times, infinities, sets, quantities with units, +and algebraic formulas. + +@item +Mathematical operations such as logarithms and trigonometric functions. + +@item +Programmer's features (bitwise operations, non-decimal numbers). + +@item +Financial functions such as future value and internal rate of return. + +@item +Number theoretical features such as prime factorization and arithmetic +modulo @i{M} for any @i{M}. + +@item +Algebraic manipulation features, including symbolic calculus. + +@item +Moving data to and from regular editing buffers. + +@item +``Embedded mode'' for manipulating Calc formulas and data directly +inside any editing buffer. + +@item +Graphics using GNUPLOT, a versatile (and free) plotting program. + +@item +Easy programming using keyboard macros, algebraic formulas, +algebraic rewrite rules, or extended Emacs Lisp. +@end itemize + +Calc tries to include a little something for everyone; as a result it is +large and might be intimidating to the first-time user. If you plan to +use Calc only as a traditional desk calculator, all you really need to +read is the ``Getting Started'' chapter of this manual and possibly the +first few sections of the tutorial. As you become more comfortable with +the program you can learn its additional features. In terms of efficiency, +scope and depth, Calc cannot replace a powerful tool like Mathematica. +@c Removed this per RMS' request: +@c Mathematica@c{\trademark} @asis{ (tm)}. +But Calc has the advantages of convenience, portability, and availability +of the source code. And, of course, it's free! + +@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started +@section About This Manual + +@noindent +This document serves as a complete description of the GNU Emacs +Calculator. It works both as an introduction for novices, and as +a reference for experienced users. While it helps to have some +experience with GNU Emacs in order to get the most out of Calc, +this manual ought to be readable even if you don't know or use Emacs +regularly. + +@ifinfo +The manual is divided into three major parts:@: the ``Getting +Started'' chapter you are reading now, the Calc tutorial (chapter 2), +and the Calc reference manual (the remaining chapters and appendices). +@end ifinfo +@iftex +The manual is divided into three major parts:@: the ``Getting +Started'' chapter you are reading now, the Calc tutorial (chapter 2), +and the Calc reference manual (the remaining chapters and appendices). +@c [when-split] +@c This manual has been printed in two volumes, the @dfn{Tutorial} and the +@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started'' +@c chapter. +@end iftex + +If you are in a hurry to use Calc, there is a brief ``demonstration'' +below which illustrates the major features of Calc in just a couple of +pages. If you don't have time to go through the full tutorial, this +will show you everything you need to know to begin. +@xref{Demonstration of Calc}. + +The tutorial chapter walks you through the various parts of Calc +with lots of hands-on examples and explanations. If you are new +to Calc and you have some time, try going through at least the +beginning of the tutorial. The tutorial includes about 70 exercises +with answers. These exercises give you some guided practice with +Calc, as well as pointing out some interesting and unusual ways +to use its features. + +The reference section discusses Calc in complete depth. You can read +the reference from start to finish if you want to learn every aspect +of Calc. Or, you can look in the table of contents or the Concept +Index to find the parts of the manual that discuss the things you +need to know. + +@cindex Marginal notes +Every Calc keyboard command is listed in the Calc Summary, and also +in the Key Index. Algebraic functions, @kbd{M-x} commands, and +variables also have their own indices. @c{Each} +@asis{In the printed manual, each} +paragraph that is referenced in the Key or Function Index is marked +in the margin with its index entry. + +@c [fix-ref Help Commands] +You can access this manual on-line at any time within Calc by +pressing the @kbd{h i} key sequence. Outside of the Calc window, +you can press @kbd{M-# i} to read the manual on-line. Also, you +can jump directly to the Tutorial by pressing @kbd{h t} or @kbd{M-# t}, +or to the Summary by pressing @kbd{h s} or @kbd{M-# s}. Within Calc, +you can also go to the part of the manual describing any Calc key, +function, or variable using @w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, +respectively. @xref{Help Commands}. + +Printed copies of this manual are also available from the Free Software +Foundation. + +@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started +@section Notations Used in This Manual + +@noindent +This section describes the various notations that are used +throughout the Calc manual. + +In keystroke sequences, uppercase letters mean you must hold down +the shift key while typing the letter. Keys pressed with Control +held down are shown as @kbd{C-x}. Keys pressed with Meta held down +are shown as @kbd{M-x}. Other notations are @key{RET} for the +Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key, +@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key. + +(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard, +the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively. +If you don't have a Meta key, look for Alt or Extend Char. You can +also press @key{ESC} or @key{C-[} first to get the same effect, so +that @kbd{M-x}, @kbd{ESC x}, and @kbd{C-[ x} are all equivalent.) + +Sometimes the @key{RET} key is not shown when it is ``obvious'' +that you must press @kbd{RET} to proceed. For example, the @key{RET} +is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}. + +Commands are generally shown like this: @kbd{p} (@code{calc-precision}) +or @kbd{M-# k} (@code{calc-keypad}). This means that the command is +normally used by pressing the @kbd{p} key or @kbd{M-# k} key sequence, +but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}. + +Commands that correspond to functions in algebraic notation +are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means +the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that +the corresponding function in an algebraic-style formula would +be @samp{cos(@var{x})}. + +A few commands don't have key equivalents: @code{calc-sincos} +[@code{sincos}].@refill + +@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started +@section A Demonstration of Calc + +@noindent +@cindex Demonstration of Calc +This section will show some typical small problems being solved with +Calc. The focus is more on demonstration than explanation, but +everything you see here will be covered more thoroughly in the +Tutorial. + +To begin, start Emacs if necessary (usually the command @code{emacs} +does this), and type @kbd{M-# c} (or @kbd{ESC # c}) to start the +Calculator. (@xref{Starting Calc}, if this doesn't work for you.) + +Be sure to type all the sample input exactly, especially noting the +difference between lower-case and upper-case letters. Remember, +@kbd{RET}, @kbd{TAB}, @kbd{DEL}, and @kbd{SPC} are the Return, Tab, +Delete, and Space keys. + +@strong{RPN calculation.} In RPN, you type the input number(s) first, +then the command to operate on the numbers. + +@noindent +Type @kbd{2 RET 3 + Q} to compute @c{$\sqrt{2+3} = 2.2360679775$} +@asis{the square root of 2+3, which is 2.2360679775}. + +@noindent +Type @kbd{P 2 ^} to compute @c{$\pi^2 = 9.86960440109$} +@asis{the value of `pi' squared, 9.86960440109}. + +@noindent +Type @kbd{TAB} to exchange the order of these two results. + +@noindent +Type @kbd{- I H S} to subtract these results and compute the Inverse +Hyperbolic sine of the difference, 2.72996136574. + +@noindent +Type @kbd{DEL} to erase this result. + +@strong{Algebraic calculation.} You can also enter calculations using +conventional ``algebraic'' notation. To enter an algebraic formula, +use the apostrophe key. + +@noindent +Type @kbd{' sqrt(2+3) RET} to compute @c{$\sqrt{2+3}$} +@asis{the square root of 2+3}. + +@noindent +Type @kbd{' pi^2 RET} to enter @c{$\pi^2$} +@asis{`pi' squared}. To evaluate this symbolic +formula as a number, type @kbd{=}. + +@noindent +Type @kbd{' arcsinh($ - $$) RET} to subtract the second-most-recent +result from the most-recent and compute the Inverse Hyperbolic sine. + +@strong{Keypad mode.} If you are using the X window system, press +@w{@kbd{M-# k}} to get Keypad mode. (If you don't use X, skip to +the next section.) + +@noindent +Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT} +``buttons'' using your left mouse button. + +@noindent +Click on @key{PI}, @key{2}, and @t{y^x}. + +@noindent +Click on @key{INV}, then @key{ENTER} to swap the two results. + +@noindent +Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}. + +@noindent +Click on @key{<-} to erase the result, then click @key{OFF} to turn +the Keypad Calculator off. + +@strong{Grabbing data.} Type @kbd{M-# x} if necessary to exit Calc. +Now select the following numbers as an Emacs region: ``Mark'' the +front of the list by typing control-@kbd{SPC} or control-@kbd{@@} there, +then move to the other end of the list. (Either get this list from +the on-line copy of this manual, accessed by @w{@kbd{M-# i}}, or just +type these numbers into a scratch file.) Now type @kbd{M-# g} to +``grab'' these numbers into Calc. + +@group +@example +1.23 1.97 +1.6 2 +1.19 1.08 +@end example +@end group + +@noindent +The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.'' +Type @w{@kbd{V R +}} to compute the sum of these numbers. + +@noindent +Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute +the product of the numbers. + +@noindent +You can also grab data as a rectangular matrix. Place the cursor on +the upper-leftmost @samp{1} and set the mark, then move to just after +the lower-right @samp{8} and press @kbd{M-# r}. + +@noindent +Type @kbd{v t} to transpose this @c{$3\times2$} +@asis{3x2} matrix into a @c{$2\times3$} +@asis{2x3} matrix. Type +@w{@kbd{v u}} to unpack the rows into two separate vectors. Now type +@w{@kbd{V R + TAB V R +}} to compute the sums of the two original columns. +(There is also a special grab-and-sum-columns command, @kbd{M-# :}.) + +@strong{Units conversion.} Units are entered algebraically. +Type @w{@kbd{' 43 mi/hr RET}} to enter the quantity 43 miles-per-hour. +Type @w{@kbd{u c km/hr RET}}. Type @w{@kbd{u c m/s RET}}. + +@strong{Date arithmetic.} Type @kbd{t N} to get the current date and +time. Type @kbd{90 +} to find the date 90 days from now. Type +@kbd{' <25 dec 87> RET} to enter a date, then @kbd{- 7 /} to see how +many weeks have passed since then. + +@strong{Algebra.} Algebraic entries can also include formulas +or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] RET} +to enter a pair of equations involving three variables. +(Note the leading apostrophe in this example; also, note that the space +between @samp{x y} is required.) Type @w{@kbd{a S x,y RET}} to solve +these equations for the variables @cite{x} and @cite{y}.@refill + +@noindent +Type @kbd{d B} to view the solutions in more readable notation. +Type @w{@kbd{d C}} to view them in C language notation, and @kbd{d T} +to view them in the notation for the @TeX{} typesetting system. +Type @kbd{d N} to return to normal notation. + +@noindent +Type @kbd{7.5}, then @kbd{s l a RET} to let @cite{a = 7.5} in these formulas. +(That's a letter @kbd{l}, not a numeral @kbd{1}.) + +@iftex +@strong{Help functions.} You can read about any command in the on-line +manual. Type @kbd{M-# c} to return to Calc after each of these +commands: @kbd{h k t N} to read about the @kbd{t N} command, +@kbd{h f sqrt RET} to read about the @code{sqrt} function, and +@kbd{h s} to read the Calc summary. +@end iftex +@ifinfo +@strong{Help functions.} You can read about any command in the on-line +manual. Remember to type the letter @kbd{l}, then @kbd{M-# c}, to +return here after each of these commands: @w{@kbd{h k t N}} to read +about the @w{@kbd{t N}} command, @kbd{h f sqrt RET} to read about the +@code{sqrt} function, and @kbd{h s} to read the Calc summary. +@end ifinfo + +Press @kbd{DEL} repeatedly to remove any leftover results from the stack. +To exit from Calc, press @kbd{q} or @kbd{M-# c} again. + +@node Using Calc, History and Acknowledgements, Demonstration of Calc, Getting Started +@section Using Calc + +@noindent +Calc has several user interfaces that are specialized for +different kinds of tasks. As well as Calc's standard interface, +there are Quick Mode, Keypad Mode, and Embedded Mode. + +@c [fix-ref Installation] +Calc must be @dfn{installed} before it can be used. @xref{Installation}, +for instructions on setting up and installing Calc. We will assume +you or someone on your system has already installed Calc as described +there. + +@menu +* Starting Calc:: +* The Standard Interface:: +* Quick Mode Overview:: +* Keypad Mode Overview:: +* Standalone Operation:: +* Embedded Mode Overview:: +* Other M-# Commands:: +@end menu + +@node Starting Calc, The Standard Interface, Using Calc, Using Calc +@subsection Starting Calc + +@noindent +On most systems, you can type @kbd{M-#} to start the Calculator. +The notation @kbd{M-#} is short for Meta-@kbd{#}. On most +keyboards this means holding down the Meta (or Alt) and +Shift keys while typing @kbd{3}. + +@cindex META key +Once again, if you don't have a Meta key on your keyboard you can type +@key{ESC} first, then @kbd{#}, to accomplish the same thing. If you +don't even have an @key{ESC} key, you can fake it by holding down +Control or @key{CTRL} while typing a left square bracket +(that's @kbd{C-[} in Emacs notation).@refill + +@kbd{M-#} is a @dfn{prefix key}; when you press it, Emacs waits for +you to press a second key to complete the command. In this case, +you will follow @kbd{M-#} with a letter (upper- or lower-case, it +doesn't matter for @kbd{M-#}) that says which Calc interface you +want to use. + +To get Calc's standard interface, type @kbd{M-# c}. To get +Keypad Mode, type @kbd{M-# k}. Type @kbd{M-# ?} to get a brief +list of the available options, and type a second @kbd{?} to get +a complete list. + +To ease typing, @kbd{M-# M-#} (or @kbd{M-# #} if that's easier) +also works to start Calc. It starts the same interface (either +@kbd{M-# c} or @w{@kbd{M-# k}}) that you last used, selecting the +@kbd{M-# c} interface by default. (If your installation has +a special function key set up to act like @kbd{M-#}, hitting that +function key twice is just like hitting @kbd{M-# M-#}.) + +If @kbd{M-#} doesn't work for you, you can always type explicit +commands like @kbd{M-x calc} (for the standard user interface) or +@w{@kbd{M-x calc-keypad}} (for Keypad Mode). First type @kbd{M-x} +(that's Meta with the letter @kbd{x}), then, at the prompt, +type the full command (like @kbd{calc-keypad}) and press Return. + +If you type @kbd{M-x calc} and Emacs still doesn't recognize the +command (it will say @samp{[No match]} when you try to press +@key{RET}), then Calc has not been properly installed. + +The same commands (like @kbd{M-# c} or @kbd{M-# M-#}) that start +the Calculator also turn it off if it is already on. + +@node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc +@subsection The Standard Calc Interface + +@noindent +@cindex Standard user interface +Calc's standard interface acts like a traditional RPN calculator, +operated by the normal Emacs keyboard. When you type @kbd{M-# c} +to start the Calculator, the Emacs screen splits into two windows +with the file you were editing on top and Calc on the bottom. + +@group +@iftex +@advance@hsize20pt +@end iftex +@smallexample + +... +--**-Emacs: myfile (Fundamental)----All---------------------- +--- Emacs Calculator Mode --- |Emacs Calc Mode v2.00... +2: 17.3 | 17.3 +1: -5 | 3 + . | 2 + | 4 + | * 8 + | ->-5 + | +--%%-Calc: 12 Deg (Calculator)----All----- --%%-Emacs: *Calc Trail* +@end smallexample +@end group + +In this figure, the mode-line for @file{myfile} has moved up and the +``Calculator'' window has appeared below it. As you can see, Calc +actually makes two windows side-by-side. The lefthand one is +called the @dfn{stack window} and the righthand one is called the +@dfn{trail window.} The stack holds the numbers involved in the +calculation you are currently performing. The trail holds a complete +record of all calculations you have done. In a desk calculator with +a printer, the trail corresponds to the paper tape that records what +you do. + +In this case, the trail shows that four numbers (17.3, 3, 2, and 4) +were first entered into the Calculator, then the 2 and 4 were +multiplied to get 8, then the 3 and 8 were subtracted to get @i{-5}. +(The @samp{>} symbol shows that this was the most recent calculation.) +The net result is the two numbers 17.3 and @i{-5} sitting on the stack. + +Most Calculator commands deal explicitly with the stack only, but +there is a set of commands that allow you to search back through +the trail and retrieve any previous result. + +Calc commands use the digits, letters, and punctuation keys. +Shifted (i.e., upper-case) letters are different from lowercase +letters. Some letters are @dfn{prefix} keys that begin two-letter +commands. For example, @kbd{e} means ``enter exponent'' and shifted +@kbd{E} means @cite{e^x}. With the @kbd{d} (``display modes'') prefix +the letter ``e'' takes on very different meanings: @kbd{d e} means +``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.'' + +There is nothing stopping you from switching out of the Calc +window and back into your editing window, say by using the Emacs +@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is +inside a regular window, Emacs acts just like normal. When the +cursor is in the Calc stack or trail windows, keys are interpreted +as Calc commands. + +When you quit by pressing @kbd{M-# c} a second time, the Calculator +windows go away but the actual Stack and Trail are not gone, just +hidden. When you press @kbd{M-# c} once again you will get the +same stack and trail contents you had when you last used the +Calculator. + +The Calculator does not remember its state between Emacs sessions. +Thus if you quit Emacs and start it again, @kbd{M-# c} will give you +a fresh stack and trail. There is a command (@kbd{m m}) that lets +you save your favorite mode settings between sessions, though. +One of the things it saves is which user interface (standard or +Keypad) you last used; otherwise, a freshly started Emacs will +always treat @kbd{M-# M-#} the same as @kbd{M-# c}. + +The @kbd{q} key is another equivalent way to turn the Calculator off. + +If you type @kbd{M-# b} first and then @kbd{M-# c}, you get a +full-screen version of Calc (@code{full-calc}) in which the stack and +trail windows are still side-by-side but are now as tall as the whole +Emacs screen. When you press @kbd{q} or @kbd{M-# c} again to quit, +the file you were editing before reappears. The @kbd{M-# b} key +switches back and forth between ``big'' full-screen mode and the +normal partial-screen mode. + +Finally, @kbd{M-# o} (@code{calc-other-window}) is like @kbd{M-# c} +except that the Calc window is not selected. The buffer you were +editing before remains selected instead. @kbd{M-# o} is a handy +way to switch out of Calc momentarily to edit your file; type +@kbd{M-# c} to switch back into Calc when you are done. + +@node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc +@subsection Quick Mode (Overview) + +@noindent +@dfn{Quick Mode} is a quick way to use Calc when you don't need the +full complexity of the stack and trail. To use it, type @kbd{M-# q} +(@code{quick-calc}) in any regular editing buffer. + +Quick Mode is very simple: It prompts you to type any formula in +standard algebraic notation (like @samp{4 - 2/3}) and then displays +the result at the bottom of the Emacs screen (@i{3.33333333333} +in this case). You are then back in the same editing buffer you +were in before, ready to continue editing or to type @kbd{M-# q} +again to do another quick calculation. The result of the calculation +will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command +at this point will yank the result into your editing buffer. + +Calc mode settings affect Quick Mode, too, though you will have to +go into regular Calc (with @kbd{M-# c}) to change the mode settings. + +@c [fix-ref Quick Calculator mode] +@xref{Quick Calculator}, for further information. + +@node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc +@subsection Keypad Mode (Overview) + +@noindent +@dfn{Keypad Mode} is a mouse-based interface to the Calculator. +It is designed for use with the X window system. If you don't +have X, you will have to operate keypad mode with your arrow +keys (which is probably more trouble than it's worth). Keypad +mode is currently not supported under Emacs 19. + +Type @kbd{M-# k} to turn Keypad Mode on or off. Once again you +get two new windows, this time on the righthand side of the screen +instead of at the bottom. The upper window is the familiar Calc +Stack; the lower window is a picture of a typical calculator keypad. + +@tex +\dimen0=\pagetotal% +\advance \dimen0 by 24\baselineskip% +\ifdim \dimen0>\pagegoal \vfill\eject \fi% +\medskip +@end tex +@smallexample + |--- Emacs Calculator Mode --- + |2: 17.3 + |1: -5 + | . + |--%%-Calc: 12 Deg (Calcul + |----+-----Calc 2.00-----+----1 + |FLR |CEIL|RND |TRNC|CLN2|FLT | + |----+----+----+----+----+----| + | LN |EXP | |ABS |IDIV|MOD | + |----+----+----+----+----+----| + |SIN |COS |TAN |SQRT|y^x |1/x | + |----+----+----+----+----+----| + | ENTER |+/- |EEX |UNDO| <- | + |-----+---+-+--+--+-+---++----| + | INV | 7 | 8 | 9 | / | + |-----+-----+-----+-----+-----| + | HYP | 4 | 5 | 6 | * | + |-----+-----+-----+-----+-----| + |EXEC | 1 | 2 | 3 | - | + |-----+-----+-----+-----+-----| + | OFF | 0 | . | PI | + | + |-----+-----+-----+-----+-----+ +@end smallexample +@iftex +@begingroup +@ifdim@hsize=5in +@vskip-3.7in +@advance@hsize-2.2in +@else +@vskip-3.89in +@advance@hsize-3.05in +@advance@vsize.1in +@fi +@end iftex + +Keypad Mode is much easier for beginners to learn, because there +is no need to memorize lots of obscure key sequences. But not all +commands in regular Calc are available on the Keypad. You can +always switch the cursor into the Calc stack window to use +standard Calc commands if you need. Serious Calc users, though, +often find they prefer the standard interface over Keypad Mode. + +To operate the Calculator, just click on the ``buttons'' of the +keypad using your left mouse button. To enter the two numbers +shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to +add them together you would then click @kbd{+} (to get 12.3 on +the stack). + +If you click the right mouse button, the top three rows of the +keypad change to show other sets of commands, such as advanced +math functions, vector operations, and operations on binary +numbers. + +@iftex +@endgroup +@end iftex +Because Keypad Mode doesn't use the regular keyboard, Calc leaves +the cursor in your original editing buffer. You can type in +this buffer in the usual way while also clicking on the Calculator +keypad. One advantage of Keypad Mode is that you don't need an +explicit command to switch between editing and calculating. + +If you press @kbd{M-# b} first, you get a full-screen Keypad Mode +(@code{full-calc-keypad}) with three windows: The keypad in the lower +left, the stack in the lower right, and the trail on top. + +@c [fix-ref Keypad Mode] +@xref{Keypad Mode}, for further information. + +@node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc +@subsection Standalone Operation + +@noindent +@cindex Standalone Operation +If you are not in Emacs at the moment but you wish to use Calc, +you must start Emacs first. If all you want is to run Calc, you +can give the commands: + +@example +emacs -f full-calc +@end example + +@noindent +or + +@example +emacs -f full-calc-keypad +@end example + +@noindent +which run a full-screen Calculator (as if by @kbd{M-# b M-# c}) or +a full-screen X-based Calculator (as if by @kbd{M-# b M-# k}). +In standalone operation, quitting the Calculator (by pressing +@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs +itself. + +@node Embedded Mode Overview, Other M-# Commands, Standalone Operation, Using Calc +@subsection Embedded Mode (Overview) + +@noindent +@dfn{Embedded Mode} is a way to use Calc directly from inside an +editing buffer. Suppose you have a formula written as part of a +document like this: + +@group +@smallexample +The derivative of + + ln(ln(x)) + +is +@end smallexample +@end group + +@noindent +and you wish to have Calc compute and format the derivative for +you and store this derivative in the buffer automatically. To +do this with Embedded Mode, first copy the formula down to where +you want the result to be: + +@group +@smallexample +The derivative of + + ln(ln(x)) + +is + + ln(ln(x)) +@end smallexample +@end group + +Now, move the cursor onto this new formula and press @kbd{M-# e}. +Calc will read the formula (using the surrounding blank lines to +tell how much text to read), then push this formula (invisibly) +onto the Calc stack. The cursor will stay on the formula in the +editing buffer, but the buffer's mode line will change to look +like the Calc mode line (with mode indicators like @samp{12 Deg} +and so on). Even though you are still in your editing buffer, +the keyboard now acts like the Calc keyboard, and any new result +you get is copied from the stack back into the buffer. To take +the derivative, you would type @kbd{a d x @key{RET}}. + +@group +@smallexample +The derivative of + + ln(ln(x)) + +is + +1 / ln(x) x +@end smallexample +@end group + +To make this look nicer, you might want to press @kbd{d =} to center +the formula, and even @kbd{d B} to use ``big'' display mode. + +@group +@smallexample +The derivative of + + ln(ln(x)) + +is +% [calc-mode: justify: center] +% [calc-mode: language: big] + + 1 + ------- + ln(x) x +@end smallexample +@end group + +Calc has added annotations to the file to help it remember the modes +that were used for this formula. They are formatted like comments +in the @TeX{} typesetting language, just in case you are using @TeX{}. +(In this example @TeX{} is not being used, so you might want to move +these comments up to the top of the file or otherwise put them out +of the way.) + +As an extra flourish, we can add an equation number using a +righthand label: Type @kbd{d @} (1) RET}. + +@group +@smallexample +% [calc-mode: justify: center] +% [calc-mode: language: big] +% [calc-mode: right-label: " (1)"] + + 1 + ------- (1) + ln(x) x +@end smallexample +@end group + +To leave Embedded Mode, type @kbd{M-# e} again. The mode line +and keyboard will revert to the way they were before. (If you have +actually been trying this as you read along, you'll want to press +@kbd{M-# 0} [with the digit zero] now to reset the modes you changed.) + +The related command @kbd{M-# w} operates on a single word, which +generally means a single number, inside text. It uses any +non-numeric characters rather than blank lines to delimit the +formula it reads. Here's an example of its use: + +@smallexample +A slope of one-third corresponds to an angle of 1 degrees. +@end smallexample + +Place the cursor on the @samp{1}, then type @kbd{M-# w} to enable +Embedded Mode on that number. Now type @kbd{3 /} (to get one-third), +and @kbd{I T} (the Inverse Tangent converts a slope into an angle), +then @w{@kbd{M-# w}} again to exit Embedded mode. + +@smallexample +A slope of one-third corresponds to an angle of 18.4349488229 degrees. +@end smallexample + +@c [fix-ref Embedded Mode] +@xref{Embedded Mode}, for full details. + +@node Other M-# Commands, , Embedded Mode Overview, Using Calc +@subsection Other @kbd{M-#} Commands + +@noindent +Two more Calc-related commands are @kbd{M-# g} and @kbd{M-# r}, +which ``grab'' data from a selected region of a buffer into the +Calculator. The region is defined in the usual Emacs way, by +a ``mark'' placed at one end of the region, and the Emacs +cursor or ``point'' placed at the other. + +The @kbd{M-# g} command reads the region in the usual left-to-right, +top-to-bottom order. The result is packaged into a Calc vector +of numbers and placed on the stack. Calc (in its standard +user interface) is then started. Type @kbd{v u} if you want +to unpack this vector into separate numbers on the stack. Also, +@kbd{C-u M-# g} interprets the region as a single number or +formula. + +The @kbd{M-# r} command reads a rectangle, with the point and +mark defining opposite corners of the rectangle. The result +is a matrix of numbers on the Calculator stack. + +Complementary to these is @kbd{M-# y}, which ``yanks'' the +value at the top of the Calc stack back into an editing buffer. +If you type @w{@kbd{M-# y}} while in such a buffer, the value is +yanked at the current position. If you type @kbd{M-# y} while +in the Calc buffer, Calc makes an educated guess as to which +editing buffer you want to use. The Calc window does not have +to be visible in order to use this command, as long as there +is something on the Calc stack. + +Here, for reference, is the complete list of @kbd{M-#} commands. +The shift, control, and meta keys are ignored for the keystroke +following @kbd{M-#}. + +@noindent +Commands for turning Calc on and off: + +@table @kbd +@item # +Turn Calc on or off, employing the same user interface as last time. + +@item C +Turn Calc on or off using its standard bottom-of-the-screen +interface. If Calc is already turned on but the cursor is not +in the Calc window, move the cursor into the window. + +@item O +Same as @kbd{C}, but don't select the new Calc window. If +Calc is already turned on and the cursor is in the Calc window, +move it out of that window. + +@item B +Control whether @kbd{M-# c} and @kbd{M-# k} use the full screen. + +@item Q +Use Quick Mode for a single short calculation. + +@item K +Turn Calc Keypad mode on or off. + +@item E +Turn Calc Embedded mode on or off at the current formula. + +@item J +Turn Calc Embedded mode on or off, select the interesting part. + +@item W +Turn Calc Embedded mode on or off at the current word (number). + +@item Z +Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command. + +@item X +Quit Calc; turn off standard, Keypad, or Embedded mode if on. +(This is like @kbd{q} or @key{OFF} inside of Calc.) +@end table +@iftex +@sp 2 +@end iftex + +@group +@noindent +Commands for moving data into and out of the Calculator: + +@table @kbd +@item G +Grab the region into the Calculator as a vector. + +@item R +Grab the rectangular region into the Calculator as a matrix. + +@item : +Grab the rectangular region and compute the sums of its columns. + +@item _ +Grab the rectangular region and compute the sums of its rows. + +@item Y +Yank a value from the Calculator into the current editing buffer. +@end table +@iftex +@sp 2 +@end iftex +@end group + +@group +@noindent +Commands for use with Embedded Mode: + +@table @kbd +@item A +``Activate'' the current buffer. Locate all formulas that +contain @samp{:=} or @samp{=>} symbols and record their locations +so that they can be updated automatically as variables are changed. + +@item D +Duplicate the current formula immediately below and select +the duplicate. + +@item F +Insert a new formula at the current point. + +@item N +Move the cursor to the next active formula in the buffer. + +@item P +Move the cursor to the previous active formula in the buffer. + +@item U +Update (i.e., as if by the @kbd{=} key) the formula at the current point. + +@item ` +Edit (as if by @code{calc-edit}) the formula at the current point. +@end table +@iftex +@sp 2 +@end iftex +@end group + +@group +@noindent +Miscellaneous commands: + +@table @kbd +@item I +Run the Emacs Info system to read the Calc manual. +(This is the same as @kbd{h i} inside of Calc.) + +@item T +Run the Emacs Info system to read the Calc Tutorial. + +@item S +Run the Emacs Info system to read the Calc Summary. + +@item L +Load Calc entirely into memory. (Normally the various parts +are loaded only as they are needed.) + +@item M +Read a region of written keystroke names (like @samp{C-n a b c RET}) +and record them as the current keyboard macro. + +@item 0 +(This is the ``zero'' digit key.) Reset the Calculator to +its default state: Empty stack, and default mode settings. +With any prefix argument, reset everything but the stack. +@end table +@end group + +@node History and Acknowledgements, , Using Calc, Getting Started +@section History and Acknowledgements + +@noindent +Calc was originally started as a two-week project to occupy a lull +in the author's schedule. Basically, a friend asked if I remembered +the value of @c{$2^{32}$} +@cite{2^32}. I didn't offhand, but I said, ``that's +easy, just call up an @code{xcalc}.'' @code{Xcalc} duly reported +that the answer to our question was @samp{4.294967e+09}---with no way to +see the full ten digits even though we knew they were there in the +program's memory! I was so annoyed, I vowed to write a calculator +of my own, once and for all. + +I chose Emacs Lisp, a) because I had always been curious about it +and b) because, being only a text editor extension language after +all, Emacs Lisp would surely reach its limits long before the project +got too far out of hand. + +To make a long story short, Emacs Lisp turned out to be a distressingly +solid implementation of Lisp, and the humble task of calculating +turned out to be more open-ended than one might have expected. + +Emacs Lisp doesn't have built-in floating point math, so it had to be +simulated in software. In fact, Emacs integers will only comfortably +fit six decimal digits or so---not enough for a decent calculator. So +I had to write my own high-precision integer code as well, and once I had +this I figured that arbitrary-size integers were just as easy as large +integers. Arbitrary floating-point precision was the logical next step. +Also, since the large integer arithmetic was there anyway it seemed only +fair to give the user direct access to it, which in turn made it practical +to support fractions as well as floats. All these features inspired me +to look around for other data types that might be worth having. + +Around this time, my friend Rick Koshi showed me his nifty new HP-28 +calculator. It allowed the user to manipulate formulas as well as +numerical quantities, and it could also operate on matrices. I decided +that these would be good for Calc to have, too. And once things had +gone this far, I figured I might as well take a look at serious algebra +systems like Mathematica, Macsyma, and Maple for further ideas. Since +these systems did far more than I could ever hope to implement, I decided +to focus on rewrite rules and other programming features so that users +could implement what they needed for themselves. + +Rick complained that matrices were hard to read, so I put in code to +format them in a 2D style. Once these routines were in place, Big mode +was obligatory. Gee, what other language modes would be useful? + +Scott Hemphill and Allen Knutson, two friends with a strong mathematical +bent, contributed ideas and algorithms for a number of Calc features +including modulo forms, primality testing, and float-to-fraction conversion. + +Units were added at the eager insistence of Mass Sivilotti. Later, +Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable +expert assistance with the units table. As far as I can remember, the +idea of using algebraic formulas and variables to represent units dates +back to an ancient article in Byte magazine about muMath, an early +algebra system for microcomputers. + +Many people have contributed to Calc by reporting bugs and suggesting +features, large and small. A few deserve special mention: Tim Peters, +who helped develop the ideas that led to the selection commands, rewrite +rules, and many other algebra features; @c{Fran\c cois} +@asis{Francois} Pinard, who contributed +an early prototype of the Calc Summary appendix as well as providing +valuable suggestions in many other areas of Calc; Carl Witty, whose eagle +eyes discovered many typographical and factual errors in the Calc manual; +Tim Kay, who drove the development of Embedded mode; Ove Ewerlid, who +made many suggestions relating to the algebra commands and contributed +some code for polynomial operations; Randal Schwartz, who suggested the +@code{calc-eval} function; Robert J. Chassell, who suggested the Calc +Tutorial and exercises; and Juha Sarlin, who first worked out how to split +Calc into quickly-loading parts. Bob Weiner helped immensely with the +Lucid Emacs port. + +@cindex Bibliography +@cindex Knuth, Art of Computer Programming +@cindex Numerical Recipes +@c Should these be expanded into more complete references? +Among the books used in the development of Calc were Knuth's @emph{Art +of Computer Programming} (especially volume II, @emph{Seminumerical +Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky, +and Vetterling; Bevington's @emph{Data Reduction and Error Analysis for +the Physical Sciences}; @emph{Concrete Mathematics} by Graham, Knuth, +and Patashnik; Steele's @emph{Common Lisp, the Language}; the @emph{CRC +Standard Math Tables} (William H. Beyer, ed.); and Abramowitz and +Stegun's venerable @emph{Handbook of Mathematical Functions}. I +consulted the user's manuals for the HP-28 and HP-48 calculators, as +well as for the programs Mathematica, SMP, Macsyma, Maple, MathCAD, +Gnuplot, and others. Also, of course, Calc could not have been written +without the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil +Lewis and Dan LaLiberte. + +Final thanks go to Richard Stallman, without whose fine implementations +of the Emacs editor, language, and environment, Calc would have been +finished in two weeks. + +@c [tutorial] + +@ifinfo +@c This node is accessed by the `M-# t' command. +@node Interactive Tutorial, , , Top +@chapter Tutorial + +@noindent +Some brief instructions on using the Emacs Info system for this tutorial: + +Press the space bar and Delete keys to go forward and backward in a +section by screenfuls (or use the regular Emacs scrolling commands +for this). + +Press @kbd{n} or @kbd{p} to go to the Next or Previous section. +If the section has a @dfn{menu}, press a digit key like @kbd{1} +or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to +go back up from a sub-section to the menu it is part of. + +Exercises in the tutorial all have cross-references to the +appropriate page of the ``answers'' section. Press @kbd{f}, then +the exercise number, to see the answer to an exercise. After +you have followed a cross-reference, you can press the letter +@kbd{l} to return to where you were before. + +You can press @kbd{?} at any time for a brief summary of Info commands. + +Press @kbd{1} now to enter the first section of the Tutorial. + +@menu +* Tutorial:: +@end menu +@end ifinfo + +@node Tutorial, Introduction, Getting Started, Top +@chapter Tutorial + +@noindent +This chapter explains how to use Calc and its many features, in +a step-by-step, tutorial way. You are encouraged to run Calc and +work along with the examples as you read (@pxref{Starting Calc}). +If you are already familiar with advanced calculators, you may wish +@c [not-split] +to skip on to the rest of this manual. +@c [when-split] +@c to skip on to volume II of this manual, the @dfn{Calc Reference}. + +@c [fix-ref Embedded Mode] +This tutorial describes the standard user interface of Calc only. +The ``Quick Mode'' and ``Keypad Mode'' interfaces are fairly +self-explanatory. @xref{Embedded Mode}, for a description of +the ``Embedded Mode'' interface. + +@ifinfo +The easiest way to read this tutorial on-line is to have two windows on +your Emacs screen, one with Calc and one with the Info system. (If you +have a printed copy of the manual you can use that instead.) Press +@kbd{M-# c} to turn Calc on or to switch into the Calc window, and +press @kbd{M-# i} to start the Info system or to switch into its window. +Or, you may prefer to use the tutorial in printed form. +@end ifinfo +@iftex +The easiest way to read this tutorial on-line is to have two windows on +your Emacs screen, one with Calc and one with the Info system. (If you +have a printed copy of the manual you can use that instead.) Press +@kbd{M-# c} to turn Calc on or to switch into the Calc window, and +press @kbd{M-# i} to start the Info system or to switch into its window. +@end iftex + +This tutorial is designed to be done in sequence. But the rest of this +manual does not assume you have gone through the tutorial. The tutorial +does not cover everything in the Calculator, but it touches on most +general areas. + +@ifinfo +You may wish to print out a copy of the Calc Summary and keep notes on +it as you learn Calc. @xref{Installation}, to see how to make a printed +summary. @xref{Summary}. +@end ifinfo +@iftex +The Calc Summary at the end of the reference manual includes some blank +space for your own use. You may wish to keep notes there as you learn +Calc. +@end iftex + +@menu +* Basic Tutorial:: +* Arithmetic Tutorial:: +* Vector/Matrix Tutorial:: +* Types Tutorial:: +* Algebra Tutorial:: +* Programming Tutorial:: + +* Answers to Exercises:: +@end menu + +@node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial +@section Basic Tutorial + +@noindent +In this section, we learn how RPN and algebraic-style calculations +work, how to undo and redo an operation done by mistake, and how +to control various modes of the Calculator. + +@menu +* RPN Tutorial:: Basic operations with the stack. +* Algebraic Tutorial:: Algebraic entry; variables. +* Undo Tutorial:: If you make a mistake: Undo and the trail. +* Modes Tutorial:: Common mode-setting commands. +@end menu + +@node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial +@subsection RPN Calculations and the Stack + +@cindex RPN notation +@ifinfo +@noindent +Calc normally uses RPN notation. You may be familiar with the RPN +system from Hewlett-Packard calculators, FORTH, or PostScript. +(Reverse Polish Notation, RPN, is named after the Polish mathematician +Jan Lukasiewicz.) +@end ifinfo +@tex +\noindent +Calc normally uses RPN notation. You may be familiar with the RPN +system from Hewlett-Packard calculators, FORTH, or PostScript. +(Reverse Polish Notation, RPN, is named after the Polish mathematician +Jan \L ukasiewicz.) +@end tex + +The central component of an RPN calculator is the @dfn{stack}. A +calculator stack is like a stack of dishes. New dishes (numbers) are +added at the top of the stack, and numbers are normally only removed +from the top of the stack. + +@cindex Operators +@cindex Operands +In an operation like @cite{2+3}, the 2 and 3 are called the @dfn{operands} +and the @cite{+} is the @dfn{operator}. In an RPN calculator you always +enter the operands first, then the operator. Each time you type a +number, Calc adds or @dfn{pushes} it onto the top of the Stack. +When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate +number of operands from the stack and pushes back the result. + +Thus we could add the numbers 2 and 3 in an RPN calculator by typing: +@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to +the @key{ENTER} key on traditional RPN calculators.) Try this now if +you wish; type @kbd{M-# c} to switch into the Calc window (you can type +@kbd{M-# c} again or @kbd{M-# o} to switch back to the Tutorial window). +The first four keystrokes ``push'' the numbers 2 and 3 onto the stack. +The @kbd{+} key ``pops'' the top two numbers from the stack, adds them, +and pushes the result (5) back onto the stack. Here's how the stack +will look at various points throughout the calculation:@refill + +@group +@smallexample + . 1: 2 2: 2 1: 5 . + . 1: 3 . + . + + M-# c 2 RET 3 RET + DEL +@end smallexample +@end group + +The @samp{.} symbol is a marker that represents the top of the stack. +Note that the ``top'' of the stack is really shown at the bottom of +the Stack window. This may seem backwards, but it turns out to be +less distracting in regular use. + +@cindex Stack levels +@cindex Levels of stack +The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level +numbers}. Old RPN calculators always had four stack levels called +@cite{x}, @cite{y}, @cite{z}, and @cite{t}. Calc's stack can grow +as large as you like, so it uses numbers instead of letters. Some +stack-manipulation commands accept a numeric argument that says +which stack level to work on. Normal commands like @kbd{+} always +work on the top few levels of the stack.@refill + +@c [fix-ref Truncating the Stack] +The Stack buffer is just an Emacs buffer, and you can move around in +it using the regular Emacs motion commands. But no matter where the +cursor is, even if you have scrolled the @samp{.} marker out of +view, most Calc commands always move the cursor back down to level 1 +before doing anything. It is possible to move the @samp{.} marker +upwards through the stack, temporarily ``hiding'' some numbers from +commands like @kbd{+}. This is called @dfn{stack truncation} and +we will not cover it in this tutorial; @pxref{Truncating the Stack}, +if you are interested. + +You don't really need the second @key{RET} in @kbd{2 @key{RET} 3 +@key{RET} +}. That's because if you type any operator name or +other non-numeric key when you are entering a number, the Calculator +automatically enters that number and then does the requested command. +Thus @kbd{2 @key{RET} 3 +} will work just as well.@refill + +Examples in this tutorial will often omit @key{RET} even when the +stack displays shown would only happen if you did press @key{RET}: + +@group +@smallexample +1: 2 2: 2 1: 5 + . 1: 3 . + . + + 2 RET 3 + +@end smallexample +@end group + +@noindent +Here, after pressing @kbd{3} the stack would really show @samp{1: 2} +with @samp{Calc:@: 3} in the minibuffer. In these situations, you can +press the optional @key{RET} to see the stack as the figure shows. + +(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises +at various points. Try them if you wish. Answers to all the exercises +are located at the end of the Tutorial chapter. Each exercise will +include a cross-reference to its particular answer. If you are +reading with the Emacs Info system, press @kbd{f} and the +exercise number to go to the answer, then the letter @kbd{l} to +return to where you were.) + +@noindent +Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2 +@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for +multiplication.) Figure it out by hand, then try it with Calc to see +if you're right. @xref{RPN Answer 1, 1}. (@bullet{}) + +(@bullet{}) @strong{Exercise 2.} Compute @c{$(2\times4) + (7\times9.4) + {5\over4}$} +@cite{2*4 + 7*9.5 + 5/4} using the +stack. @xref{RPN Answer 2, 2}. (@bullet{}) + +The @key{DEL} key is called Backspace on some keyboards. It is +whatever key you would use to correct a simple typing error when +regularly using Emacs. The @key{DEL} key pops and throws away the +top value on the stack. (You can still get that value back from +the Trail if you should need it later on.) There are many places +in this tutorial where we assume you have used @key{DEL} to erase the +results of the previous example at the beginning of a new example. +In the few places where it is really important to use @key{DEL} to +clear away old results, the text will remind you to do so. + +(It won't hurt to let things accumulate on the stack, except that +whenever you give a display-mode-changing command Calc will have to +spend a long time reformatting such a large stack.) + +Since the @kbd{-} key is also an operator (it subtracts the top two +stack elements), how does one enter a negative number? Calc uses +the @kbd{_} (underscore) key to act like the minus sign in a number. +So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key +will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine. + +You can also press @kbd{n}, which means ``change sign.'' It changes +the number at the top of the stack (or the number being entered) +from positive to negative or vice-versa: @kbd{5 n @key{RET}}. + +@cindex Duplicating a stack entry +If you press @key{RET} when you're not entering a number, the effect +is to duplicate the top number on the stack. Consider this calculation: + +@group +@smallexample +1: 3 2: 3 1: 9 2: 9 1: 81 + . 1: 3 . 1: 9 . + . . + + 3 RET RET * RET * +@end smallexample +@end group + +@noindent +(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^}, +to raise 3 to the fourth power.) + +The space-bar key (denoted @key{SPC} here) performs the same function +as @key{RET}; you could replace all three occurrences of @key{RET} in +the above example with @key{SPC} and the effect would be the same. + +@cindex Exchanging stack entries +Another stack manipulation key is @key{TAB}. This exchanges the top +two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +} +to get 5, and then you realize what you really wanted to compute +was @cite{20 / (2+3)}. + +@group +@smallexample +1: 5 2: 5 2: 20 1: 4 + . 1: 20 1: 5 . + . . + + 2 RET 3 + 20 TAB / +@end smallexample +@end group + +@noindent +Planning ahead, the calculation would have gone like this: + +@group +@smallexample +1: 20 2: 20 3: 20 2: 20 1: 4 + . 1: 2 2: 2 1: 5 . + . 1: 3 . + . + + 20 RET 2 RET 3 + / +@end smallexample +@end group + +A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type +@key{TAB}). It rotates the top three elements of the stack upward, +bringing the object in level 3 to the top. + +@group +@smallexample +1: 10 2: 10 3: 10 3: 20 3: 30 + . 1: 20 2: 20 2: 30 2: 10 + . 1: 30 1: 10 1: 20 + . . . + + 10 RET 20 RET 30 RET M-TAB M-TAB +@end smallexample +@end group + +(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are +on the stack. Figure out how to add one to the number in level 2 +without affecting the rest of the stack. Also figure out how to add +one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{}) + +Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two +arguments from the stack and push a result. Operations like @kbd{n} and +@kbd{Q} (square root) pop a single number and push the result. You can +think of them as simply operating on the top element of the stack. + +@group +@smallexample +1: 3 1: 9 2: 9 1: 25 1: 5 + . . 1: 16 . . + . + + 3 RET RET * 4 RET RET * + Q +@end smallexample +@end group + +@noindent +(Note that capital @kbd{Q} means to hold down the Shift key while +typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.) + +@cindex Pythagorean Theorem +Here we've used the Pythagorean Theorem to determine the hypotenuse of a +right triangle. Calc actually has a built-in command for that called +@kbd{f h}, but let's suppose we can't remember the necessary keystrokes. +We can still enter it by its full name using @kbd{M-x} notation: + +@group +@smallexample +1: 3 2: 3 1: 5 + . 1: 4 . + . + + 3 RET 4 RET M-x calc-hypot +@end smallexample +@end group + +All Calculator commands begin with the word @samp{calc-}. Since it +gets tiring to type this, Calc provides an @kbd{x} key which is just +like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-} +prefix for you: + +@group +@smallexample +1: 3 2: 3 1: 5 + . 1: 4 . + . + + 3 RET 4 RET x hypot +@end smallexample +@end group + +What happens if you take the square root of a negative number? + +@group +@smallexample +1: 4 1: -4 1: (0, 2) + . . . + + 4 RET n Q +@end smallexample +@end group + +@noindent +The notation @cite{(a, b)} represents a complex number. +Complex numbers are more traditionally written @c{$a + b i$} +@cite{a + b i}; +Calc can display in this format, too, but for now we'll stick to the +@cite{(a, b)} notation. + +If you don't know how complex numbers work, you can safely ignore this +feature. Complex numbers only arise from operations that would be +errors in a calculator that didn't have complex numbers. (For example, +taking the square root or logarithm of a negative number produces a +complex result.) + +Complex numbers are entered in the notation shown. The @kbd{(} and +@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.'' + +@group +@smallexample +1: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3) + . 1: 2 . 3 . + . . + + ( 2 , 3 ) +@end smallexample +@end group + +You can perform calculations while entering parts of incomplete objects. +However, an incomplete object cannot actually participate in a calculation: + +@group +@smallexample +1: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ... + . 1: 2 2: 2 5 5 + . 1: 3 . . + . + (error) + ( 2 RET 3 + + +@end smallexample +@end group + +@noindent +Adding 5 to an incomplete object makes no sense, so the last command +produces an error message and leaves the stack the same. + +Incomplete objects can't participate in arithmetic, but they can be +moved around by the regular stack commands. + +@group +@smallexample +2: 2 3: 2 3: 3 1: ( ... 1: (2, 3) +1: 3 2: 3 2: ( ... 2 . + . 1: ( ... 1: 2 3 + . . . + +2 RET 3 RET ( M-TAB M-TAB ) +@end smallexample +@end group + +@noindent +Note that the @kbd{,} (comma) key did not have to be used here. +When you press @kbd{)} all the stack entries between the incomplete +entry and the top are collected, so there's never really a reason +to use the comma. It's up to you. + +(@bullet{}) @strong{Exercise 4.} To enter the complex number @cite{(2, 3)}, +your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened? +(Joe thought of a clever way to correct his mistake in only two +keystrokes, but it didn't quite work. Try it to find out why.) +@xref{RPN Answer 4, 4}. (@bullet{}) + +Vectors are entered the same way as complex numbers, but with square +brackets in place of parentheses. We'll meet vectors again later in +the tutorial. + +Any Emacs command can be given a @dfn{numeric prefix argument} by +typing a series of @key{META}-digits beforehand. If @key{META} is +awkward for you, you can instead type @kbd{C-u} followed by the +necessary digits. Numeric prefix arguments can be negative, as in +@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric +prefix arguments in a variety of ways. For example, a numeric prefix +on the @kbd{+} operator adds any number of stack entries at once: + +@group +@smallexample +1: 10 2: 10 3: 10 3: 10 1: 60 + . 1: 20 2: 20 2: 20 . + . 1: 30 1: 30 + . . + + 10 RET 20 RET 30 RET C-u 3 + +@end smallexample +@end group + +For stack manipulation commands like @key{RET}, a positive numeric +prefix argument operates on the top @var{n} stack entries at once. A +negative argument operates on the entry in level @var{n} only. An +argument of zero operates on the entire stack. In this example, we copy +the second-to-top element of the stack: + +@group +@smallexample +1: 10 2: 10 3: 10 3: 10 4: 10 + . 1: 20 2: 20 2: 20 3: 20 + . 1: 30 1: 30 2: 30 + . . 1: 20 + . + + 10 RET 20 RET 30 RET C-u -2 RET +@end smallexample +@end group + +@cindex Clearing the stack +@cindex Emptying the stack +Another common idiom is @kbd{M-0 DEL}, which clears the stack. +(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the +entire stack.) + +@node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial +@subsection Algebraic-Style Calculations + +@noindent +If you are not used to RPN notation, you may prefer to operate the +Calculator in ``algebraic mode,'' which is closer to the way +non-RPN calculators work. In algebraic mode, you enter formulas +in traditional @cite{2+3} notation. + +You don't really need any special ``mode'' to enter algebraic formulas. +You can enter a formula at any time by pressing the apostrophe (@kbd{'}) +key. Answer the prompt with the desired formula, then press @key{RET}. +The formula is evaluated and the result is pushed onto the RPN stack. +If you don't want to think in RPN at all, you can enter your whole +computation as a formula, read the result from the stack, then press +@key{DEL} to delete it from the stack. + +Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}. +The result should be the number 9. + +Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*}, +@samp{/}, and @samp{^}. You can use parentheses to make the order +of evaluation clear. In the absence of parentheses, @samp{^} is +evaluated first, then @samp{*}, then @samp{/}, then finally +@samp{+} and @samp{-}. For example, the expression + +@example +2 + 3*4*5 / 6*7^8 - 9 +@end example + +@noindent +is equivalent to + +@example +2 + ((3*4*5) / (6*(7^8)) - 9 +@end example + +@noindent +or, in large mathematical notation, + +@ifinfo +@group +@example + 3 * 4 * 5 +2 + --------- - 9 + 8 + 6 * 7 +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$ +\afterdisplay +@end tex + +@noindent +The result of this expression will be the number @i{-6.99999826533}. + +Calc's order of evaluation is the same as for most computer languages, +except that @samp{*} binds more strongly than @samp{/}, as the above +example shows. As in normal mathematical notation, the @samp{*} symbol +can often be omitted: @samp{2 a} is the same as @samp{2*a}. + +Operators at the same level are evaluated from left to right, except +that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is +equivalent to @samp{(2-3)-4} or @i{-5}, whereas @samp{2^3^4} is equivalent +to @samp{2^(3^4)} (a very large integer; try it!). + +If you tire of typing the apostrophe all the time, there is an +``algebraic mode'' you can select in which Calc automatically senses +when you are about to type an algebraic expression. To enter this +mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator +should appear in the Calc window's mode line.) + +Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}. + +In algebraic mode, when you press any key that would normally begin +entering a number (such as a digit, a decimal point, or the @kbd{_} +key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins +an algebraic entry. + +Functions which do not have operator symbols like @samp{+} and @samp{*} +must be entered in formulas using function-call notation. For example, +the function name corresponding to the square-root key @kbd{Q} is +@code{sqrt}. To compute a square root in a formula, you would use +the notation @samp{sqrt(@var{x})}. + +Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should +be @cite{0.16227766017}. + +Note that if the formula begins with a function name, you need to use +the apostrophe even if you are in algebraic mode. If you type @kbd{arcsin} +out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite +command, and the @kbd{csin} will be taken as the name of the rewrite +rule to use! + +Some people prefer to enter complex numbers and vectors in algebraic +form because they find RPN entry with incomplete objects to be too +distracting, even though they otherwise use Calc as an RPN calculator. + +Still in algebraic mode, type: + +@group +@smallexample +1: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1) + . 1: (1, -2) . 1: 1 . + . . + + (2,3) RET (1,-2) RET * 1 RET + +@end smallexample +@end group + +Algebraic mode allows us to enter complex numbers without pressing +an apostrophe first, but it also means we need to press @key{RET} +after every entry, even for a simple number like @cite{1}. + +(You can type @kbd{C-u m a} to enable a special ``incomplete algebraic +mode'' in which the @kbd{(} and @kbd{[} keys use algebraic entry even +though regular numeric keys still use RPN numeric entry. There is also +a ``total algebraic mode,'' started by typing @kbd{m t}, in which all +normal keys begin algebraic entry. You must then use the @key{META} key +to type Calc commands: @kbd{M-m t} to get back out of total algebraic +mode, @kbd{M-q} to quit, etc. Total algebraic mode is not supported +under Emacs 19.) + +If you're still in algebraic mode, press @kbd{m a} again to turn it off. + +Actual non-RPN calculators use a mixture of algebraic and RPN styles. +In general, operators of two numbers (like @kbd{+} and @kbd{*}) +use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q}) +use RPN form. Also, a non-RPN calculator allows you to see the +intermediate results of a calculation as you go along. You can +accomplish this in Calc by performing your calculation as a series +of algebraic entries, using the @kbd{$} sign to tie them together. +In an algebraic formula, @kbd{$} represents the number on the top +of the stack. Here, we perform the calculation @c{$\sqrt{2\times4+1}$} +@cite{sqrt(2*4+1)}, +which on a traditional calculator would be done by pressing +@kbd{2 * 4 + 1 =} and then the square-root key. + +@group +@smallexample +1: 8 1: 9 1: 3 + . . . + + ' 2*4 RET $+1 RET Q +@end smallexample +@end group + +@noindent +Notice that we didn't need to press an apostrophe for the @kbd{$+1}, +because the dollar sign always begins an algebraic entry. + +(@bullet{}) @strong{Exercise 1.} How could you get the same effect as +pressing @kbd{Q} but using an algebraic entry instead? How about +if the @kbd{Q} key on your keyboard were broken? +@xref{Algebraic Answer 1, 1}. (@bullet{}) + +The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack +entries. For example, @kbd{' $$+$ RET} is just like typing @kbd{+}. + +Algebraic formulas can include @dfn{variables}. To store in a +variable, press @kbd{s s}, then type the variable name, then press +@key{RET}. (There are actually two flavors of store command: +@kbd{s s} stores a number in a variable but also leaves the number +on the stack, while @w{@kbd{s t}} removes a number from the stack and +stores it in the variable.) A variable name should consist of one +or more letters or digits, beginning with a letter. + +@group +@smallexample +1: 17 . 1: a + a^2 1: 306 + . . . + + 17 s t a RET ' a+a^2 RET = +@end smallexample +@end group + +@noindent +The @kbd{=} key @dfn{evaluates} a formula by replacing all its +variables by the values that were stored in them. + +For RPN calculations, you can recall a variable's value on the +stack either by entering its name as a formula and pressing @kbd{=}, +or by using the @kbd{s r} command. + +@group +@smallexample +1: 17 2: 17 3: 17 2: 17 1: 306 + . 1: 17 2: 17 1: 289 . + . 1: 2 . + . + + s r a RET ' a RET = 2 ^ + +@end smallexample +@end group + +If you press a single digit for a variable name (as in @kbd{s t 3}, you +get one of ten @dfn{quick variables} @code{q0} through @code{q9}. +They are ``quick'' simply because you don't have to type the letter +@code{q} or the @key{RET} after their names. In fact, you can type +simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for +@kbd{t 3} and @w{@kbd{r 3}}. + +Any variables in an algebraic formula for which you have not stored +values are left alone, even when you evaluate the formula. + +@group +@smallexample +1: 2 a + 2 b 1: 34 + 2 b + . . + + ' 2a+2b RET = +@end smallexample +@end group + +Calls to function names which are undefined in Calc are also left +alone, as are calls for which the value is undefined. + +@group +@smallexample +1: 2 + log10(0) + log10(x) + log10(5, 6) + foo(3) + . + + ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) RET +@end smallexample +@end group + +@noindent +In this example, the first call to @code{log10} works, but the other +calls are not evaluated. In the second call, the logarithm is +undefined for that value of the argument; in the third, the argument +is symbolic, and in the fourth, there are too many arguments. In the +fifth case, there is no function called @code{foo}. You will see a +``Wrong number of arguments'' message referring to @samp{log10(5,6)}. +Press the @kbd{w} (``why'') key to see any other messages that may +have arisen from the last calculation. In this case you will get +``logarithm of zero,'' then ``number expected: @code{x}''. Calc +automatically displays the first message only if the message is +sufficiently important; for example, Calc considers ``wrong number +of arguments'' and ``logarithm of zero'' to be important enough to +report automatically, while a message like ``number expected: @code{x}'' +will only show up if you explicitly press the @kbd{w} key. + +(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y}, +stored 5 in @code{x}, pressed @kbd{=}, and got the expected result, +@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)}, +expecting @samp{10 (1+y)}, but it didn't work. Why not? +@xref{Algebraic Answer 2, 2}. (@bullet{}) + +(@bullet{}) @strong{Exercise 3.} What result would you expect +@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}? +@xref{Algebraic Answer 3, 3}. (@bullet{}) + +One interesting way to work with variables is to use the +@dfn{evaluates-to} (@samp{=>}) operator. It works like this: +Enter a formula algebraically in the usual way, but follow +the formula with an @samp{=>} symbol. (There is also an @kbd{s =} +command which builds an @samp{=>} formula using the stack.) On +the stack, you will see two copies of the formula with an @samp{=>} +between them. The lefthand formula is exactly like you typed it; +the righthand formula has been evaluated as if by typing @kbd{=}. + +@group +@smallexample +2: 2 + 3 => 5 2: 2 + 3 => 5 +1: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b + . . + +' 2+3 => RET ' 2a+2b RET s = 10 s t a RET +@end smallexample +@end group + +@noindent +Notice that the instant we stored a new value in @code{a}, all +@samp{=>} operators already on the stack that referred to @cite{a} +were updated to use the new value. With @samp{=>}, you can push a +set of formulas on the stack, then change the variables experimentally +to see the effects on the formulas' values. + +You can also ``unstore'' a variable when you are through with it: + +@group +@smallexample +2: 2 + 5 => 5 +1: 2 a + 2 b => 2 a + 2 b + . + + s u a RET +@end smallexample +@end group + +We will encounter formulas involving variables and functions again +when we discuss the algebra and calculus features of the Calculator. + +@node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial +@subsection Undo and Redo + +@noindent +If you make a mistake, you can usually correct it by pressing shift-@kbd{U}, +the ``undo'' command. First, clear the stack (@kbd{M-0 DEL}) and exit +and restart Calc (@kbd{M-# M-# M-# M-#}) to make sure things start off +with a clean slate. Now: + +@group +@smallexample +1: 2 2: 2 1: 8 2: 2 1: 6 + . 1: 3 . 1: 3 . + . . + + 2 RET 3 ^ U * +@end smallexample +@end group + +You can undo any number of times. Calc keeps a complete record of +all you have done since you last opened the Calc window. After the +above example, you could type: + +@group +@smallexample +1: 6 2: 2 1: 2 . . + . 1: 3 . + . + (error) + U U U U +@end smallexample +@end group + +You can also type @kbd{D} to ``redo'' a command that you have undone +mistakenly. + +@group +@smallexample + . 1: 2 2: 2 1: 6 1: 6 + . 1: 3 . . + . + (error) + D D D D +@end smallexample +@end group + +@noindent +It was not possible to redo past the @cite{6}, since that was placed there +by something other than an undo command. + +@cindex Time travel +You can think of undo and redo as a sort of ``time machine.'' Press +@kbd{U} to go backward in time, @kbd{D} to go forward. If you go +backward and do something (like @kbd{*}) then, as any science fiction +reader knows, you have changed your future and you cannot go forward +again. Thus, the inability to redo past the @cite{6} even though there +was an earlier undo command. + +You can always recall an earlier result using the Trail. We've ignored +the trail so far, but it has been faithfully recording everything we +did since we loaded the Calculator. If the Trail is not displayed, +press @kbd{t d} now to turn it on. + +Let's try grabbing an earlier result. The @cite{8} we computed was +undone by a @kbd{U} command, and was lost even to Redo when we pressed +@kbd{*}, but it's still there in the trail. There should be a little +@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail +entry. If there isn't, press @kbd{t ]} to reset the trail pointer. +Now, press @w{@kbd{t p}} to move the arrow onto the line containing +@cite{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the +stack. + +If you press @kbd{t ]} again, you will see that even our Yank command +went into the trail. + +Let's go further back in time. Earlier in the tutorial we computed +a huge integer using the formula @samp{2^3^4}. We don't remember +what it was, but the first digits were ``241''. Press @kbd{t r} +(which stands for trail-search-reverse), then type @kbd{241}. +The trail cursor will jump back to the next previous occurrence of +the string ``241'' in the trail. This is just a regular Emacs +incremental search; you can now press @kbd{C-s} or @kbd{C-r} to +continue the search forwards or backwards as you like. + +To finish the search, press @key{RET}. This halts the incremental +search and leaves the trail pointer at the thing we found. Now we +can type @kbd{t y} to yank that number onto the stack. If we hadn't +remembered the ``241'', we could simply have searched for @kbd{2^3^4}, +then pressed @kbd{@key{RET} t n} to halt and then move to the next item. + +You may have noticed that all the trail-related commands begin with +the letter @kbd{t}. (The store-and-recall commands, on the other hand, +all began with @kbd{s}.) Calc has so many commands that there aren't +enough keys for all of them, so various commands are grouped into +two-letter sequences where the first letter is called the @dfn{prefix} +key. If you type a prefix key by accident, you can press @kbd{C-g} +to cancel it. (In fact, you can press @kbd{C-g} to cancel almost +anything in Emacs.) To get help on a prefix key, press that key +followed by @kbd{?}. Some prefixes have several lines of help, +so you need to press @kbd{?} repeatedly to see them all. This may +not work under Lucid Emacs, but you can also type @kbd{h h} to +see all the help at once. + +Try pressing @kbd{t ?} now. You will see a line of the form, + +@smallexample +trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t- +@end smallexample + +@noindent +The word ``trail'' indicates that the @kbd{t} prefix key contains +trail-related commands. Each entry on the line shows one command, +with a single capital letter showing which letter you press to get +that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and +@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?} +again to see more @kbd{t}-prefix comands. Notice that the commands +are roughly divided (by semicolons) into related groups. + +When you are in the help display for a prefix key, the prefix is +still active. If you press another key, like @kbd{y} for example, +it will be interpreted as a @kbd{t y} command. If all you wanted +was to look at the help messages, press @kbd{C-g} afterwards to cancel +the prefix. + +One more way to correct an error is by editing the stack entries. +The actual Stack buffer is marked read-only and must not be edited +directly, but you can press @kbd{`} (the backquote or accent grave) +to edit a stack entry. + +Try entering @samp{3.141439} now. If this is supposed to represent +@c{$\pi$} +@cite{pi}, it's got several errors. Press @kbd{`} to edit this number. +Now use the normal Emacs cursor motion and editing keys to change +the second 4 to a 5, and to transpose the 3 and the 9. When you +press @key{RET}, the number on the stack will be replaced by your +new number. This works for formulas, vectors, and all other types +of values you can put on the stack. The @kbd{`} key also works +during entry of a number or algebraic formula. + +@node Modes Tutorial, , Undo Tutorial, Basic Tutorial +@subsection Mode-Setting Commands + +@noindent +Calc has many types of @dfn{modes} that affect the way it interprets +your commands or the way it displays data. We have already seen one +mode, namely algebraic mode. There are many others, too; we'll +try some of the most common ones here. + +Perhaps the most fundamental mode in Calc is the current @dfn{precision}. +Notice the @samp{12} on the Calc window's mode line: + +@smallexample +--%%-Calc: 12 Deg (Calculator)----All------ +@end smallexample + +@noindent +Most of the symbols there are Emacs things you don't need to worry +about, but the @samp{12} and the @samp{Deg} are mode indicators. +The @samp{12} means that calculations should always be carried to +12 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /}, +we get @cite{0.142857142857} with exactly 12 digits, not counting +leading and trailing zeros. + +You can set the precision to anything you like by pressing @kbd{p}, +then entering a suitable number. Try pressing @kbd{p 30 @key{RET}}, +then doing @kbd{1 @key{RET} 7 /} again: + +@group +@smallexample +1: 0.142857142857 +2: 0.142857142857142857142857142857 + . +@end smallexample +@end group + +Although the precision can be set arbitrarily high, Calc always +has to have @emph{some} value for the current precision. After +all, the true value @cite{1/7} is an infinitely repeating decimal; +Calc has to stop somewhere. + +Of course, calculations are slower the more digits you request. +Press @w{@kbd{p 12}} now to set the precision back down to the default. + +Calculations always use the current precision. For example, even +though we have a 30-digit value for @cite{1/7} on the stack, if +we use it in a calculation in 12-digit mode it will be rounded +down to 12 digits before it is used. Try it; press @key{RET} to +duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET} +key didn't round the number, because it doesn't do any calculation. +But the instant we pressed @kbd{+}, the number was rounded down. + +@group +@smallexample +1: 0.142857142857 +2: 0.142857142857142857142857142857 +3: 1.14285714286 + . +@end smallexample +@end group + +@noindent +In fact, since we added a digit on the left, we had to lose one +digit on the right from even the 12-digit value of @cite{1/7}. + +How did we get more than 12 digits when we computed @samp{2^3^4}? The +answer is that Calc makes a distinction between @dfn{integers} and +@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number +that does not contain a decimal point. There is no such thing as an +``infinitely repeating fraction integer,'' so Calc doesn't have to limit +itself. If you asked for @samp{2^10000} (don't try this!), you would +have to wait a long time but you would eventually get an exact answer. +If you ask for @samp{2.^10000}, you will quickly get an answer which is +correct only to 12 places. The decimal point tells Calc that it should +use floating-point arithmetic to get the answer, not exact integer +arithmetic. + +You can use the @kbd{F} (@code{calc-floor}) command to convert a +floating-point value to an integer, and @kbd{c f} (@code{calc-float}) +to convert an integer to floating-point form. + +Let's try entering that last calculation: + +@group +@smallexample +1: 2. 2: 2. 1: 1.99506311689e3010 + . 1: 10000 . + . + + 2.0 RET 10000 RET ^ +@end smallexample +@end group + +@noindent +@cindex Scientific notation, entry of +Notice the letter @samp{e} in there. It represents ``times ten to the +power of,'' and is used by Calc automatically whenever writing the +number out fully would introduce more extra zeros than you probably +want to see. You can enter numbers in this notation, too. + +@group +@smallexample +1: 2. 2: 2. 1: 1.99506311678e3010 + . 1: 10000. . + . + + 2.0 RET 1e4 RET ^ +@end smallexample +@end group + +@cindex Round-off errors +@noindent +Hey, the answer is different! Look closely at the middle columns +of the two examples. In the first, the stack contained the +exact integer @cite{10000}, but in the second it contained +a floating-point value with a decimal point. When you raise a +number to an integer power, Calc uses repeated squaring and +multiplication to get the answer. When you use a floating-point +power, Calc uses logarithms and exponentials. As you can see, +a slight error crept in during one of these methods. Which +one should we trust? Let's raise the precision a bit and find +out: + +@group +@smallexample + . 1: 2. 2: 2. 1: 1.995063116880828e3010 + . 1: 10000. . + . + + p 16 RET 2. RET 1e4 ^ p 12 RET +@end smallexample +@end group + +@noindent +@cindex Guard digits +Presumably, it doesn't matter whether we do this higher-precision +calculation using an integer or floating-point power, since we +have added enough ``guard digits'' to trust the first 12 digits +no matter what. And the verdict is@dots{} Integer powers were more +accurate; in fact, the result was only off by one unit in the +last place. + +@cindex Guard digits +Calc does many of its internal calculations to a slightly higher +precision, but it doesn't always bump the precision up enough. +In each case, Calc added about two digits of precision during +its calculation and then rounded back down to 12 digits +afterward. In one case, it was enough; in the the other, it +wasn't. If you really need @var{x} digits of precision, it +never hurts to do the calculation with a few extra guard digits. + +What if we want guard digits but don't want to look at them? +We can set the @dfn{float format}. Calc supports four major +formats for floating-point numbers, called @dfn{normal}, +@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering +notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f}, +@kbd{d s}, and @kbd{d e}, respectively. In each case, you can +supply a numeric prefix argument which says how many digits +should be displayed. As an example, let's put a few numbers +onto the stack and try some different display modes. First, +use @kbd{M-0 DEL} to clear the stack, then enter the four +numbers shown here: + +@group +@smallexample +4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 +3: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000 +2: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450 +1: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345 + . . . . . + + d n M-3 d n d s M-3 d s M-3 d f +@end smallexample +@end group + +@noindent +Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down +to three significant digits, but then when we typed @kbd{d s} all +five significant figures reappeared. The float format does not +affect how numbers are stored, it only affects how they are +displayed. Only the current precision governs the actual rounding +of numbers in the Calculator's memory. + +Engineering notation, not shown here, is like scientific notation +except the exponent (the power-of-ten part) is always adjusted to be +a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result +there will be one, two, or three digits before the decimal point. + +Whenever you change a display-related mode, Calc redraws everything +in the stack. This may be slow if there are many things on the stack, +so Calc allows you to type shift-@kbd{H} before any mode command to +prevent it from updating the stack. Anything Calc displays after the +mode-changing command will appear in the new format. + +@group +@smallexample +4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 +3: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345. +2: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45 +1: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345 + . . . . . + + H d s DEL U TAB d SPC d n +@end smallexample +@end group + +@noindent +Here the @kbd{H d s} command changes to scientific notation but without +updating the screen. Deleting the top stack entry and undoing it back +causes it to show up in the new format; swapping the top two stack +entries reformats both entries. The @kbd{d SPC} command refreshes the +whole stack. The @kbd{d n} command changes back to the normal float +format; since it doesn't have an @kbd{H} prefix, it also updates all +the stack entries to be in @kbd{d n} format. + +Notice that the integer @cite{12345} was not affected by any +of the float formats. Integers are integers, and are always +displayed exactly. + +@cindex Large numbers, readability +Large integers have their own problems. Let's look back at +the result of @kbd{2^3^4}. + +@example +2417851639229258349412352 +@end example + +@noindent +Quick---how many digits does this have? Try typing @kbd{d g}: + +@example +2,417,851,639,229,258,349,412,352 +@end example + +@noindent +Now how many digits does this have? It's much easier to tell! +We can actually group digits into clumps of any size. Some +people prefer @kbd{M-5 d g}: + +@example +24178,51639,22925,83494,12352 +@end example + +Let's see what happens to floating-point numbers when they are grouped. +First, type @kbd{p 25 @key{RET}} to make sure we have enough precision +to get ourselves into trouble. Now, type @kbd{1e13 /}: + +@example +24,17851,63922.9258349412352 +@end example + +@noindent +The integer part is grouped but the fractional part isn't. Now try +@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five): + +@example +24,17851,63922.92583,49412,352 +@end example + +If you find it hard to tell the decimal point from the commas, try +changing the grouping character to a space with @kbd{d , @key{SPC}}: + +@example +24 17851 63922.92583 49412 352 +@end example + +Type @kbd{d , ,} to restore the normal grouping character, then +@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to +restore the default precision. + +Press @kbd{U} enough times to get the original big integer back. +(Notice that @kbd{U} does not undo each mode-setting command; if +you want to undo a mode-setting command, you have to do it yourself.) +Now, type @kbd{d r 16 @key{RET}}: + +@example +16#200000000000000000000 +@end example + +@noindent +The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form. +Suddenly it looks pretty simple; this should be no surprise, since we +got this number by computing a power of two, and 16 is a power of 2. +In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary +form: + +@example +2#1000000000000000000000000000000000000000000000000000000 @dots{} +@end example + +@noindent +We don't have enough space here to show all the zeros! They won't +fit on a typical screen, either, so you will have to use horizontal +scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the +stack window left and right by half its width. Another way to view +something large is to press @kbd{`} (back-quote) to edit the top of +stack in a separate window. (Press @kbd{M-# M-#} when you are done.) + +You can enter non-decimal numbers using the @kbd{#} symbol, too. +Let's see what the hexadecimal number @samp{5FE} looks like in +binary. Type @kbd{16#5FE} (the letters can be typed in upper or +lower case; they will always appear in upper case). It will also +help to turn grouping on with @kbd{d g}: + +@example +2#101,1111,1110 +@end example + +Notice that @kbd{d g} groups by fours by default if the display radix +is binary or hexadecimal, but by threes if it is decimal, octal, or any +other radix. + +Now let's see that number in decimal; type @kbd{d r 10}: + +@example +1,534 +@end example + +Numbers are not @emph{stored} with any particular radix attached. They're +just numbers; they can be entered in any radix, and are always displayed +in whatever radix you've chosen with @kbd{d r}. The current radix applies +to integers, fractions, and floats. + +@cindex Roundoff errors, in non-decimal numbers +(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third +as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got +@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied +that by three, he got @samp{3#0.222222...} instead of the expected +@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief, +saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got +@samp{3#0.10000001} (some zeros omitted). What's going on here? +@xref{Modes Answer 1, 1}. (@bullet{}) + +@cindex Scientific notation, in non-decimal numbers +(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal +modes in the natural way (the exponent is a power of the radix instead of +a power of ten, although the exponent itself is always written in decimal). +Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number +@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}. +What is wrong with this picture? What could we write instead that would +work better? @xref{Modes Answer 2, 2}. (@bullet{}) + +The @kbd{m} prefix key has another set of modes, relating to the way +Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix +modes generally affect the way things look, @kbd{m}-prefix modes affect +the way they are actually computed. + +The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice +the @samp{Deg} indicator in the mode line. This means that if you use +a command that interprets a number as an angle, it will assume the +angle is measured in degrees. For example, + +@group +@smallexample +1: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5 + . . . . + + 45 S 2 ^ c 1 +@end smallexample +@end group + +@noindent +The shift-@kbd{S} command computes the sine of an angle. The sine +of 45 degrees is @c{$\sqrt{2}/2$} +@cite{sqrt(2)/2}; squaring this yields @cite{2/4 = 0.5}. +However, there has been a slight roundoff error because the +representation of @c{$\sqrt{2}/2$} +@cite{sqrt(2)/2} wasn't exact. The @kbd{c 1} +command is a handy way to clean up numbers in this case; it +temporarily reduces the precision by one digit while it +re-rounds the number on the top of the stack. + +@cindex Roundoff errors, examples +(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine +of 45 degrees as shown above, then, hoping to avoid an inexact +result, he increased the precision to 16 digits before squaring. +What happened? @xref{Modes Answer 3, 3}. (@bullet{}) + +To do this calculation in radians, we would type @kbd{m r} first. +(The indicator changes to @samp{Rad}.) 45 degrees corresponds to +@c{$\pi\over4$} +@cite{pi/4} radians. To get @c{$\pi$} +@cite{pi}, press the @kbd{P} key. (Once +again, this is a shifted capital @kbd{P}. Remember, unshifted +@kbd{p} sets the precision.) + +@group +@smallexample +1: 3.14159265359 1: 0.785398163398 1: 0.707106781187 + . . . + + P 4 / m r S +@end smallexample +@end group + +Likewise, inverse trigonometric functions generate results in +either radians or degrees, depending on the current angular mode. + +@group +@smallexample +1: 0.707106781187 1: 0.785398163398 1: 45. + . . . + + .5 Q m r I S m d U I S +@end smallexample +@end group + +@noindent +Here we compute the Inverse Sine of @c{$\sqrt{0.5}$} +@cite{sqrt(0.5)}, first in +radians, then in degrees. + +Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees +and vice-versa. + +@group +@smallexample +1: 45 1: 0.785398163397 1: 45. + . . . + + 45 c r c d +@end smallexample +@end group + +Another interesting mode is @dfn{fraction mode}. Normally, +dividing two integers produces a floating-point result if the +quotient can't be expressed as an exact integer. Fraction mode +causes integer division to produce a fraction, i.e., a rational +number, instead. + +@group +@smallexample +2: 12 1: 1.33333333333 1: 4:3 +1: 9 . . + . + + 12 RET 9 / m f U / m f +@end smallexample +@end group + +@noindent +In the first case, we get an approximate floating-point result. +In the second case, we get an exact fractional result (four-thirds). + +You can enter a fraction at any time using @kbd{:} notation. +(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator +because @kbd{/} is already used to divide the top two stack +elements.) Calculations involving fractions will always +produce exact fractional results; fraction mode only says +what to do when dividing two integers. + +@cindex Fractions vs. floats +@cindex Floats vs. fractions +(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact, +why would you ever use floating-point numbers instead? +@xref{Modes Answer 4, 4}. (@bullet{}) + +Typing @kbd{m f} doesn't change any existing values in the stack. +In the above example, we had to Undo the division and do it over +again when we changed to fraction mode. But if you use the +evaluates-to operator you can get commands like @kbd{m f} to +recompute for you. + +@group +@smallexample +1: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3 + . . . + + ' 12/9 => RET p 4 RET m f +@end smallexample +@end group + +@noindent +In this example, the righthand side of the @samp{=>} operator +on the stack is recomputed when we change the precision, then +again when we change to fraction mode. All @samp{=>} expressions +on the stack are recomputed every time you change any mode that +might affect their values. + +@node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial +@section Arithmetic Tutorial + +@noindent +In this section, we explore the arithmetic and scientific functions +available in the Calculator. + +The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, +and @kbd{^}. Each normally takes two numbers from the top of the stack +and pushes back a result. The @kbd{n} and @kbd{&} keys perform +change-sign and reciprocal operations, respectively. + +@group +@smallexample +1: 5 1: 0.2 1: 5. 1: -5. 1: 5. + . . . . . + + 5 & & n n +@end smallexample +@end group + +@cindex Binary operators +You can apply a ``binary operator'' like @kbd{+} across any number of +stack entries by giving it a numeric prefix. You can also apply it +pairwise to several stack elements along with the top one if you use +a negative prefix. + +@group +@smallexample +3: 2 1: 9 3: 2 4: 2 3: 12 +2: 3 . 2: 3 3: 3 2: 13 +1: 4 1: 4 2: 4 1: 14 + . . 1: 10 . + . + +2 RET 3 RET 4 M-3 + U 10 M-- M-3 + +@end smallexample +@end group + +@cindex Unary operators +You can apply a ``unary operator'' like @kbd{&} to the top @var{n} +stack entries with a numeric prefix, too. + +@group +@smallexample +3: 2 3: 0.5 3: 0.5 +2: 3 2: 0.333333333333 2: 3. +1: 4 1: 0.25 1: 4. + . . . + +2 RET 3 RET 4 M-3 & M-2 & +@end smallexample +@end group + +Notice that the results here are left in floating-point form. +We can convert them back to integers by pressing @kbd{F}, the +``floor'' function. This function rounds down to the next lower +integer. There is also @kbd{R}, which rounds to the nearest +integer. + +@group +@smallexample +7: 2. 7: 2 7: 2 +6: 2.4 6: 2 6: 2 +5: 2.5 5: 2 5: 3 +4: 2.6 4: 2 4: 3 +3: -2. 3: -2 3: -2 +2: -2.4 2: -3 2: -2 +1: -2.6 1: -3 1: -3 + . . . + + M-7 F U M-7 R +@end smallexample +@end group + +Since dividing-and-flooring (i.e., ``integer quotient'') is such a +common operation, Calc provides a special command for that purpose, the +backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which +computes the remainder that would arise from a @kbd{\} operation, i.e., +the ``modulo'' of two numbers. For example, + +@group +@smallexample +2: 1234 1: 12 2: 1234 1: 34 +1: 100 . 1: 100 . + . . + +1234 RET 100 \ U % +@end smallexample +@end group + +These commands actually work for any real numbers, not just integers. + +@group +@smallexample +2: 3.1415 1: 3 2: 3.1415 1: 0.1415 +1: 1 . 1: 1 . + . . + +3.1415 RET 1 \ U % +@end smallexample +@end group + +(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a +frill, since you could always do the same thing with @kbd{/ F}. Think +of a situation where this is not true---@kbd{/ F} would be inadequate. +Now think of a way you could get around the problem if Calc didn't +provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{}) + +We've already seen the @kbd{Q} (square root) and @kbd{S} (sine) +commands. Other commands along those lines are @kbd{C} (cosine), +@kbd{T} (tangent), @kbd{E} (@cite{e^x}) and @kbd{L} (natural +logarithm). These can be modified by the @kbd{I} (inverse) and +@kbd{H} (hyperbolic) prefix keys. + +Let's compute the sine and cosine of an angle, and verify the +identity @c{$\sin^2x + \cos^2x = 1$} +@cite{sin(x)^2 + cos(x)^2 = 1}. We'll +arbitrarily pick @i{-64} degrees as a good value for @cite{x}. With +the angular mode set to degrees (type @w{@kbd{m d}}), do: + +@group +@smallexample +2: -64 2: -64 2: -0.89879 2: -0.89879 1: 1. +1: -64 1: -0.89879 1: -64 1: 0.43837 . + . . . . + + 64 n RET RET S TAB C f h +@end smallexample +@end group + +@noindent +(For brevity, we're showing only five digits of the results here. +You can of course do these calculations to any precision you like.) + +Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum +of squares, command. + +Another identity is @c{$\displaystyle\tan x = {\sin x \over \cos x}$} +@cite{tan(x) = sin(x) / cos(x)}. +@group +@smallexample + +2: -0.89879 1: -2.0503 1: -64. +1: 0.43837 . . + . + + U / I T +@end smallexample +@end group + +A physical interpretation of this calculation is that if you move +@cite{0.89879} units downward and @cite{0.43837} units to the right, +your direction of motion is @i{-64} degrees from horizontal. Suppose +we move in the opposite direction, up and to the left: + +@group +@smallexample +2: -0.89879 2: 0.89879 1: -2.0503 1: -64. +1: 0.43837 1: -0.43837 . . + . . + + U U M-2 n / I T +@end smallexample +@end group + +@noindent +How can the angle be the same? The answer is that the @kbd{/} operation +loses information about the signs of its inputs. Because the quotient +is negative, we know exactly one of the inputs was negative, but we +can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which +computes the inverse tangent of the quotient of a pair of numbers. +Since you feed it the two original numbers, it has enough information +to give you a full 360-degree answer. + +@group +@smallexample +2: 0.89879 1: 116. 3: 116. 2: 116. 1: 180. +1: -0.43837 . 2: -0.89879 1: -64. . + . 1: 0.43837 . + . + + U U f T M-RET M-2 n f T - +@end smallexample +@end group + +@noindent +The resulting angles differ by 180 degrees; in other words, they +point in opposite directions, just as we would expect. + +The @key{META}-@key{RET} we used in the third step is the +``last-arguments'' command. It is sort of like Undo, except that it +restores the arguments of the last command to the stack without removing +the command's result. It is useful in situations like this one, +where we need to do several operations on the same inputs. We could +have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate +the top two stack elements right after the @kbd{U U}, then a pair of +@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates. + +A similar identity is supposed to hold for hyperbolic sines and cosines, +except that it is the @emph{difference} +@c{$\cosh^2x - \sinh^2x$} +@cite{cosh(x)^2 - sinh(x)^2} that always equals one. +Let's try to verify this identity.@refill + +@group +@smallexample +2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 +1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 + . . . . . + + 64 n RET RET H C 2 ^ TAB H S 2 ^ +@end smallexample +@end group + +@noindent +@cindex Roundoff errors, examples +Something's obviously wrong, because when we subtract these numbers +the answer will clearly be zero! But if you think about it, if these +numbers @emph{did} differ by one, it would be in the 55th decimal +place. The difference we seek has been lost entirely to roundoff +error. + +We could verify this hypothesis by doing the actual calculation with, +say, 60 decimal places of precision. This will be slow, but not +enormously so. Try it if you wish; sure enough, the answer is +0.99999, reasonably close to 1. + +Of course, a more reasonable way to verify the identity is to use +a more reasonable value for @cite{x}! + +@cindex Common logarithm +Some Calculator commands use the Hyperbolic prefix for other purposes. +The logarithm and exponential functions, for example, work to the base +@cite{e} normally but use base-10 instead if you use the Hyperbolic +prefix. + +@group +@smallexample +1: 1000 1: 6.9077 1: 1000 1: 3 + . . . . + + 1000 L U H L +@end smallexample +@end group + +@noindent +First, we mistakenly compute a natural logarithm. Then we undo +and compute a common logarithm instead. + +The @kbd{B} key computes a general base-@var{b} logarithm for any +value of @var{b}. + +@group +@smallexample +2: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077 +1: 10 . . 1: 2.71828 . + . . + + 1000 RET 10 B H E H P B +@end smallexample +@end group + +@noindent +Here we first use @kbd{B} to compute the base-10 logarithm, then use +the ``hyperbolic'' exponential as a cheap hack to recover the number +1000, then use @kbd{B} again to compute the natural logarithm. Note +that @kbd{P} with the hyperbolic prefix pushes the constant @cite{e} +onto the stack. + +You may have noticed that both times we took the base-10 logarithm +of 1000, we got an exact integer result. Calc always tries to give +an exact rational result for calculations involving rational numbers +where possible. But when we used @kbd{H E}, the result was a +floating-point number for no apparent reason. In fact, if we had +computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an +exact integer 1000. But the @kbd{H E} command is rigged to generate +a floating-point result all of the time so that @kbd{1000 H E} will +not waste time computing a thousand-digit integer when all you +probably wanted was @samp{1e1000}. + +(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to +the @kbd{B} command for which Calc could find an exact rational +result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{}) + +The Calculator also has a set of functions relating to combinatorics +and statistics. You may be familiar with the @dfn{factorial} function, +which computes the product of all the integers up to a given number. + +@group +@smallexample +1: 100 1: 93326215443... 1: 100. 1: 9.3326e157 + . . . . + + 100 ! U c f ! +@end smallexample +@end group + +@noindent +Recall, the @kbd{c f} command converts the integer or fraction at the +top of the stack to floating-point format. If you take the factorial +of a floating-point number, you get a floating-point result +accurate to the current precision. But if you give @kbd{!} an +exact integer, you get an exact integer result (158 digits long +in this case). + +If you take the factorial of a non-integer, Calc uses a generalized +factorial function defined in terms of Euler's Gamma function +@c{$\Gamma(n)$} +@cite{gamma(n)} +(which is itself available as the @kbd{f g} command). + +@group +@smallexample +3: 4. 3: 24. 1: 5.5 1: 52.342777847 +2: 4.5 2: 52.3427777847 . . +1: 5. 1: 120. + . . + + M-3 ! M-0 DEL 5.5 f g +@end smallexample +@end group + +@noindent +Here we verify the identity @c{$n! = \Gamma(n+1)$} +@cite{@var{n}!@: = gamma(@var{n}+1)}. + +The binomial coefficient @var{n}-choose-@var{m}@c{ or $\displaystyle {n \choose m}$} +@asis{} is defined by +@c{$\displaystyle {n! \over m! \, (n-m)!}$} +@cite{n!@: / m!@: (n-m)!} for all reals @cite{n} and +@cite{m}. The intermediate results in this formula can become quite +large even if the final result is small; the @kbd{k c} command computes +a binomial coefficient in a way that avoids large intermediate +values. + +The @kbd{k} prefix key defines several common functions out of +combinatorics and number theory. Here we compute the binomial +coefficient 30-choose-20, then determine its prime factorization. + +@group +@smallexample +2: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29] +1: 20 . . + . + + 30 RET 20 k c k f +@end smallexample +@end group + +@noindent +You can verify these prime factors by using @kbd{v u} to ``unpack'' +this vector into 8 separate stack entries, then @kbd{M-8 *} to +multiply them back together. The result is the original number, +30045015. + +@cindex Hash tables +Suppose a program you are writing needs a hash table with at least +10000 entries. It's best to use a prime number as the actual size +of a hash table. Calc can compute the next prime number after 10000: + +@group +@smallexample +1: 10000 1: 10007 1: 9973 + . . . + + 10000 k n I k n +@end smallexample +@end group + +@noindent +Just for kicks we've also computed the next prime @emph{less} than +10000. + +@c [fix-ref Financial Functions] +@xref{Financial Functions}, for a description of the Calculator +commands that deal with business and financial calculations (functions +like @code{pv}, @code{rate}, and @code{sln}). + +@c [fix-ref Binary Number Functions] +@xref{Binary Functions}, to read about the commands for operating +on binary numbers (like @code{and}, @code{xor}, and @code{lsh}). + +@node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial +@section Vector/Matrix Tutorial + +@noindent +A @dfn{vector} is a list of numbers or other Calc data objects. +Calc provides a large set of commands that operate on vectors. Some +are familiar operations from vector analysis. Others simply treat +a vector as a list of objects. + +@menu +* Vector Analysis Tutorial:: +* Matrix Tutorial:: +* List Tutorial:: +@end menu + +@node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial +@subsection Vector Analysis + +@noindent +If you add two vectors, the result is a vector of the sums of the +elements, taken pairwise. + +@group +@smallexample +1: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3] + . 1: [7, 6, 0] . + . + + [1,2,3] s 1 [7 6 0] s 2 + +@end smallexample +@end group + +@noindent +Note that we can separate the vector elements with either commas or +spaces. This is true whether we are using incomplete vectors or +algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these +vectors so we can easily reuse them later. + +If you multiply two vectors, the result is the sum of the products +of the elements taken pairwise. This is called the @dfn{dot product} +of the vectors. + +@group +@smallexample +2: [1, 2, 3] 1: 19 +1: [7, 6, 0] . + . + + r 1 r 2 * +@end smallexample +@end group + +@cindex Dot product +The dot product of two vectors is equal to the product of their +lengths times the cosine of the angle between them. (Here the vector +is interpreted as a line from the origin @cite{(0,0,0)} to the +specified point in three-dimensional space.) The @kbd{A} +(absolute value) command can be used to compute the length of a +vector. + +@group +@smallexample +3: 19 3: 19 1: 0.550782 1: 56.579 +2: [1, 2, 3] 2: 3.741657 . . +1: [7, 6, 0] 1: 9.219544 + . . + + M-RET M-2 A * / I C +@end smallexample +@end group + +@noindent +First we recall the arguments to the dot product command, then +we compute the absolute values of the top two stack entries to +obtain the lengths of the vectors, then we divide the dot product +by the product of the lengths to get the cosine of the angle. +The inverse cosine finds that the angle between the vectors +is about 56 degrees. + +@cindex Cross product +@cindex Perpendicular vectors +The @dfn{cross product} of two vectors is a vector whose length +is the product of the lengths of the inputs times the sine of the +angle between them, and whose direction is perpendicular to both +input vectors. Unlike the dot product, the cross product is +defined only for three-dimensional vectors. Let's double-check +our computation of the angle using the cross product. + +@group +@smallexample +2: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579 +1: [7, 6, 0] 2: [1, 2, 3] . . + . 1: [7, 6, 0] + . + + r 1 r 2 V C s 3 M-RET M-2 A * / A I S +@end smallexample +@end group + +@noindent +First we recall the original vectors and compute their cross product, +which we also store for later reference. Now we divide the vector +by the product of the lengths of the original vectors. The length of +this vector should be the sine of the angle; sure enough, it is! + +@c [fix-ref General Mode Commands] +Vector-related commands generally begin with the @kbd{v} prefix key. +Some are uppercase letters and some are lowercase. To make it easier +to type these commands, the shift-@kbd{V} prefix key acts the same as +the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all +prefix keys have this property.) + +If we take the dot product of two perpendicular vectors we expect +to get zero, since the cosine of 90 degrees is zero. Let's check +that the cross product is indeed perpendicular to both inputs: + +@group +@smallexample +2: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0 +1: [-18, 21, -8] . 1: [-18, 21, -8] . + . . + + r 1 r 3 * DEL r 2 r 3 * +@end smallexample +@end group + +@cindex Normalizing a vector +@cindex Unit vectors +(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the +stack, what keystrokes would you use to @dfn{normalize} the +vector, i.e., to reduce its length to one without changing its +direction? @xref{Vector Answer 1, 1}. (@bullet{}) + +(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be +at any of several positions along a ruler. You have a list of +those positions in the form of a vector, and another list of the +probabilities for the particle to be at the corresponding positions. +Find the average position of the particle. +@xref{Vector Answer 2, 2}. (@bullet{}) + +@node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial +@subsection Matrices + +@noindent +A @dfn{matrix} is just a vector of vectors, all the same length. +This means you can enter a matrix using nested brackets. You can +also use the semicolon character to enter a matrix. We'll show +both methods here: + +@group +@smallexample +1: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] + [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] + . . + + [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] RET +@end smallexample +@end group + +@noindent +We'll be using this matrix again, so type @kbd{s 4} to save it now. + +Note that semicolons work with incomplete vectors, but they work +better in algebraic entry. That's why we use the apostrophe in +the second example. + +When two matrices are multiplied, the lefthand matrix must have +the same number of columns as the righthand matrix has rows. +Row @cite{i}, column @cite{j} of the result is effectively the +dot product of row @cite{i} of the left matrix by column @cite{j} +of the right matrix. + +If we try to duplicate this matrix and multiply it by itself, +the dimensions are wrong and the multiplication cannot take place: + +@group +@smallexample +1: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ] + [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] + . + + RET * +@end smallexample +@end group + +@noindent +Though rather hard to read, this is a formula which shows the product +of two matrices. The @samp{*} function, having invalid arguments, has +been left in symbolic form. + +We can multiply the matrices if we @dfn{transpose} one of them first. + +@group +@smallexample +2: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ] + [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ] +1: [ [ 1, 4 ] . [ 27, 36, 45 ] ] + [ 2, 5 ] . + [ 3, 6 ] ] + . + + U v t * U TAB * +@end smallexample +@end group + +Matrix multiplication is not commutative; indeed, switching the +order of the operands can even change the dimensions of the result +matrix, as happened here! + +If you multiply a plain vector by a matrix, it is treated as a +single row or column depending on which side of the matrix it is +on. The result is a plain vector which should also be interpreted +as a row or column as appropriate. + +@group +@smallexample +2: [ [ 1, 2, 3 ] 1: [14, 32] + [ 4, 5, 6 ] ] . +1: [1, 2, 3] + . + + r 4 r 1 * +@end smallexample +@end group + +Multiplying in the other order wouldn't work because the number of +rows in the matrix is different from the number of elements in the +vector. + +(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows +of the above @c{$2\times3$} +@asis{2x3} matrix to get @cite{[6, 15]}. Now use @samp{*} to +sum along the columns to get @cite{[5, 7, 9]}. +@xref{Matrix Answer 1, 1}. (@bullet{}) + +@cindex Identity matrix +An @dfn{identity matrix} is a square matrix with ones along the +diagonal and zeros elsewhere. It has the property that multiplication +by an identity matrix, on the left or on the right, always produces +the original matrix. + +@group +@smallexample +1: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] + [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] + . 1: [ [ 1, 0, 0 ] . + [ 0, 1, 0 ] + [ 0, 0, 1 ] ] + . + + r 4 v i 3 RET * +@end smallexample +@end group + +If a matrix is square, it is often possible to find its @dfn{inverse}, +that is, a matrix which, when multiplied by the original matrix, yields +an identity matrix. The @kbd{&} (reciprocal) key also computes the +inverse of a matrix. + +@group +@smallexample +1: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ] + [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ] + [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ] + . . + + r 4 r 2 | s 5 & +@end smallexample +@end group + +@noindent +The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and +matrices together. Here we have used it to add a new row onto +our matrix to make it square. + +We can multiply these two matrices in either order to get an identity. + +@group +@smallexample +1: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ] + [ 0., 1., 0. ] [ 0., 1., 0. ] + [ 0., 0., 1. ] ] [ 0., 0., 1. ] ] + . . + + M-RET * U TAB * +@end smallexample +@end group + +@cindex Systems of linear equations +@cindex Linear equations, systems of +Matrix inverses are related to systems of linear equations in algebra. +Suppose we had the following set of equations: + +@ifinfo +@group +@example + a + 2b + 3c = 6 + 4a + 5b + 6c = 2 + 7a + 6b = 3 +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\beforedisplayh +$$ \openup1\jot \tabskip=0pt plus1fil +\halign to\displaywidth{\tabskip=0pt + $\hfil#$&$\hfil{}#{}$& + $\hfil#$&$\hfil{}#{}$& + $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr + a&+&2b&+&3c&=6 \cr + 4a&+&5b&+&6c&=2 \cr + 7a&+&6b& & &=3 \cr} +$$ +\afterdisplayh +@end tex + +@noindent +This can be cast into the matrix equation, + +@ifinfo +@group +@example + [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ] + [ 4, 5, 6 ] * [ b ] = [ 2 ] + [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ] +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 } + \times + \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 } +$$ +\afterdisplay +@end tex + +We can solve this system of equations by multiplying both sides by the +inverse of the matrix. Calc can do this all in one step: + +@group +@smallexample +2: [6, 2, 3] 1: [-12.6, 15.2, -3.93333] +1: [ [ 1, 2, 3 ] . + [ 4, 5, 6 ] + [ 7, 6, 0 ] ] + . + + [6,2,3] r 5 / +@end smallexample +@end group + +@noindent +The result is the @cite{[a, b, c]} vector that solves the equations. +(Dividing by a square matrix is equivalent to multiplying by its +inverse.) + +Let's verify this solution: + +@group +@smallexample +2: [ [ 1, 2, 3 ] 1: [6., 2., 3.] + [ 4, 5, 6 ] . + [ 7, 6, 0 ] ] +1: [-12.6, 15.2, -3.93333] + . + + r 5 TAB * +@end smallexample +@end group + +@noindent +Note that we had to be careful about the order in which we multiplied +the matrix and vector. If we multiplied in the other order, Calc would +assume the vector was a row vector in order to make the dimensions +come out right, and the answer would be incorrect. If you +don't feel safe letting Calc take either interpretation of your +vectors, use explicit @c{$N\times1$} +@asis{Nx1} or @c{$1\times N$} +@asis{1xN} matrices instead. +In this case, you would enter the original column vector as +@samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}. + +(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make +vectors and matrices that include variables. Solve the following +system of equations to get expressions for @cite{x} and @cite{y} +in terms of @cite{a} and @cite{b}. + +@ifinfo +@group +@example + x + a y = 6 + x + b y = 10 +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ \eqalign{ x &+ a y = 6 \cr + x &+ b y = 10} +$$ +\afterdisplay +@end tex + +@noindent +@xref{Matrix Answer 2, 2}. (@bullet{}) + +@cindex Least-squares for over-determined systems +@cindex Over-determined systems of equations +(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined'' +if it has more equations than variables. It is often the case that +there are no values for the variables that will satisfy all the +equations at once, but it is still useful to find a set of values +which ``nearly'' satisfy all the equations. In terms of matrix equations, +you can't solve @cite{A X = B} directly because the matrix @cite{A} +is not square for an over-determined system. Matrix inversion works +only for square matrices. One common trick is to multiply both sides +on the left by the transpose of @cite{A}: +@ifinfo +@samp{trn(A)*A*X = trn(A)*B}. +@end ifinfo +@tex +\turnoffactive +$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}. +@end tex +Now @c{$A^T A$} +@cite{trn(A)*A} is a square matrix so a solution is possible. It +turns out that the @cite{X} vector you compute in this way will be a +``least-squares'' solution, which can be regarded as the ``closest'' +solution to the set of equations. Use Calc to solve the following +over-determined system:@refill + +@ifinfo +@group +@example + a + 2b + 3c = 6 + 4a + 5b + 6c = 2 + 7a + 6b = 3 + 2a + 4b + 6c = 11 +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\beforedisplayh +$$ \openup1\jot \tabskip=0pt plus1fil +\halign to\displaywidth{\tabskip=0pt + $\hfil#$&$\hfil{}#{}$& + $\hfil#$&$\hfil{}#{}$& + $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr + a&+&2b&+&3c&=6 \cr + 4a&+&5b&+&6c&=2 \cr + 7a&+&6b& & &=3 \cr + 2a&+&4b&+&6c&=11 \cr} +$$ +\afterdisplayh +@end tex + +@noindent +@xref{Matrix Answer 3, 3}. (@bullet{}) + +@node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial +@subsection Vectors as Lists + +@noindent +@cindex Lists +Although Calc has a number of features for manipulating vectors and +matrices as mathematical objects, you can also treat vectors as +simple lists of values. For example, we saw that the @kbd{k f} +command returns a vector which is a list of the prime factors of a +number. + +You can pack and unpack stack entries into vectors: + +@group +@smallexample +3: 10 1: [10, 20, 30] 3: 10 +2: 20 . 2: 20 +1: 30 1: 30 + . . + + M-3 v p v u +@end smallexample +@end group + +You can also build vectors out of consecutive integers, or out +of many copies of a given value: + +@group +@smallexample +1: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4] + . 1: 17 1: [17, 17, 17, 17] + . . + + v x 4 RET 17 v b 4 RET +@end smallexample +@end group + +You can apply an operator to every element of a vector using the +@dfn{map} command. + +@group +@smallexample +1: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68] + . . . + + V M * 2 V M ^ V M Q +@end smallexample +@end group + +@noindent +In the first step, we multiply the vector of integers by the vector +of 17's elementwise. In the second step, we raise each element to +the power two. (The general rule is that both operands must be +vectors of the same length, or else one must be a vector and the +other a plain number.) In the final step, we take the square root +of each element. + +(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two +from @c{$2^{-4}$} +@cite{2^-4} to @cite{2^4}. @xref{List Answer 1, 1}. (@bullet{}) + +You can also @dfn{reduce} a binary operator across a vector. +For example, reducing @samp{*} computes the product of all the +elements in the vector: + +@group +@smallexample +1: 123123 1: [3, 7, 11, 13, 41] 1: 123123 + . . . + + 123123 k f V R * +@end smallexample +@end group + +@noindent +In this example, we decompose 123123 into its prime factors, then +multiply those factors together again to yield the original number. + +We could compute a dot product ``by hand'' using mapping and +reduction: + +@group +@smallexample +2: [1, 2, 3] 1: [7, 12, 0] 1: 19 +1: [7, 6, 0] . . + . + + r 1 r 2 V M * V R + +@end smallexample +@end group + +@noindent +Recalling two vectors from the previous section, we compute the +sum of pairwise products of the elements to get the same answer +for the dot product as before. + +A slight variant of vector reduction is the @dfn{accumulate} operation, +@kbd{V U}. This produces a vector of the intermediate results from +a corresponding reduction. Here we compute a table of factorials: + +@group +@smallexample +1: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720] + . . + + v x 6 RET V U * +@end smallexample +@end group + +Calc allows vectors to grow as large as you like, although it gets +rather slow if vectors have more than about a hundred elements. +Actually, most of the time is spent formatting these large vectors +for display, not calculating on them. Try the following experiment +(if your computer is very fast you may need to substitute a larger +vector size). + +@group +@smallexample +1: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ... + . . + + v x 500 RET 1 V M + +@end smallexample +@end group + +Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the +experiment again. In @kbd{v .} mode, long vectors are displayed +``abbreviated'' like this: + +@group +@smallexample +1: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501] + . . + + v x 500 RET 1 V M + +@end smallexample +@end group + +@noindent +(where now the @samp{...} is actually part of the Calc display). +You will find both operations are now much faster. But notice that +even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail. +Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the +experiment one more time. Operations on long vectors are now quite +fast! (But of course if you use @kbd{t .} you will lose the ability +to get old vectors back using the @kbd{t y} command.) + +An easy way to view a full vector when @kbd{v .} mode is active is +to press @kbd{`} (back-quote) to edit the vector; editing always works +with the full, unabbreviated value. + +@cindex Least-squares for fitting a straight line +@cindex Fitting data to a line +@cindex Line, fitting data to +@cindex Data, extracting from buffers +@cindex Columns of data, extracting +As a larger example, let's try to fit a straight line to some data, +using the method of least squares. (Calc has a built-in command for +least-squares curve fitting, but we'll do it by hand here just to +practice working with vectors.) Suppose we have the following list +of values in a file we have loaded into Emacs: + +@smallexample + x y + --- --- + 1.34 0.234 + 1.41 0.298 + 1.49 0.402 + 1.56 0.412 + 1.64 0.466 + 1.73 0.473 + 1.82 0.601 + 1.91 0.519 + 2.01 0.603 + 2.11 0.637 + 2.22 0.645 + 2.33 0.705 + 2.45 0.917 + 2.58 1.009 + 2.71 0.971 + 2.85 1.062 + 3.00 1.148 + 3.15 1.157 + 3.32 1.354 +@end smallexample + +@noindent +If you are reading this tutorial in printed form, you will find it +easiest to press @kbd{M-# i} to enter the on-line Info version of +the manual and find this table there. (Press @kbd{g}, then type +@kbd{List Tutorial}, to jump straight to this section.) + +Position the cursor at the upper-left corner of this table, just +to the left of the @cite{1.34}. Press @kbd{C-@@} to set the mark. +(On your system this may be @kbd{C-2}, @kbd{C-SPC}, or @kbd{NUL}.) +Now position the cursor to the lower-right, just after the @cite{1.354}. +You have now defined this region as an Emacs ``rectangle.'' Still +in the Info buffer, type @kbd{M-# r}. This command +(@code{calc-grab-rectangle}) will pop you back into the Calculator, with +the contents of the rectangle you specified in the form of a matrix.@refill + +@group +@smallexample +1: [ [ 1.34, 0.234 ] + [ 1.41, 0.298 ] + @dots{} +@end smallexample +@end group + +@noindent +(You may wish to use @kbd{v .} mode to abbreviate the display of this +large matrix.) + +We want to treat this as a pair of lists. The first step is to +transpose this matrix into a pair of rows. Remember, a matrix is +just a vector of vectors. So we can unpack the matrix into a pair +of row vectors on the stack. + +@group +@smallexample +1: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ] + [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ] + . . + + v t v u +@end smallexample +@end group + +@noindent +Let's store these in quick variables 1 and 2, respectively. + +@group +@smallexample +1: [1.34, 1.41, 1.49, ... ] . + . + + t 2 t 1 +@end smallexample +@end group + +@noindent +(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the +stored value from the stack.) + +In a least squares fit, the slope @cite{m} is given by the formula + +@ifinfo +@example +m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2) +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ m = {N \sum x y - \sum x \sum y \over + N \sum x^2 - \left( \sum x \right)^2} $$ +\afterdisplay +@end tex + +@noindent +where @c{$\sum x$} +@cite{sum(x)} represents the sum of all the values of @cite{x}. +While there is an actual @code{sum} function in Calc, it's easier to +sum a vector using a simple reduction. First, let's compute the four +different sums that this formula uses. + +@group +@smallexample +1: 41.63 1: 98.0003 + . . + + r 1 V R + t 3 r 1 2 V M ^ V R + t 4 + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 13.613 1: 33.36554 + . . + + r 2 V R + t 5 r 1 r 2 V M * V R + t 6 +@end smallexample +@end group + +@ifinfo +@noindent +These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)}, +respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and +@samp{sum(x y)}.) +@end ifinfo +@tex +\turnoffactive +These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$, +respectively. (We could have used \kbd{*} to compute $\sum x^2$ and +$\sum x y$.) +@end tex + +Finally, we also need @cite{N}, the number of data points. This is just +the length of either of our lists. + +@group +@smallexample +1: 19 + . + + r 1 v l t 7 +@end smallexample +@end group + +@noindent +(That's @kbd{v} followed by a lower-case @kbd{l}.) + +Now we grind through the formula: + +@group +@smallexample +1: 633.94526 2: 633.94526 1: 67.23607 + . 1: 566.70919 . + . + + r 7 r 6 * r 3 r 5 * - + +@end smallexample +@end group +@noindent +@group +@smallexample +2: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679 +1: 1862.0057 2: 1862.0057 1: 128.9488 . + . 1: 1733.0569 . + . + + r 7 r 4 * r 3 2 ^ - / t 8 +@end smallexample +@end group + +That gives us the slope @cite{m}. The y-intercept @cite{b} can now +be found with the simple formula, + +@ifinfo +@example +b = (sum(y) - m sum(x)) / N +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ b = {\sum y - m \sum x \over N} $$ +\afterdisplay +\vskip10pt +@end tex + +@group +@smallexample +1: 13.613 2: 13.613 1: -8.09358 1: -0.425978 + . 1: 21.70658 . . + . + + r 5 r 8 r 3 * - r 7 / t 9 +@end smallexample +@end group + +Let's ``plot'' this straight line approximation, @c{$y \approx m x + b$} +@cite{m x + b}, and compare it with the original data.@refill + +@group +@smallexample +1: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ] + . . + + r 1 r 8 * r 9 + s 0 +@end smallexample +@end group + +@noindent +Notice that multiplying a vector by a constant, and adding a constant +to a vector, can be done without mapping commands since these are +common operations from vector algebra. As far as Calc is concerned, +we've just been doing geometry in 19-dimensional space! + +We can subtract this vector from our original @cite{y} vector to get +a feel for the error of our fit. Let's find the maximum error: + +@group +@smallexample +1: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897 + . . . + + r 2 - V M A V R X +@end smallexample +@end group + +@noindent +First we compute a vector of differences, then we take the absolute +values of these differences, then we reduce the @code{max} function +across the vector. (The @code{max} function is on the two-key sequence +@kbd{f x}; because it is so common to use @code{max} in a vector +operation, the letters @kbd{X} and @kbd{N} are also accepted for +@code{max} and @code{min} in this context. In general, you answer +the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that +invokes the function you want. You could have typed @kbd{V R f x} or +even @kbd{V R x max @key{RET}} if you had preferred.) + +If your system has the GNUPLOT program, you can see graphs of your +data and your straight line to see how well they match. (If you have +GNUPLOT 3.0, the following instructions will work regardless of the +kind of display you have. Some GNUPLOT 2.0, non-X-windows systems +may require additional steps to view the graphs.) + +Let's start by plotting the original data. Recall the ``@i{x}'' and ``@i{y}'' +vectors onto the stack and press @kbd{g f}. This ``fast'' graphing +command does everything you need to do for simple, straightforward +plotting of data. + +@group +@smallexample +2: [1.34, 1.41, 1.49, ... ] +1: [0.234, 0.298, 0.402, ... ] + . + + r 1 r 2 g f +@end smallexample +@end group + +If all goes well, you will shortly get a new window containing a graph +of the data. (If not, contact your GNUPLOT or Calc installer to find +out what went wrong.) In the X window system, this will be a separate +graphics window. For other kinds of displays, the default is to +display the graph in Emacs itself using rough character graphics. +Press @kbd{q} when you are done viewing the character graphics. + +Next, let's add the line we got from our least-squares fit: + +@group +@smallexample +2: [1.34, 1.41, 1.49, ... ] +1: [0.273, 0.309, 0.351, ... ] + . + + DEL r 0 g a g p +@end smallexample +@end group + +It's not very useful to get symbols to mark the data points on this +second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q} +when you are done to remove the X graphics window and terminate GNUPLOT. + +(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do +least squares fitting to a general system of equations. Our 19 data +points are really 19 equations of the form @cite{y_i = m x_i + b} for +different pairs of @cite{(x_i,y_i)}. Use the matrix-transpose method +to solve for @cite{m} and @cite{b}, duplicating the above result. +@xref{List Answer 2, 2}. (@bullet{}) + +@cindex Geometric mean +(@bullet{}) @strong{Exercise 3.} If the input data do not form a +rectangle, you can use @w{@kbd{M-# g}} (@code{calc-grab-region}) +to grab the data the way Emacs normally works with regions---it reads +left-to-right, top-to-bottom, treating line breaks the same as spaces. +Use this command to find the geometric mean of the following numbers. +(The geometric mean is the @var{n}th root of the product of @var{n} numbers.) + +@example +2.3 6 22 15.1 7 + 15 14 7.5 + 2.5 +@end example + +@noindent +The @kbd{M-# g} command accepts numbers separated by spaces or commas, +with or without surrounding vector brackets. +@xref{List Answer 3, 3}. (@bullet{}) + +@ifinfo +As another example, a theorem about binomial coefficients tells +us that the alternating sum of binomial coefficients +@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so +on up to @var{n}-choose-@var{n}, +always comes out to zero. Let's verify this +for @cite{n=6}.@refill +@end ifinfo +@tex +As another example, a theorem about binomial coefficients tells +us that the alternating sum of binomial coefficients +${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$ +always comes out to zero. Let's verify this +for \cite{n=6}. +@end tex + +@group +@smallexample +1: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6] + . . + + v x 7 RET 1 - + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [1, -6, 15, -20, 15, -6, 1] 1: 0 + . . + + V M ' (-1)^$ choose(6,$) RET V R + +@end smallexample +@end group + +The @kbd{V M '} command prompts you to enter any algebraic expression +to define the function to map over the vector. The symbol @samp{$} +inside this expression represents the argument to the function. +The Calculator applies this formula to each element of the vector, +substituting each element's value for the @samp{$} sign(s) in turn. + +To define a two-argument function, use @samp{$$} for the first +argument and @samp{$} for the second: @kbd{V M ' $$-$ RET} is +equivalent to @kbd{V M -}. This is analogous to regular algebraic +entry, where @samp{$$} would refer to the next-to-top stack entry +and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ RET} +would act exactly like @kbd{-}. + +Notice that the @kbd{V M '} command has recorded two things in the +trail: The result, as usual, and also a funny-looking thing marked +@samp{oper} that represents the operator function you typed in. +The function is enclosed in @samp{< >} brackets, and the argument is +denoted by a @samp{#} sign. If there were several arguments, they +would be shown as @samp{#1}, @samp{#2}, and so on. (For example, +@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the +trail.) This object is a ``nameless function''; you can use nameless +@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like. +Nameless function notation has the interesting, occasionally useful +property that a nameless function is not actually evaluated until +it is used. For example, @kbd{V M ' $+random(2.0)} evaluates +@samp{random(2.0)} once and adds that random number to all elements +of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the +@samp{random(2.0)} separately for each vector element. + +Another group of operators that are often useful with @kbd{V M} are +the relational operators: @kbd{a =}, for example, compares two numbers +and gives the result 1 if they are equal, or 0 if not. Similarly, +@w{@kbd{a <}} checks for one number being less than another. + +Other useful vector operations include @kbd{v v}, to reverse a +vector end-for-end; @kbd{V S}, to sort the elements of a vector +into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract +one row or column of a matrix, or (in both cases) to extract one +element of a plain vector. With a negative argument, @kbd{v r} +and @kbd{v c} instead delete one row, column, or vector element. + +@cindex Divisor functions +(@bullet{}) @strong{Exercise 4.} The @cite{k}th @dfn{divisor function} +@tex +$\sigma_k(n)$ +@end tex +is the sum of the @cite{k}th powers of all the divisors of an +integer @cite{n}. Figure out a method for computing the divisor +function for reasonably small values of @cite{n}. As a test, +the 0th and 1st divisor functions of 30 are 8 and 72, respectively. +@xref{List Answer 4, 4}. (@bullet{}) + +@cindex Square-free numbers +@cindex Duplicate values in a list +(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a +list of prime factors for a number. Sometimes it is important to +know that a number is @dfn{square-free}, i.e., that no prime occurs +more than once in its list of prime factors. Find a sequence of +keystrokes to tell if a number is square-free; your method should +leave 1 on the stack if it is, or 0 if it isn't. +@xref{List Answer 5, 5}. (@bullet{}) + +@cindex Triangular lists +(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks +like the following diagram. (You may wish to use the @kbd{v /} +command to enable multi-line display of vectors.) + +@group +@smallexample +1: [ [1], + [1, 2], + [1, 2, 3], + [1, 2, 3, 4], + [1, 2, 3, 4, 5], + [1, 2, 3, 4, 5, 6] ] +@end smallexample +@end group + +@noindent +@xref{List Answer 6, 6}. (@bullet{}) + +(@bullet{}) @strong{Exercise 7.} Build the following list of lists. + +@group +@smallexample +1: [ [0], + [1, 2], + [3, 4, 5], + [6, 7, 8, 9], + [10, 11, 12, 13, 14], + [15, 16, 17, 18, 19, 20] ] +@end smallexample +@end group + +@noindent +@xref{List Answer 7, 7}. (@bullet{}) + +@cindex Maximizing a function over a list of values +@c [fix-ref Numerical Solutions] +(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's +@c{$J_1(x)$} +@cite{J1} function @samp{besJ(1,x)} for @cite{x} from 0 to 5 +in steps of 0.25. +Find the value of @cite{x} (from among the above set of values) for +which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method, +i.e., just reading along the list by hand to find the largest value +is not allowed! (There is an @kbd{a X} command which does this kind +of thing automatically; @pxref{Numerical Solutions}.) +@xref{List Answer 8, 8}. (@bullet{})@refill + +@cindex Digits, vectors of +(@bullet{}) @strong{Exercise 9.} You are given an integer in the range +@c{$0 \le N < 10^m$} +@cite{0 <= N < 10^m} for @cite{m=12} (i.e., an integer of less than +twelve digits). Convert this integer into a vector of @cite{m} +digits, each in the range from 0 to 9. In vector-of-digits notation, +add one to this integer to produce a vector of @cite{m+1} digits +(since there could be a carry out of the most significant digit). +Convert this vector back into a regular integer. A good integer +to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{}) + +(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use +@kbd{V R a =} to test if all numbers in a list were equal. What +happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{}) + +(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one +is @c{$\pi$} +@cite{pi}. The area of the @c{$2\times2$} +@asis{2x2} square that encloses that +circle is 4. So if we throw @i{N} darts at random points in the square, +about @c{$\pi/4$} +@cite{pi/4} of them will land inside the circle. This gives us +an entertaining way to estimate the value of @c{$\pi$} +@cite{pi}. The @w{@kbd{k r}} +command picks a random number between zero and the value on the stack. +We could get a random floating-point number between @i{-1} and 1 by typing +@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @cite{(x,y)} points in +this square, then use vector mapping and reduction to count how many +points lie inside the unit circle. Hint: Use the @kbd{v b} command. +@xref{List Answer 11, 11}. (@bullet{}) + +@cindex Matchstick problem +(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides +another way to calculate @c{$\pi$} +@cite{pi}. Say you have an infinite field +of vertical lines with a spacing of one inch. Toss a one-inch matchstick +onto the field. The probability that the matchstick will land crossing +a line turns out to be @c{$2/\pi$} +@cite{2/pi}. Toss 100 matchsticks to estimate +@c{$\pi$} +@cite{pi}. (If you want still more fun, the probability that the GCD +(@w{@kbd{k g}}) of two large integers is one turns out to be @c{$6/\pi^2$} +@cite{6/pi^2}. +That provides yet another way to estimate @c{$\pi$} +@cite{pi}.) +@xref{List Answer 12, 12}. (@bullet{}) + +(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in +double-quote marks, @samp{"hello"}, creates a vector of the numerical +(ASCII) codes of the characters (here, @cite{[104, 101, 108, 108, 111]}). +Sometimes it is convenient to compute a @dfn{hash code} of a string, +which is just an integer that represents the value of that string. +Two equal strings have the same hash code; two different strings +@dfn{probably} have different hash codes. (For example, Calc has +over 400 function names, but Emacs can quickly find the definition for +any given name because it has sorted the functions into ``buckets'' by +their hash codes. Sometimes a few names will hash into the same bucket, +but it is easier to search among a few names than among all the names.) +One popular hash function is computed as follows: First set @cite{h = 0}. +Then, for each character from the string in turn, set @cite{h = 3h + c_i} +where @cite{c_i} is the character's ASCII code. If we have 511 buckets, +we then take the hash code modulo 511 to get the bucket number. Develop a +simple command or commands for converting string vectors into hash codes. +The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo +511 is 121. @xref{List Answer 13, 13}. (@bullet{}) + +(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U} +commands do nested function evaluations. @kbd{H V U} takes a starting +value and a number of steps @var{n} from the stack; it then applies the +function you give to the starting value 0, 1, 2, up to @var{n} times +and returns a vector of the results. Use this command to create a +``random walk'' of 50 steps. Start with the two-dimensional point +@cite{(0,0)}; then take one step a random distance between @i{-1} and 1 +in both @cite{x} and @cite{y}; then take another step, and so on. Use the +@kbd{g f} command to display this random walk. Now modify your random +walk to walk a unit distance, but in a random direction, at each step. +(Hint: The @code{sincos} function returns a vector of the cosine and +sine of an angle.) @xref{List Answer 14, 14}. (@bullet{}) + +@node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial +@section Types Tutorial + +@noindent +Calc understands a variety of data types as well as simple numbers. +In this section, we'll experiment with each of these types in turn. + +The numbers we've been using so far have mainly been either @dfn{integers} +or @dfn{floats}. We saw that floats are usually a good approximation to +the mathematical concept of real numbers, but they are only approximations +and are susceptible to roundoff error. Calc also supports @dfn{fractions}, +which can exactly represent any rational number. + +@group +@smallexample +1: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414 + . 1: 49 . . . + . + + 10 ! 49 RET : 2 + & +@end smallexample +@end group + +@noindent +The @kbd{:} command divides two integers to get a fraction; @kbd{/} +would normally divide integers to get a floating-point result. +Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:} +since the @kbd{:} would otherwise be interpreted as part of a +fraction beginning with 49. + +You can convert between floating-point and fractional format using +@kbd{c f} and @kbd{c F}: + +@group +@smallexample +1: 1.35027217629e-5 1: 7:518414 + . . + + c f c F +@end smallexample +@end group + +The @kbd{c F} command replaces a floating-point number with the +``simplest'' fraction whose floating-point representation is the +same, to within the current precision. + +@group +@smallexample +1: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113 + . . . . + + P c F DEL p 5 RET P c F +@end smallexample +@end group + +(@bullet{}) @strong{Exercise 1.} A calculation has produced the +result 1.26508260337. You suspect it is the square root of the +product of @c{$\pi$} +@cite{pi} and some rational number. Is it? (Be sure +to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{}) + +@dfn{Complex numbers} can be stored in both rectangular and polar form. + +@group +@smallexample +1: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.) + . . . . . + + 9 n Q c p 2 * Q +@end smallexample +@end group + +@noindent +The square root of @i{-9} is by default rendered in rectangular form +(@w{@cite{0 + 3i}}), but we can convert it to polar form (3 with a +phase angle of 90 degrees). All the usual arithmetic and scientific +operations are defined on both types of complex numbers. + +Another generalized kind of number is @dfn{infinity}. Infinity +isn't really a number, but it can sometimes be treated like one. +Calc uses the symbol @code{inf} to represent positive infinity, +i.e., a value greater than any real number. Naturally, you can +also write @samp{-inf} for minus infinity, a value less than any +real number. The word @code{inf} can only be input using +algebraic entry. + +@group +@smallexample +2: inf 2: -inf 2: -inf 2: -inf 1: nan +1: -17 1: -inf 1: -inf 1: inf . + . . . . + +' inf RET 17 n * RET 72 + A + +@end smallexample +@end group + +@noindent +Since infinity is infinitely large, multiplying it by any finite +number (like @i{-17}) has no effect, except that since @i{-17} +is negative, it changes a plus infinity to a minus infinity. +(``A huge positive number, multiplied by @i{-17}, yields a huge +negative number.'') Adding any finite number to infinity also +leaves it unchanged. Taking an absolute value gives us plus +infinity again. Finally, we add this plus infinity to the minus +infinity we had earlier. If you work it out, you might expect +the answer to be @i{-72} for this. But the 72 has been completely +lost next to the infinities; by the time we compute @w{@samp{inf - inf}} +the finite difference between them, if any, is indetectable. +So we say the result is @dfn{indeterminate}, which Calc writes +with the symbol @code{nan} (for Not A Number). + +Dividing by zero is normally treated as an error, but you can get +Calc to write an answer in terms of infinity by pressing @kbd{m i} +to turn on ``infinite mode.'' + +@group +@smallexample +3: nan 2: nan 2: nan 2: nan 1: nan +2: 1 1: 1 / 0 1: uinf 1: uinf . +1: 0 . . . + . + + 1 RET 0 / m i U / 17 n * + +@end smallexample +@end group + +@noindent +Dividing by zero normally is left unevaluated, but after @kbd{m i} +it instead gives an infinite result. The answer is actually +@code{uinf}, ``undirected infinity.'' If you look at a graph of +@cite{1 / x} around @w{@cite{x = 0}}, you'll see that it goes toward +plus infinity as you approach zero from above, but toward minus +infinity as you approach from below. Since we said only @cite{1 / 0}, +Calc knows that the answer is infinite but not in which direction. +That's what @code{uinf} means. Notice that multiplying @code{uinf} +by a negative number still leaves plain @code{uinf}; there's no +point in saying @samp{-uinf} because the sign of @code{uinf} is +unknown anyway. Finally, we add @code{uinf} to our @code{nan}, +yielding @code{nan} again. It's easy to see that, because +@code{nan} means ``totally unknown'' while @code{uinf} means +``unknown sign but known to be infinite,'' the more mysterious +@code{nan} wins out when it is combined with @code{uinf}, or, for +that matter, with anything else. + +(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer +for each of these formulas: @samp{inf / inf}, @samp{exp(inf)}, +@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)}, +@samp{abs(uinf)}, @samp{ln(0)}. +@xref{Types Answer 2, 2}. (@bullet{}) + +(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan}, +which stands for an unknown value. Can @code{nan} stand for +a complex number? Can it stand for infinity? +@xref{Types Answer 3, 3}. (@bullet{}) + +@dfn{HMS forms} represent a value in terms of hours, minutes, and +seconds. + +@group +@smallexample +1: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2. + . . 1: 1@@ 45' 0." . + . + + 2@@ 30' RET 1 + RET 2 / / +@end smallexample +@end group + +HMS forms can also be used to hold angles in degrees, minutes, and +seconds. + +@group +@smallexample +1: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721 + . . . . + + 0.5 I T c h S +@end smallexample +@end group + +@noindent +First we convert the inverse tangent of 0.5 to degrees-minutes-seconds +form, then we take the sine of that angle. Note that the trigonometric +functions will accept HMS forms directly as input. + +@cindex Beatles +(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is +47 minutes and 26 seconds long, and contains 17 songs. What is the +average length of a song on @emph{Abbey Road}? If the Extended Disco +Version of @emph{Abbey Road} added 20 seconds to the length of each +song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{}) + +A @dfn{date form} represents a date, or a date and time. Dates must +be entered using algebraic entry. Date forms are surrounded by +@samp{< >} symbols; most standard formats for dates are recognized. + +@group +@smallexample +2: <Sun Jan 13, 1991> 1: 2.25 +1: <6:00pm Thu Jan 10, 1991> . + . + +' <13 Jan 1991>, <1/10/91, 6pm> RET - +@end smallexample +@end group + +@noindent +In this example, we enter two dates, then subtract to find the +number of days between them. It is also possible to add an +HMS form or a number (of days) to a date form to get another +date form. + +@group +@smallexample +1: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991> + . . + + t N 2 + 10@@ 5' + +@end smallexample +@end group + +@c [fix-ref Date Arithmetic] +@noindent +The @kbd{t N} (``now'') command pushes the current date and time on the +stack; then we add two days, ten hours and five minutes to the date and +time. Other date-and-time related commands include @kbd{t J}, which +does Julian day conversions, @kbd{t W}, which finds the beginning of +the week in which a date form lies, and @kbd{t I}, which increments a +date by one or several months. @xref{Date Arithmetic}, for more. + +(@bullet{}) @strong{Exercise 5.} How many days until the next +Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{}) + +(@bullet{}) @strong{Exercise 6.} How many leap years will there be +between now and the year 10001 A.D.? @xref{Types Answer 6, 6}. (@bullet{}) + +@cindex Slope and angle of a line +@cindex Angle and slope of a line +An @dfn{error form} represents a mean value with an attached standard +deviation, or error estimate. Suppose our measurements indicate that +a certain telephone pole is about 30 meters away, with an estimated +error of 1 meter, and 8 meters tall, with an estimated error of 0.2 +meters. What is the slope of a line from here to the top of the +pole, and what is the equivalent angle in degrees? + +@group +@smallexample +1: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594 + . 1: 30 +/- 1 . . + . + + 8 p .2 RET 30 p 1 / I T +@end smallexample +@end group + +@noindent +This means that the angle is about 15 degrees, and, assuming our +original error estimates were valid standard deviations, there is about +a 60% chance that the result is correct within 0.59 degrees. + +@cindex Torus, volume of +(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is +@c{$2 \pi^2 R r^2$} +@w{@cite{2 pi^2 R r^2}} where @cite{R} is the radius of the circle that +defines the center of the tube and @cite{r} is the radius of the tube +itself. Suppose @cite{R} is 20 cm and @cite{r} is 4 cm, each known to +within 5 percent. What is the volume and the relative uncertainty of +the volume? @xref{Types Answer 7, 7}. (@bullet{}) + +An @dfn{interval form} represents a range of values. While an +error form is best for making statistical estimates, intervals give +you exact bounds on an answer. Suppose we additionally know that +our telephone pole is definitely between 28 and 31 meters away, +and that it is between 7.7 and 8.1 meters tall. + +@group +@smallexample +1: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1] + . 1: [28 .. 31] . . + . + + [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T +@end smallexample +@end group + +@noindent +If our bounds were correct, then the angle to the top of the pole +is sure to lie in the range shown. + +The square brackets around these intervals indicate that the endpoints +themselves are allowable values. In other words, the distance to the +telephone pole is between 28 and 31, @emph{inclusive}. You can also +make an interval that is exclusive of its endpoints by writing +parentheses instead of square brackets. You can even make an interval +which is inclusive (``closed'') on one end and exclusive (``open'') on +the other. + +@group +@smallexample +1: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3) + . . 1: [2 .. 3) . + . + + [ 1 .. 10 ) & [ 2 .. 3 ) * +@end smallexample +@end group + +@noindent +The Calculator automatically keeps track of which end values should +be open and which should be closed. You can also make infinite or +semi-infinite intervals by using @samp{-inf} or @samp{inf} for one +or both endpoints. + +(@bullet{}) @strong{Exercise 8.} What answer would you expect from +@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What +about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes +zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}? +@xref{Types Answer 8, 8}. (@bullet{}) + +(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number +are @kbd{RET *} and @w{@kbd{2 ^}}. Normally these produce the same +answer. Would you expect this still to hold true for interval forms? +If not, which of these will result in a larger interval? +@xref{Types Answer 9, 9}. (@bullet{}) + +A @dfn{modulo form} is used for performing arithmetic modulo @i{M}. +For example, arithmetic involving time is generally done modulo 12 +or 24 hours. + +@group +@smallexample +1: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24 + . . . . + + 17 M 24 RET 10 + n 5 / +@end smallexample +@end group + +@noindent +In this last step, Calc has found a new number which, when multiplied +by 5 modulo 24, produces the original number, 21. If @i{M} is prime +it is always possible to find such a number. For non-prime @i{M} +like 24, it is only sometimes possible. + +@group +@smallexample +1: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16 + . . . . + + 10 M 24 RET 100 ^ 10 RET 100 ^ 24 % +@end smallexample +@end group + +@noindent +These two calculations get the same answer, but the first one is +much more efficient because it avoids the huge intermediate value +that arises in the second one. + +@cindex Fermat, primality test of +(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat +says that @c{\w{$x^{n-1} \bmod n = 1$}} +@cite{x^(n-1) mod n = 1} if @cite{n} is a prime number +and @cite{x} is an integer less than @cite{n}. If @cite{n} is +@emph{not} a prime number, this will @emph{not} be true for most +values of @cite{x}. Thus we can test informally if a number is +prime by trying this formula for several values of @cite{x}. +Use this test to tell whether the following numbers are prime: +811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{}) + +It is possible to use HMS forms as parts of error forms, intervals, +modulo forms, or as the phase part of a polar complex number. +For example, the @code{calc-time} command pushes the current time +of day on the stack as an HMS/modulo form. + +@group +@smallexample +1: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0" + . . + + x time RET n +@end smallexample +@end group + +@noindent +This calculation tells me it is six hours and 22 minutes until midnight. + +(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year +is about @c{$\pi \times 10^7$} +@w{@cite{pi * 10^7}} seconds. What time will it be that +many seconds from right now? @xref{Types Answer 11, 11}. (@bullet{}) + +(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging +for the CD release of the Extended Disco Version of @emph{Abbey Road}. +You are told that the songs will actually be anywhere from 20 to 60 +seconds longer than the originals. One CD can hold about 75 minutes +of music. Should you order single or double packages? +@xref{Types Answer 12, 12}. (@bullet{}) + +Another kind of data the Calculator can manipulate is numbers with +@dfn{units}. This isn't strictly a new data type; it's simply an +application of algebraic expressions, where we use variables with +suggestive names like @samp{cm} and @samp{in} to represent units +like centimeters and inches. + +@group +@smallexample +1: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m + . . . . + + ' 2in RET u c cm RET u c fath RET u b +@end smallexample +@end group + +@noindent +We enter the quantity ``2 inches'' (actually an algebraic expression +which means two times the variable @samp{in}), then we convert it +first to centimeters, then to fathoms, then finally to ``base'' units, +which in this case means meters. + +@group +@smallexample +1: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm + . . . . + + ' 9 acre RET Q u s ' $+30 cm RET + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2 + . . . + + u s 2 ^ u c cgs +@end smallexample +@end group + +@noindent +Since units expressions are really just formulas, taking the square +root of @samp{acre} is undefined. After all, @code{acre} might be an +algebraic variable that you will someday assign a value. We use the +``units-simplify'' command to simplify the expression with variables +being interpreted as unit names. + +In the final step, we have converted not to a particular unit, but to a +units system. The ``cgs'' system uses centimeters instead of meters +as its standard unit of length. + +There is a wide variety of units defined in the Calculator. + +@group +@smallexample +1: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c + . . . . + + ' 55 mph RET u c kph RET u c km/hr RET u c c RET +@end smallexample +@end group + +@noindent +We express a speed first in miles per hour, then in kilometers per +hour, then again using a slightly more explicit notation, then +finally in terms of fractions of the speed of light. + +Temperature conversions are a bit more tricky. There are two ways to +interpret ``20 degrees Fahrenheit''---it could mean an actual +temperature, or it could mean a change in temperature. For normal +units there is no difference, but temperature units have an offset +as well as a scale factor and so there must be two explicit commands +for them. + +@group +@smallexample +1: 20 degF 1: 11.1111 degC 1: -20:3 degC 1: -6.666 degC + . . . . + + ' 20 degF RET u c degC RET U u t degC RET c f +@end smallexample +@end group + +@noindent +First we convert a change of 20 degrees Fahrenheit into an equivalent +change in degrees Celsius (or Centigrade). Then, we convert the +absolute temperature 20 degrees Fahrenheit into Celsius. Since +this comes out as an exact fraction, we then convert to floating-point +for easier comparison with the other result. + +For simple unit conversions, you can put a plain number on the stack. +Then @kbd{u c} and @kbd{u t} will prompt for both old and new units. +When you use this method, you're responsible for remembering which +numbers are in which units: + +@group +@smallexample +1: 55 1: 88.5139 1: 8.201407e-8 + . . . + + 55 u c mph RET kph RET u c km/hr RET c RET +@end smallexample +@end group + +To see a complete list of built-in units, type @kbd{u v}. Press +@w{@kbd{M-# c}} again to re-enter the Calculator when you're done looking +at the units table. + +(@bullet{}) @strong{Exercise 13.} How many seconds are there really +in a year? @xref{Types Answer 13, 13}. (@bullet{}) + +@cindex Speed of light +(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by +the speed of light (and of electricity, which is nearly as fast). +Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its +cabinet is one meter across. Is speed of light going to be a +significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{}) + +(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about +five yards in an hour. He has obtained a supply of Power Pills; each +Power Pill he eats doubles his speed. How many Power Pills can he +swallow and still travel legally on most US highways? +@xref{Types Answer 15, 15}. (@bullet{}) + +@node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial +@section Algebra and Calculus Tutorial + +@noindent +This section shows how to use Calc's algebra facilities to solve +equations, do simple calculus problems, and manipulate algebraic +formulas. + +@menu +* Basic Algebra Tutorial:: +* Rewrites Tutorial:: +@end menu + +@node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial +@subsection Basic Algebra + +@noindent +If you enter a formula in algebraic mode that refers to variables, +the formula itself is pushed onto the stack. You can manipulate +formulas as regular data objects. + +@group +@smallexample +1: 2 x^2 - 6 1: 6 - 2 x^2 1: (6 - 2 x^2) (3 x^2 + y) + . . . + + ' 2x^2-6 RET n ' 3x^2+y RET * +@end smallexample +@end group + +(@bullet{}) @strong{Exercise 1.} Do @kbd{' x RET Q 2 ^} and +@kbd{' x RET 2 ^ Q} both wind up with the same result (@samp{x})? +Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{}) + +There are also commands for doing common algebraic operations on +formulas. Continuing with the formula from the last example, + +@group +@smallexample +1: 18 x^2 + 6 y - 6 x^4 - 2 x^2 y 1: (18 - 2 y) x^2 - 6 x^4 + 6 y + . . + + a x a c x RET +@end smallexample +@end group + +@noindent +First we ``expand'' using the distributive law, then we ``collect'' +terms involving like powers of @cite{x}. + +Let's find the value of this expression when @cite{x} is 2 and @cite{y} +is one-half. + +@group +@smallexample +1: 17 x^2 - 6 x^4 + 3 1: -25 + . . + + 1:2 s l y RET 2 s l x RET +@end smallexample +@end group + +@noindent +The @kbd{s l} command means ``let''; it takes a number from the top of +the stack and temporarily assigns it as the value of the variable +you specify. It then evaluates (as if by the @kbd{=} key) the +next expression on the stack. After this command, the variable goes +back to its original value, if any. + +(An earlier exercise in this tutorial involved storing a value in the +variable @code{x}; if this value is still there, you will have to +unstore it with @kbd{s u x RET} before the above example will work +properly.) + +@cindex Maximum of a function using Calculus +Let's find the maximum value of our original expression when @cite{y} +is one-half and @cite{x} ranges over all possible values. We can +do this by taking the derivative with respect to @cite{x} and examining +values of @cite{x} for which the derivative is zero. If the second +derivative of the function at that value of @cite{x} is negative, +the function has a local maximum there. + +@group +@smallexample +1: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3 + . . + + U DEL s 1 a d x RET s 2 +@end smallexample +@end group + +@noindent +Well, the derivative is clearly zero when @cite{x} is zero. To find +the other root(s), let's divide through by @cite{x} and then solve: + +@group +@smallexample +1: (34 x - 24 x^3) / x 1: 34 x / x - 24 x^3 / x 1: 34 - 24 x^2 + . . . + + ' x RET / a x a s + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 34 - 24 x^2 = 0 1: x = 1.19023 + . . + + 0 a = s 3 a S x RET +@end smallexample +@end group + +@noindent +Notice the use of @kbd{a s} to ``simplify'' the formula. When the +default algebraic simplifications don't do enough, you can use +@kbd{a s} to tell Calc to spend more time on the job. + +Now we compute the second derivative and plug in our values of @cite{x}: + +@group +@smallexample +1: 1.19023 2: 1.19023 2: 1.19023 + . 1: 34 x - 24 x^3 1: 34 - 72 x^2 + . . + + a . r 2 a d x RET s 4 +@end smallexample +@end group + +@noindent +(The @kbd{a .} command extracts just the righthand side of an equation. +Another method would have been to use @kbd{v u} to unpack the equation +@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 DEL} +to delete the @samp{x}.) + +@group +@smallexample +2: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34 +1: 1.19023 . 1: 0 . + . . + + TAB s l x RET U DEL 0 s l x RET +@end smallexample +@end group + +@noindent +The first of these second derivatives is negative, so we know the function +has a maximum value at @cite{x = 1.19023}. (The function also has a +local @emph{minimum} at @cite{x = 0}.) + +When we solved for @cite{x}, we got only one value even though +@cite{34 - 24 x^2 = 0} is a quadratic equation that ought to have +two solutions. The reason is that @w{@kbd{a S}} normally returns a +single ``principal'' solution. If it needs to come up with an +arbitrary sign (as occurs in the quadratic formula) it picks @cite{+}. +If it needs an arbitrary integer, it picks zero. We can get a full +solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}. + +@group +@smallexample +1: 34 - 24 x^2 = 0 1: x = 1.19023 s1 1: x = -1.19023 + . . . + + r 3 H a S x RET s 5 1 n s l s1 RET +@end smallexample +@end group + +@noindent +Calc has invented the variable @samp{s1} to represent an unknown sign; +it is supposed to be either @i{+1} or @i{-1}. Here we have used +the ``let'' command to evaluate the expression when the sign is negative. +If we plugged this into our second derivative we would get the same, +negative, answer, so @cite{x = -1.19023} is also a maximum. + +To find the actual maximum value, we must plug our two values of @cite{x} +into the original formula. + +@group +@smallexample +2: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3 +1: x = 1.19023 s1 . + . + + r 1 r 5 s l RET +@end smallexample +@end group + +@noindent +(Here we see another way to use @kbd{s l}; if its input is an equation +with a variable on the lefthand side, then @kbd{s l} treats the equation +like an assignment to that variable if you don't give a variable name.) + +It's clear that this will have the same value for either sign of +@code{s1}, but let's work it out anyway, just for the exercise: + +@group +@smallexample +2: [-1, 1] 1: [15.04166, 15.04166] +1: 24.08333 s1^2 ... . + . + + [ 1 n , 1 ] TAB V M $ RET +@end smallexample +@end group + +@noindent +Here we have used a vector mapping operation to evaluate the function +at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '} +except that it takes the formula from the top of the stack. The +formula is interpreted as a function to apply across the vector at the +next-to-top stack level. Since a formula on the stack can't contain +@samp{$} signs, Calc assumes the variables in the formula stand for +different arguments. It prompts you for an @dfn{argument list}, giving +the list of all variables in the formula in alphabetical order as the +default list. In this case the default is @samp{(s1)}, which is just +what we want so we simply press @key{RET} at the prompt. + +If there had been several different values, we could have used +@w{@kbd{V R X}} to find the global maximum. + +Calc has a built-in @kbd{a P} command that solves an equation using +@w{@kbd{H a S}} and returns a vector of all the solutions. It simply +automates the job we just did by hand. Applied to our original +cubic polynomial, it would produce the vector of solutions +@cite{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command +which finds a local maximum of a function. It uses a numerical search +method rather than examining the derivatives, and thus requires you +to provide some kind of initial guess to show it where to look.) + +(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a +polynomial (such as the output of an @kbd{a P} command), what +sequence of commands would you use to reconstruct the original +polynomial? (The answer will be unique to within a constant +multiple; choose the solution where the leading coefficient is one.) +@xref{Algebra Answer 2, 2}. (@bullet{}) + +The @kbd{m s} command enables ``symbolic mode,'' in which formulas +like @samp{sqrt(5)} that can't be evaluated exactly are left in +symbolic form rather than giving a floating-point approximate answer. +Fraction mode (@kbd{m f}) is also useful when doing algebra. + +@group +@smallexample +2: 34 x - 24 x^3 2: 34 x - 24 x^3 +1: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0] + . . + + r 2 RET m s m f a P x RET +@end smallexample +@end group + +One more mode that makes reading formulas easier is ``Big mode.'' + +@group +@smallexample + 3 +2: 34 x - 24 x + + ____ ____ + V 51 V 51 +1: [-----, -----, 0] + 6 -6 + + . + + d B +@end smallexample +@end group + +Here things like powers, square roots, and quotients and fractions +are displayed in a two-dimensional pictorial form. Calc has other +language modes as well, such as C mode, FORTRAN mode, and @TeX{} mode. + +@group +@smallexample +2: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3 +1: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/ + . . + + d C d F + +@end smallexample +@end group +@noindent +@group +@smallexample +3: 34 x - 24 x^3 +2: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0] +1: @{2 \over 3@} \sqrt@{5@} + . + + d T ' 2 \sqrt@{5@} \over 3 RET +@end smallexample +@end group + +@noindent +As you can see, language modes affect both entry and display of +formulas. They affect such things as the names used for built-in +functions, the set of arithmetic operators and their precedences, +and notations for vectors and matrices. + +Notice that @samp{sqrt(51)} may cause problems with older +implementations of C and FORTRAN, which would require something more +like @samp{sqrt(51.0)}. It is always wise to check over the formulas +produced by the various language modes to make sure they are fully +correct. + +Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You +may prefer to remain in Big mode, but all the examples in the tutorial +are shown in normal mode.) + +@cindex Area under a curve +What is the area under the portion of this curve from @cite{x = 1} to @cite{2}? +This is simply the integral of the function: + +@group +@smallexample +1: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x + . . + + r 1 a i x +@end smallexample +@end group + +@noindent +We want to evaluate this at our two values for @cite{x} and subtract. +One way to do it is again with vector mapping and reduction: + +@group +@smallexample +2: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666 +1: 5.6666 x^3 ... . . + + [ 2 , 1 ] TAB V M $ RET V R - +@end smallexample +@end group + +(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @cite{y} +of @c{$x \sin \pi x$} +@w{@cite{x sin(pi x)}} (where the sine is calculated in radians). +Find the values of the integral for integers @cite{y} from 1 to 5. +@xref{Algebra Answer 3, 3}. (@bullet{}) + +Calc's integrator can do many simple integrals symbolically, but many +others are beyond its capabilities. Suppose we wish to find the area +under the curve @c{$\sin x \ln x$} +@cite{sin(x) ln(x)} over the same range of @cite{x}. If +you entered this formula and typed @kbd{a i x RET} (don't bother to try +this), Calc would work for a long time but would be unable to find a +solution. In fact, there is no closed-form solution to this integral. +Now what do we do? + +@cindex Integration, numerical +@cindex Numerical integration +One approach would be to do the integral numerically. It is not hard +to do this by hand using vector mapping and reduction. It is rather +slow, though, since the sine and logarithm functions take a long time. +We can save some time by reducing the working precision. + +@group +@smallexample +3: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9] +2: 1 . +1: 0.1 + . + + 10 RET 1 RET .1 RET C-u v x +@end smallexample +@end group + +@noindent +(Note that we have used the extended version of @kbd{v x}; we could +also have used plain @kbd{v x} as follows: @kbd{v x 10 RET 9 + .1 *}.) + +@group +@smallexample +2: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ] +1: sin(x) ln(x) . + . + + ' sin(x) ln(x) RET s 1 m r p 5 RET V M $ RET + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 3.4195 0.34195 + . . + + V R + 0.1 * +@end smallexample +@end group + +@noindent +(If you got wildly different results, did you remember to switch +to radians mode?) + +Here we have divided the curve into ten segments of equal width; +approximating these segments as rectangular boxes (i.e., assuming +the curve is nearly flat at that resolution), we compute the areas +of the boxes (height times width), then sum the areas. (It is +faster to sum first, then multiply by the width, since the width +is the same for every box.) + +The true value of this integral turns out to be about 0.374, so +we're not doing too well. Let's try another approach. + +@group +@smallexample +1: sin(x) ln(x) 1: 0.84147 x - 0.84147 + 0.11957 (x - 1)^2 - ... + . . + + r 1 a t x=1 RET 4 RET +@end smallexample +@end group + +@noindent +Here we have computed the Taylor series expansion of the function +about the point @cite{x=1}. We can now integrate this polynomial +approximation, since polynomials are easy to integrate. + +@group +@smallexample +1: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761 + . . . + + a i x RET [ 2 , 1 ] TAB V M $ RET V R - +@end smallexample +@end group + +@noindent +Better! By increasing the precision and/or asking for more terms +in the Taylor series, we can get a result as accurate as we like. +(Taylor series converge better away from singularities in the +function such as the one at @code{ln(0)}, so it would also help to +expand the series about the points @cite{x=2} or @cite{x=1.5} instead +of @cite{x=1}.) + +@cindex Simpson's rule +@cindex Integration by Simpson's rule +(@bullet{}) @strong{Exercise 4.} Our first method approximated the +curve by stairsteps of width 0.1; the total area was then the sum +of the areas of the rectangles under these stairsteps. Our second +method approximated the function by a polynomial, which turned out +to be a better approximation than stairsteps. A third method is +@dfn{Simpson's rule}, which is like the stairstep method except +that the steps are not required to be flat. Simpson's rule boils +down to the formula, + +@ifinfo +@example +(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ... + + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h)) +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ \displaylines{ + \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots + \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad +} $$ +\afterdisplay +@end tex + +@noindent +where @cite{n} (which must be even) is the number of slices and @cite{h} +is the width of each slice. These are 10 and 0.1 in our example. +For reference, here is the corresponding formula for the stairstep +method: + +@ifinfo +@example +h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ... + + f(a+(n-2)*h) + f(a+(n-1)*h)) +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots + + f(a+(n-2)h) + f(a+(n-1)h)) $$ +\afterdisplay +@end tex + +Compute the integral from 1 to 2 of @c{$\sin x \ln x$} +@cite{sin(x) ln(x)} using +Simpson's rule with 10 slices. @xref{Algebra Answer 4, 4}. (@bullet{}) + +Calc has a built-in @kbd{a I} command for doing numerical integration. +It uses @dfn{Romberg's method}, which is a more sophisticated cousin +of Simpson's rule. In particular, it knows how to keep refining the +result until the current precision is satisfied. + +@c [fix-ref Selecting Sub-Formulas] +Aside from the commands we've seen so far, Calc also provides a +large set of commands for operating on parts of formulas. You +indicate the desired sub-formula by placing the cursor on any part +of the formula before giving a @dfn{selection} command. Selections won't +be covered in the tutorial; @pxref{Selecting Subformulas}, for +details and examples. + +@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1) +@c to 2^((n-1)*(r-1)). + +@node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial +@subsection Rewrite Rules + +@noindent +No matter how many built-in commands Calc provided for doing algebra, +there would always be something you wanted to do that Calc didn't have +in its repertoire. So Calc also provides a @dfn{rewrite rule} system +that you can use to define your own algebraic manipulations. + +Suppose we want to simplify this trigonometric formula: + +@group +@smallexample +1: 1 / cos(x) - sin(x) tan(x) + . + + ' 1/cos(x) - sin(x) tan(x) RET s 1 +@end smallexample +@end group + +@noindent +If we were simplifying this by hand, we'd probably replace the +@samp{tan} with a @samp{sin/cos} first, then combine over a common +denominator. There is no Calc command to do the former; the @kbd{a n} +algebra command will do the latter but we'll do both with rewrite +rules just for practice. + +Rewrite rules are written with the @samp{:=} symbol. + +@group +@smallexample +1: 1 / cos(x) - sin(x)^2 / cos(x) + . + + a r tan(a) := sin(a)/cos(a) RET +@end smallexample +@end group + +@noindent +(The ``assignment operator'' @samp{:=} has several uses in Calc. All +by itself the formula @samp{tan(a) := sin(a)/cos(a)} doesn't do anything, +but when it is given to the @kbd{a r} command, that command interprets +it as a rewrite rule.) + +The lefthand side, @samp{tan(a)}, is called the @dfn{pattern} of the +rewrite rule. Calc searches the formula on the stack for parts that +match the pattern. Variables in a rewrite pattern are called +@dfn{meta-variables}, and when matching the pattern each meta-variable +can match any sub-formula. Here, the meta-variable @samp{a} matched +the actual variable @samp{x}. + +When the pattern part of a rewrite rule matches a part of the formula, +that part is replaced by the righthand side with all the meta-variables +substituted with the things they matched. So the result is +@samp{sin(x) / cos(x)}. Calc's normal algebraic simplifications then +mix this in with the rest of the original formula. + +To merge over a common denominator, we can use another simple rule: + +@group +@smallexample +1: (1 - sin(x)^2) / cos(x) + . + + a r a/x + b/x := (a+b)/x RET +@end smallexample +@end group + +This rule points out several interesting features of rewrite patterns. +First, if a meta-variable appears several times in a pattern, it must +match the same thing everywhere. This rule detects common denominators +because the same meta-variable @samp{x} is used in both of the +denominators. + +Second, meta-variable names are independent from variables in the +target formula. Notice that the meta-variable @samp{x} here matches +the subformula @samp{cos(x)}; Calc never confuses the two meanings of +@samp{x}. + +And third, rewrite patterns know a little bit about the algebraic +properties of formulas. The pattern called for a sum of two quotients; +Calc was able to match a difference of two quotients by matching +@samp{a = 1}, @samp{b = -sin(x)^2}, and @samp{x = cos(x)}. + +@c [fix-ref Algebraic Properties of Rewrite Rules] +We could just as easily have written @samp{a/x - b/x := (a-b)/x} for +the rule. It would have worked just the same in all cases. (If we +really wanted the rule to apply only to @samp{+} or only to @samp{-}, +we could have used the @code{plain} symbol. @xref{Algebraic Properties +of Rewrite Rules}, for some examples of this.) + +One more rewrite will complete the job. We want to use the identity +@samp{sin(x)^2 + cos(x)^2 = 1}, but of course we must first rearrange +the identity in a way that matches our formula. The obvious rule +would be @samp{@w{1 - sin(x)^2} := cos(x)^2}, but a little thought shows +that the rule @samp{sin(x)^2 := 1 - cos(x)^2} will also work. The +latter rule has a more general pattern so it will work in many other +situations, too. + +@group +@smallexample +1: (1 + cos(x)^2 - 1) / cos(x) 1: cos(x) + . . + + a r sin(x)^2 := 1 - cos(x)^2 RET a s +@end smallexample +@end group + +You may ask, what's the point of using the most general rule if you +have to type it in every time anyway? The answer is that Calc allows +you to store a rewrite rule in a variable, then give the variable +name in the @kbd{a r} command. In fact, this is the preferred way to +use rewrites. For one, if you need a rule once you'll most likely +need it again later. Also, if the rule doesn't work quite right you +can simply Undo, edit the variable, and run the rule again without +having to retype it. + +@group +@smallexample +' tan(x) := sin(x)/cos(x) RET s t tsc RET +' a/x + b/x := (a+b)/x RET s t merge RET +' sin(x)^2 := 1 - cos(x)^2 RET s t sinsqr RET + +1: 1 / cos(x) - sin(x) tan(x) 1: cos(x) + . . + + r 1 a r tsc RET a r merge RET a r sinsqr RET a s +@end smallexample +@end group + +To edit a variable, type @kbd{s e} and the variable name, use regular +Emacs editing commands as necessary, then type @kbd{M-# M-#} or +@kbd{C-c C-c} to store the edited value back into the variable. +You can also use @w{@kbd{s e}} to create a new variable if you wish. + +Notice that the first time you use each rule, Calc puts up a ``compiling'' +message briefly. The pattern matcher converts rules into a special +optimized pattern-matching language rather than using them directly. +This allows @kbd{a r} to apply even rather complicated rules very +efficiently. If the rule is stored in a variable, Calc compiles it +only once and stores the compiled form along with the variable. That's +another good reason to store your rules in variables rather than +entering them on the fly. + +(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get symbolic +mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}. +Using a rewrite rule, simplify this formula by multiplying both +sides by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have +to be expanded by the distributive law; do this with another +rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{}) + +The @kbd{a r} command can also accept a vector of rewrite rules, or +a variable containing a vector of rules. + +@group +@smallexample +1: [tsc, merge, sinsqr] 1: [tan(x) := sin(x) / cos(x), ... ] + . . + + ' [tsc,merge,sinsqr] RET = + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 1 / cos(x) - sin(x) tan(x) 1: cos(x) + . . + + s t trig RET r 1 a r trig RET a s +@end smallexample +@end group + +@c [fix-ref Nested Formulas with Rewrite Rules] +Calc tries all the rules you give against all parts of the formula, +repeating until no further change is possible. (The exact order in +which things are tried is rather complex, but for simple rules like +the ones we've used here the order doesn't really matter. +@xref{Nested Formulas with Rewrite Rules}.) + +Calc actually repeats only up to 100 times, just in case your rule set +has gotten into an infinite loop. You can give a numeric prefix argument +to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does +only one rewrite at a time. + +@group +@smallexample +1: 1 / cos(x) - sin(x)^2 / cos(x) 1: (1 - sin(x)^2) / cos(x) + . . + + r 1 M-1 a r trig RET M-1 a r trig RET +@end smallexample +@end group + +You can type @kbd{M-0 a r} if you want no limit at all on the number +of rewrites that occur. + +Rewrite rules can also be @dfn{conditional}. Simply follow the rule +with a @samp{::} symbol and the desired condition. For example, + +@group +@smallexample +1: exp(2 pi i) + exp(3 pi i) + exp(4 pi i) + . + + ' exp(2 pi i) + exp(3 pi i) + exp(4 pi i) RET + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 1 + exp(3 pi i) + 1 + . + + a r exp(k pi i) := 1 :: k % 2 = 0 RET +@end smallexample +@end group + +@noindent +(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2, +which will be zero only when @samp{k} is an even integer.) + +An interesting point is that the variables @samp{pi} and @samp{i} +were matched literally rather than acting as meta-variables. +This is because they are special-constant variables. The special +constants @samp{e}, @samp{phi}, and so on also match literally. +A common error with rewrite +rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting +to match any @samp{f} with five arguments but in fact matching +only when the fifth argument is literally @samp{e}!@refill + +@cindex Fibonacci numbers +@c @starindex +@tindex fib +Rewrite rules provide an interesting way to define your own functions. +Suppose we want to define @samp{fib(n)} to produce the @var{n}th +Fibonacci number. The first two Fibonacci numbers are each 1; +later numbers are formed by summing the two preceding numbers in +the sequence. This is easy to express in a set of three rules: + +@group +@smallexample +' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] RET s t fib + +1: fib(7) 1: 13 + . . + + ' fib(7) RET a r fib RET +@end smallexample +@end group + +One thing that is guaranteed about the order that rewrites are tried +is that, for any given subformula, earlier rules in the rule set will +be tried for that subformula before later ones. So even though the +first and third rules both match @samp{fib(1)}, we know the first will +be used preferentially. + +This rule set has one dangerous bug: Suppose we apply it to the +formula @samp{fib(x)}? (Don't actually try this.) The third rule +will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}. +Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) + +fib(x-4)}, and so on, expanding forever. What we really want is to apply +the third rule only when @samp{n} is an integer greater than two. Type +@w{@kbd{s e fib RET}}, then edit the third rule to: + +@smallexample +fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 +@end smallexample + +@noindent +Now: + +@group +@smallexample +1: fib(6) + fib(x) + fib(0) 1: 8 + fib(x) + fib(0) + . . + + ' fib(6)+fib(x)+fib(0) RET a r fib RET +@end smallexample +@end group + +@noindent +We've created a new function, @code{fib}, and a new command, +@w{@kbd{a r fib RET}}, which means ``evaluate all @code{fib} calls in +this formula.'' To make things easier still, we can tell Calc to +apply these rules automatically by storing them in the special +variable @code{EvalRules}. + +@group +@smallexample +1: [fib(1) := ...] . 1: [8, 13] + . . + + s r fib RET s t EvalRules RET ' [fib(6), fib(7)] RET +@end smallexample +@end group + +It turns out that this rule set has the problem that it does far +more work than it needs to when @samp{n} is large. Consider the +first few steps of the computation of @samp{fib(6)}: + +@group +@smallexample +fib(6) = +fib(5) + fib(4) = +fib(4) + fib(3) + fib(3) + fib(2) = +fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ... +@end smallexample +@end group + +@noindent +Note that @samp{fib(3)} appears three times here. Unless Calc's +algebraic simplifier notices the multiple @samp{fib(3)}s and combines +them (and, as it happens, it doesn't), this rule set does lots of +needless recomputation. To cure the problem, type @code{s e EvalRules} +to edit the rules (or just @kbd{s E}, a shorthand command for editing +@code{EvalRules}) and add another condition: + +@smallexample +fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember +@end smallexample + +@noindent +If a @samp{:: remember} condition appears anywhere in a rule, then if +that rule succeeds Calc will add another rule that describes that match +to the front of the rule set. (Remembering works in any rule set, but +for technical reasons it is most effective in @code{EvalRules}.) For +example, if the rule rewrites @samp{fib(7)} to something that evaluates +to 13, then the rule @samp{fib(7) := 13} will be added to the rule set. + +Type @kbd{' fib(8) RET} to compute the eighth Fibonacci number, then +type @kbd{s E} again to see what has happened to the rule set. + +With the @code{remember} feature, our rule set can now compute +@samp{fib(@var{n})} in just @var{n} steps. In the process it builds +up a table of all Fibonacci numbers up to @var{n}. After we have +computed the result for a particular @var{n}, we can get it back +(and the results for all smaller @var{n}) later in just one step. + +All Calc operations will run somewhat slower whenever @code{EvalRules} +contains any rules. You should type @kbd{s u EvalRules RET} now to +un-store the variable. + +(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate +a problem to reduce the amount of recursion necessary to solve it. +Create a rule that, in about @var{n} simple steps and without recourse +to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with +@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the +@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is +rather clunky to use, so add a couple more rules to make the ``user +interface'' the same as for our first version: enter @samp{fib(@var{n})}, +get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{}) + +There are many more things that rewrites can do. For example, there +are @samp{&&&} and @samp{|||} pattern operators that create ``and'' +and ``or'' combinations of rules. As one really simple example, we +could combine our first two Fibonacci rules thusly: + +@example +[fib(1 ||| 2) := 1, fib(n) := ... ] +@end example + +@noindent +That means ``@code{fib} of something matching either 1 or 2 rewrites +to 1.'' + +You can also make meta-variables optional by enclosing them in @code{opt}. +For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not +@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x} +matches all of these forms, filling in a default of zero for @samp{a} +and one for @samp{b}. + +(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x} +on the stack and tried to use the rule +@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened? +@xref{Rewrites Answer 3, 3}. (@bullet{}) + +(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @cite{a}, +divide @cite{a} by two if it is even, otherwise compute @cite{3 a + 1}. +Now repeat this step over and over. A famous unproved conjecture +is that for any starting @cite{a}, the sequence always eventually +reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of +rules that convert this into @samp{seq(1, @var{n})} where @var{n} +is the number of steps it took the sequence to reach the value 1. +Now enhance the rules to accept @samp{seq(@var{a})} as a starting +configuration, and to stop with just the number @var{n} by itself. +Now make the result be a vector of values in the sequence, from @var{a} +to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x} +and @var{y}.) For example, rewriting @samp{seq(6)} should yield the +vector @cite{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. +@xref{Rewrites Answer 4, 4}. (@bullet{}) + +(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function +@samp{nterms(@var{x})} that returns the number of terms in the sum +@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes +is one or more non-sum terms separated by @samp{+} or @samp{-} signs, +so that @cite{2 - 3 (x + y) + x y} is a sum of three terms.) +@xref{Rewrites Answer 5, 5}. (@bullet{}) + +(@bullet{}) @strong{Exercise 6.} Calc considers the form @cite{0^0} +to be ``indeterminate,'' and leaves it unevaluated (assuming infinite +mode is not enabled). Some people prefer to define @cite{0^0 = 1}, +so that the identity @cite{x^0 = 1} can safely be used for all @cite{x}. +Find a way to make Calc follow this convention. What happens if you +now type @kbd{m i} to turn on infinite mode? +@xref{Rewrites Answer 6, 6}. (@bullet{}) + +(@bullet{}) @strong{Exercise 7.} A Taylor series for a function is an +infinite series that exactly equals the value of that function at +values of @cite{x} near zero. + +@ifinfo +@example +cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ... +@end example +@end ifinfo +@tex +\turnoffactive \let\rm\goodrm +\beforedisplay +$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$ +\afterdisplay +@end tex + +The @kbd{a t} command produces a @dfn{truncated Taylor series} which +is obtained by dropping all the terms higher than, say, @cite{x^2}. +Calc represents the truncated Taylor series as a polynomial in @cite{x}. +Mathematicians often write a truncated series using a ``big-O'' notation +that records what was the lowest term that was truncated. + +@ifinfo +@example +cos(x) = 1 - x^2 / 2! + O(x^3) +@end example +@end ifinfo +@tex +\turnoffactive \let\rm\goodrm +\beforedisplay +$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$ +\afterdisplay +@end tex + +@noindent +The meaning of @cite{O(x^3)} is ``a quantity which is negligibly small +if @cite{x^3} is considered negligibly small as @cite{x} goes to zero.'' + +The exercise is to create rewrite rules that simplify sums and products of +power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}. +For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)} +on the stack, we want to be able to type @kbd{*} and get the result +@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are +rearranged or if @kbd{a s} needs to be typed after rewriting. (This one +is rather tricky; the solution at the end of this chapter uses 6 rewrite +rules. Hint: The @samp{constant(x)} condition tests whether @samp{x} is +a number.) @xref{Rewrites Answer 7, 7}. (@bullet{}) + +@c [fix-ref Rewrite Rules] +@xref{Rewrite Rules}, for the whole story on rewrite rules. + +@node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial +@section Programming Tutorial + +@noindent +The Calculator is written entirely in Emacs Lisp, a highly extensible +language. If you know Lisp, you can program the Calculator to do +anything you like. Rewrite rules also work as a powerful programming +system. But Lisp and rewrite rules take a while to master, and often +all you want to do is define a new function or repeat a command a few +times. Calc has features that allow you to do these things easily. + +(Note that the programming commands relating to user-defined keys +are not yet supported under Lucid Emacs 19.) + +One very limited form of programming is defining your own functions. +Calc's @kbd{Z F} command allows you to define a function name and +key sequence to correspond to any formula. Programming commands use +the shift-@kbd{Z} prefix; the user commands they create use the lower +case @kbd{z} prefix. + +@group +@smallexample +1: 1 + x + x^2 / 2 + x^3 / 6 1: 1 + x + x^2 / 2 + x^3 / 6 + . . + + ' 1 + x + x^2/2! + x^3/3! RET Z F e myexp RET RET RET y +@end smallexample +@end group + +This polynomial is a Taylor series approximation to @samp{exp(x)}. +The @kbd{Z F} command asks a number of questions. The above answers +say that the key sequence for our function should be @kbd{z e}; the +@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the +function in algebraic formulas should also be @code{myexp}; the +default argument list @samp{(x)} is acceptable; and finally @kbd{y} +answers the question ``leave it in symbolic form for non-constant +arguments?'' + +@group +@smallexample +1: 1.3495 2: 1.3495 3: 1.3495 + . 1: 1.34986 2: 1.34986 + . 1: myexp(a + 1) + . + + .3 z e .3 E ' a+1 RET z e +@end smallexample +@end group + +@noindent +First we call our new @code{exp} approximation with 0.3 as an +argument, and compare it with the true @code{exp} function. Then +we note that, as requested, if we try to give @kbd{z e} an +argument that isn't a plain number, it leaves the @code{myexp} +function call in symbolic form. If we had answered @kbd{n} to the +final question, @samp{myexp(a + 1)} would have evaluated by plugging +in @samp{a + 1} for @samp{x} in the defining formula. + +@cindex Sine integral Si(x) +@c @starindex +@tindex Si +(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function +@c{${\rm Si}(x)$} +@cite{Si(x)} is defined as the integral of @samp{sin(t)/t} for +@cite{t = 0} to @cite{x} in radians. (It was invented because this +integral has no solution in terms of basic functions; if you give it +to Calc's @kbd{a i} command, it will ponder it for a long time and then +give up.) We can use the numerical integration command, however, +which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)} +with any integrand @samp{f(t)}. Define a @kbd{z s} command and +@code{Si} function that implement this. You will need to edit the +default argument list a bit. As a test, @samp{Si(1)} should return +0.946083. (Hint: @code{ninteg} will run a lot faster if you reduce +the precision to, say, six digits beforehand.) +@xref{Programming Answer 1, 1}. (@bullet{}) + +The simplest way to do real ``programming'' of Emacs is to define a +@dfn{keyboard macro}. A keyboard macro is simply a sequence of +keystrokes which Emacs has stored away and can play back on demand. +For example, if you find yourself typing @kbd{H a S x @key{RET}} often, +you may wish to program a keyboard macro to type this for you. + +@group +@smallexample +1: y = sqrt(x) 1: x = y^2 + . . + + ' y=sqrt(x) RET C-x ( H a S x RET C-x ) + +1: y = cos(x) 1: x = s1 arccos(y) + 2 pi n1 + . . + + ' y=cos(x) RET X +@end smallexample +@end group + +@noindent +When you type @kbd{C-x (}, Emacs begins recording. But it is also +still ready to execute your keystrokes, so you're really ``training'' +Emacs by walking it through the procedure once. When you type +@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to +re-execute the same keystrokes. + +You can give a name to your macro by typing @kbd{Z K}. + +@group +@smallexample +1: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y)) + . . + + Z K x RET ' y=x^4 RET z x +@end smallexample +@end group + +@noindent +Notice that we use shift-@kbd{Z} to define the command, and lower-case +@kbd{z} to call it up. + +Keyboard macros can call other macros. + +@group +@smallexample +1: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y + . . . . + + ' abs(x) RET C-x ( ' y RET a = z x C-x ) ' 2/x RET X +@end smallexample +@end group + +(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate +the item in level 3 of the stack, without disturbing the rest of +the stack. @xref{Programming Answer 2, 2}. (@bullet{}) + +(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute +the following functions: + +@enumerate +@item +Compute @c{$\displaystyle{\sin x \over x}$} +@cite{sin(x) / x}, where @cite{x} is the number on the +top of the stack. + +@item +Compute the base-@cite{b} logarithm, just like the @kbd{B} key except +the arguments are taken in the opposite order. + +@item +Produce a vector of integers from 1 to the integer on the top of +the stack. +@end enumerate +@noindent +@xref{Programming Answer 3, 3}. (@bullet{}) + +(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute +the average (mean) value of a list of numbers. +@xref{Programming Answer 4, 4}. (@bullet{}) + +In many programs, some of the steps must execute several times. +Calc has @dfn{looping} commands that allow this. Loops are useful +inside keyboard macros, but actually work at any time. + +@group +@smallexample +1: x^6 2: x^6 1: 360 x^2 + . 1: 4 . + . + + ' x^6 RET 4 Z < a d x RET Z > +@end smallexample +@end group + +@noindent +Here we have computed the fourth derivative of @cite{x^6} by +enclosing a derivative command in a ``repeat loop'' structure. +This structure pops a repeat count from the stack, then +executes the body of the loop that many times. + +If you make a mistake while entering the body of the loop, +type @w{@kbd{Z C-g}} to cancel the loop command. + +@cindex Fibonacci numbers +Here's another example: + +@group +@smallexample +3: 1 2: 10946 +2: 1 1: 17711 +1: 20 . + . + +1 RET RET 20 Z < TAB C-j + Z > +@end smallexample +@end group + +@noindent +The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci +numbers, respectively. (To see what's going on, try a few repetitions +of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD} +key if you have one, makes a copy of the number in level 2.) + +@cindex Golden ratio +@cindex Phi, golden ratio +A fascinating property of the Fibonacci numbers is that the @cite{n}th +Fibonacci number can be found directly by computing @c{$\phi^n / \sqrt{5}$} +@cite{phi^n / sqrt(5)} +and then rounding to the nearest integer, where @c{$\phi$ (``phi'')} +@cite{phi}, the +``golden ratio,'' is @c{$(1 + \sqrt{5}) / 2$} +@cite{(1 + sqrt(5)) / 2}. (For convenience, this constant is available +from the @code{phi} variable, or the @kbd{I H P} command.) + +@group +@smallexample +1: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946 + . . . . + + I H P 21 ^ 5 Q / R +@end smallexample +@end group + +@cindex Continued fractions +(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction} +representation of @c{$\phi$} +@cite{phi} is @c{$1 + 1/(1 + 1/(1 + 1/( \ldots )))$} +@cite{1 + 1/(1 + 1/(1 + 1/( ...@: )))}. +We can compute an approximate value by carrying this however far +and then replacing the innermost @c{$1/( \ldots )$} +@cite{1/( ...@: )} by 1. Approximate +@c{$\phi$} +@cite{phi} using a twenty-term continued fraction. +@xref{Programming Answer 5, 5}. (@bullet{}) + +(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for +Fibonacci numbers can be expressed in terms of matrices. Given a +vector @w{@cite{[a, b]}} determine a matrix which, when multiplied by this +vector, produces the vector @cite{[b, c]}, where @cite{a}, @cite{b} and +@cite{c} are three successive Fibonacci numbers. Now write a program +that, given an integer @cite{n}, computes the @cite{n}th Fibonacci number +using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{}) + +@cindex Harmonic numbers +A more sophisticated kind of loop is the @dfn{for} loop. Suppose +we wish to compute the 20th ``harmonic'' number, which is equal to +the sum of the reciprocals of the integers from 1 to 20. + +@group +@smallexample +3: 0 1: 3.597739 +2: 1 . +1: 20 + . + +0 RET 1 RET 20 Z ( & + 1 Z ) +@end smallexample +@end group + +@noindent +The ``for'' loop pops two numbers, the lower and upper limits, then +repeats the body of the loop as an internal counter increases from +the lower limit to the upper one. Just before executing the loop +body, it pushes the current loop counter. When the loop body +finishes, it pops the ``step,'' i.e., the amount by which to +increment the loop counter. As you can see, our loop always +uses a step of one. + +This harmonic number function uses the stack to hold the running +total as well as for the various loop housekeeping functions. If +you find this disorienting, you can sum in a variable instead: + +@group +@smallexample +1: 0 2: 1 . 1: 3.597739 + . 1: 20 . + . + + 0 t 7 1 RET 20 Z ( & s + 7 1 Z ) r 7 +@end smallexample +@end group + +@noindent +The @kbd{s +} command adds the top-of-stack into the value in a +variable (and removes that value from the stack). + +It's worth noting that many jobs that call for a ``for'' loop can +also be done more easily by Calc's high-level operations. Two +other ways to compute harmonic numbers are to use vector mapping +and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}), +or to use the summation command @kbd{a +}. Both of these are +probably easier than using loops. However, there are some +situations where loops really are the way to go: + +(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first +harmonic number which is greater than 4.0. +@xref{Programming Answer 7, 7}. (@bullet{}) + +Of course, if we're going to be using variables in our programs, +we have to worry about the programs clobbering values that the +caller was keeping in those same variables. This is easy to +fix, though: + +@group +@smallexample + . 1: 0.6667 1: 0.6667 3: 0.6667 + . . 2: 3.597739 + 1: 0.6667 + . + + Z ` p 4 RET 2 RET 3 / s 7 s s a RET Z ' r 7 s r a RET +@end smallexample +@end group + +@noindent +When we type @kbd{Z `} (that's a back-quote character), Calc saves +its mode settings and the contents of the ten ``quick variables'' +for later reference. When we type @kbd{Z '} (that's an apostrophe +now), Calc restores those saved values. Thus the @kbd{p 4} and +@kbd{s 7} commands have no effect outside this sequence. Wrapping +this around the body of a keyboard macro ensures that it doesn't +interfere with what the user of the macro was doing. Notice that +the contents of the stack, and the values of named variables, +survive past the @kbd{Z '} command. + +@cindex Bernoulli numbers, approximate +The @dfn{Bernoulli numbers} are a sequence with the interesting +property that all of the odd Bernoulli numbers are zero, and the +even ones, while difficult to compute, can be roughly approximated +by the formula @c{$\displaystyle{2 n! \over (2 \pi)^n}$} +@cite{2 n!@: / (2 pi)^n}. Let's write a keyboard +macro to compute (approximate) Bernoulli numbers. (Calc has a +command, @kbd{k b}, to compute exact Bernoulli numbers, but +this command is very slow for large @cite{n} since the higher +Bernoulli numbers are very large fractions.) + +@group +@smallexample +1: 10 1: 0.0756823 + . . + + 10 C-x ( RET 2 % Z [ DEL 0 Z : ' 2 $! / (2 pi)^$ RET = Z ] C-x ) +@end smallexample +@end group + +@noindent +You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and +@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if'' +command. For the purposes of @w{@kbd{Z [}}, the condition is ``true'' +if the value it pops from the stack is a nonzero number, or ``false'' +if it pops zero or something that is not a number (like a formula). +Here we take our integer argument modulo 2; this will be nonzero +if we're asking for an odd Bernoulli number. + +The actual tenth Bernoulli number is @cite{5/66}. + +@group +@smallexample +3: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659 +2: 5:66 . . . . +1: 0.0757575 + . + +10 k b RET c f M-0 DEL 11 X DEL 12 X DEL 13 X DEL 14 X +@end smallexample +@end group + +Just to exercise loops a bit more, let's compute a table of even +Bernoulli numbers. + +@group +@smallexample +3: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...] +2: 2 . +1: 30 + . + + [ ] 2 RET 30 Z ( X | 2 Z ) +@end smallexample +@end group + +@noindent +The vertical-bar @kbd{|} is the vector-concatenation command. When +we execute it, the list we are building will be in stack level 2 +(initially this is an empty list), and the next Bernoulli number +will be in level 1. The effect is to append the Bernoulli number +onto the end of the list. (To create a table of exact fractional +Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above +sequence of keystrokes.) + +With loops and conditionals, you can program essentially anything +in Calc. One other command that makes looping easier is @kbd{Z /}, +which takes a condition from the stack and breaks out of the enclosing +loop if the condition is true (non-zero). You can use this to make +``while'' and ``until'' style loops. + +If you make a mistake when entering a keyboard macro, you can edit +it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}. +One technique is to enter a throwaway dummy definition for the macro, +then enter the real one in the edit command. + +@group +@smallexample +1: 3 1: 3 Keyboard Macro Editor. + . . Original keys: 1 RET 2 + + + type "1\r" + type "2" + calc-plus + +C-x ( 1 RET 2 + C-x ) Z K h RET Z E h +@end smallexample +@end group + +@noindent +This shows the screen display assuming you have the @file{macedit} +keyboard macro editing package installed, which is usually the case +since a copy of @file{macedit} comes bundled with Calc. + +A keyboard macro is stored as a pure keystroke sequence. The +@file{macedit} package (invoked by @kbd{Z E}) scans along the +macro and tries to decode it back into human-readable steps. +If a key or keys are simply shorthand for some command with a +@kbd{M-x} name, that name is shown. Anything that doesn't correspond +to a @kbd{M-x} command is written as a @samp{type} command. + +Let's edit in a new definition, for computing harmonic numbers. +First, erase the three lines of the old definition. Then, type +in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands +to copy it from this page of the Info file; you can skip typing +the comments that begin with @samp{#}). + +@smallexample +calc-kbd-push # Save local values (Z `) +type "0" # Push a zero +calc-store-into # Store it in variable 1 +type "1" +type "1" # Initial value for loop +calc-roll-down # This is the TAB key; swap initial & final +calc-kbd-for # Begin "for" loop... +calc-inv # Take reciprocal +calc-store-plus # Add to accumulator +type "1" +type "1" # Loop step is 1 +calc-kbd-end-for # End "for" loop +calc-recall # Now recall final accumulated value +type "1" +calc-kbd-pop # Restore values (Z ') +@end smallexample + +@noindent +Press @kbd{M-# M-#} to finish editing and return to the Calculator. + +@group +@smallexample +1: 20 1: 3.597739 + . . + + 20 z h +@end smallexample +@end group + +If you don't know how to write a particular command in @file{macedit} +format, you can always write it as keystrokes in a @code{type} command. +There is also a @code{keys} command which interprets the rest of the +line as standard Emacs keystroke names. In fact, @file{macedit} defines +a handy @code{read-kbd-macro} command which reads the current region +of the current buffer as a sequence of keystroke names, and defines that +sequence on the @kbd{X} (and @kbd{C-x e}) key. Because this is so +useful, Calc puts this command on the @kbd{M-# m} key. Try reading in +this macro in the following form: Press @kbd{C-@@} (or @kbd{C-SPC}) at +one end of the text below, then type @kbd{M-# m} at the other. + +@group +@example +Z ` 0 t 1 + 1 TAB + Z ( & s + 1 1 Z ) + r 1 +Z ' +@end example +@end group + +(@bullet{}) @strong{Exercise 8.} A general algorithm for solving +equations numerically is @dfn{Newton's Method}. Given the equation +@cite{f(x) = 0} for any function @cite{f}, and an initial guess +@cite{x_0} which is reasonably close to the desired solution, apply +this formula over and over: + +@ifinfo +@example +new_x = x - f(x)/f'(x) +@end example +@end ifinfo +@tex +\beforedisplay +$$ x_{\goodrm new} = x - {f(x) \over f'(x)} $$ +\afterdisplay +@end tex + +@noindent +where @cite{f'(x)} is the derivative of @cite{f}. The @cite{x} +values will quickly converge to a solution, i.e., eventually +@c{$x_{\rm new}$} +@cite{new_x} and @cite{x} will be equal to within the limits +of the current precision. Write a program which takes a formula +involving the variable @cite{x}, and an initial guess @cite{x_0}, +on the stack, and produces a value of @cite{x} for which the formula +is zero. Use it to find a solution of @c{$\sin(\cos x) = 0.5$} +@cite{sin(cos(x)) = 0.5} +near @cite{x = 4.5}. (Use angles measured in radians.) Note that +the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's +method when it is able. @xref{Programming Answer 8, 8}. (@bullet{}) + +@cindex Digamma function +@cindex Gamma constant, Euler's +@cindex Euler's gamma constant +(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function @c{$\psi(z)$ (``psi'')} +@cite{psi(z)} +is defined as the derivative of @c{$\ln \Gamma(z)$} +@cite{ln(gamma(z))}. For large +values of @cite{z}, it can be approximated by the infinite sum + +@ifinfo +@example +psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf) +@end example +@end ifinfo +@tex +\let\rm\goodrm +\beforedisplay +$$ \psi(z) \approx \ln z - {1\over2z} - + \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}} +$$ +\afterdisplay +@end tex + +@noindent +where @c{$\sum$} +@cite{sum} represents the sum over @cite{n} from 1 to infinity +(or to some limit high enough to give the desired accuracy), and +the @code{bern} function produces (exact) Bernoulli numbers. +While this sum is not guaranteed to converge, in practice it is safe. +An interesting mathematical constant is Euler's gamma, which is equal +to about 0.5772. One way to compute it is by the formula, +@c{$\gamma = -\psi(1)$} +@cite{gamma = -psi(1)}. Unfortunately, 1 isn't a large enough argument +for the above formula to work (5 is a much safer value for @cite{z}). +Fortunately, we can compute @c{$\psi(1)$} +@cite{psi(1)} from @c{$\psi(5)$} +@cite{psi(5)} using +the recurrence @c{$\psi(z+1) = \psi(z) + {1 \over z}$} +@cite{psi(z+1) = psi(z) + 1/z}. Your task: Develop +a program to compute @c{$\psi(z)$} +@cite{psi(z)}; it should ``pump up'' @cite{z} +if necessary to be greater than 5, then use the above summation +formula. Use looping commands to compute the sum. Use your function +to compute @c{$\gamma$} +@cite{gamma} to twelve decimal places. (Calc has a built-in command +for Euler's constant, @kbd{I P}, which you can use to check your answer.) +@xref{Programming Answer 9, 9}. (@bullet{}) + +@cindex Polynomial, list of coefficients +(@bullet{}) @strong{Exercise 10.} Given a polynomial in @cite{x} and +a number @cite{m} on the stack, where the polynomial is of degree +@cite{m} or less (i.e., does not have any terms higher than @cite{x^m}), +write a program to convert the polynomial into a list-of-coefficients +notation. For example, @cite{5 x^4 + (x + 1)^2} with @cite{m = 6} +should produce the list @cite{[1, 2, 1, 0, 5, 0, 0]}. Also develop +a way to convert from this form back to the standard algebraic form. +@xref{Programming Answer 10, 10}. (@bullet{}) + +@cindex Recursion +(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the +first kind} are defined by the recurrences, + +@ifinfo +@example +s(n,n) = 1 for n >= 0, +s(n,0) = 0 for n > 0, +s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1. +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr + s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr + s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad + \hbox{for } n \ge m \ge 1.} +$$ +\afterdisplay +\vskip5pt +(These numbers are also sometimes written $\displaystyle{n \brack m}$.) +@end tex + +This can be implemented using a @dfn{recursive} program in Calc; the +program must invoke itself in order to calculate the two righthand +terms in the general formula. Since it always invokes itself with +``simpler'' arguments, it's easy to see that it must eventually finish +the computation. Recursion is a little difficult with Emacs keyboard +macros since the macro is executed before its definition is complete. +So here's the recommended strategy: Create a ``dummy macro'' and assign +it to a key with, e.g., @kbd{Z K s}. Now enter the true definition, +using the @kbd{z s} command to call itself recursively, then assign it +to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run +the complete recursive program. (Another way is to use @w{@kbd{Z E}} +or @kbd{M-# m} (@code{read-kbd-macro}) to read the whole macro at once, +thus avoiding the ``training'' phase.) The task: Write a program +that computes Stirling numbers of the first kind, given @cite{n} and +@cite{m} on the stack. Test it with @emph{small} inputs like +@cite{s(4,2)}. (There is a built-in command for Stirling numbers, +@kbd{k s}, which you can use to check your answers.) +@xref{Programming Answer 11, 11}. (@bullet{}) + +The programming commands we've seen in this part of the tutorial +are low-level, general-purpose operations. Often you will find +that a higher-level function, such as vector mapping or rewrite +rules, will do the job much more easily than a detailed, step-by-step +program can: + +(@bullet{}) @strong{Exercise 12.} Write another program for +computing Stirling numbers of the first kind, this time using +rewrite rules. Once again, @cite{n} and @cite{m} should be taken +from the stack. @xref{Programming Answer 12, 12}. (@bullet{}) + +@example + +@end example +This ends the tutorial section of the Calc manual. Now you know enough +about Calc to use it effectively for many kinds of calculations. But +Calc has many features that were not even touched upon in this tutorial. +@c [not-split] +The rest of this manual tells the whole story. +@c [when-split] +@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story. + +@page +@node Answers to Exercises, , Programming Tutorial, Tutorial +@section Answers to Exercises + +@noindent +This section includes answers to all the exercises in the Calc tutorial. + +@menu +* RPN Answer 1:: 1 RET 2 RET 3 RET 4 + * - +* RPN Answer 2:: 2*4 + 7*9.5 + 5/4 +* RPN Answer 3:: Operating on levels 2 and 3 +* RPN Answer 4:: Joe's complex problems +* Algebraic Answer 1:: Simulating Q command +* Algebraic Answer 2:: Joe's algebraic woes +* Algebraic Answer 3:: 1 / 0 +* Modes Answer 1:: 3#0.1 = 3#0.0222222? +* Modes Answer 2:: 16#f.e8fe15 +* Modes Answer 3:: Joe's rounding bug +* Modes Answer 4:: Why floating point? +* Arithmetic Answer 1:: Why the \ command? +* Arithmetic Answer 2:: Tripping up the B command +* Vector Answer 1:: Normalizing a vector +* Vector Answer 2:: Average position +* Matrix Answer 1:: Row and column sums +* Matrix Answer 2:: Symbolic system of equations +* Matrix Answer 3:: Over-determined system +* List Answer 1:: Powers of two +* List Answer 2:: Least-squares fit with matrices +* List Answer 3:: Geometric mean +* List Answer 4:: Divisor function +* List Answer 5:: Duplicate factors +* List Answer 6:: Triangular list +* List Answer 7:: Another triangular list +* List Answer 8:: Maximum of Bessel function +* List Answer 9:: Integers the hard way +* List Answer 10:: All elements equal +* List Answer 11:: Estimating pi with darts +* List Answer 12:: Estimating pi with matchsticks +* List Answer 13:: Hash codes +* List Answer 14:: Random walk +* Types Answer 1:: Square root of pi times rational +* Types Answer 2:: Infinities +* Types Answer 3:: What can "nan" be? +* Types Answer 4:: Abbey Road +* Types Answer 5:: Friday the 13th +* Types Answer 6:: Leap years +* Types Answer 7:: Erroneous donut +* Types Answer 8:: Dividing intervals +* Types Answer 9:: Squaring intervals +* Types Answer 10:: Fermat's primality test +* Types Answer 11:: pi * 10^7 seconds +* Types Answer 12:: Abbey Road on CD +* Types Answer 13:: Not quite pi * 10^7 seconds +* Types Answer 14:: Supercomputers and c +* Types Answer 15:: Sam the Slug +* Algebra Answer 1:: Squares and square roots +* Algebra Answer 2:: Building polynomial from roots +* Algebra Answer 3:: Integral of x sin(pi x) +* Algebra Answer 4:: Simpson's rule +* Rewrites Answer 1:: Multiplying by conjugate +* Rewrites Answer 2:: Alternative fib rule +* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x +* Rewrites Answer 4:: Sequence of integers +* Rewrites Answer 5:: Number of terms in sum +* Rewrites Answer 6:: Defining 0^0 = 1 +* Rewrites Answer 7:: Truncated Taylor series +* Programming Answer 1:: Fresnel's C(x) +* Programming Answer 2:: Negate third stack element +* Programming Answer 3:: Compute sin(x) / x, etc. +* Programming Answer 4:: Average value of a list +* Programming Answer 5:: Continued fraction phi +* Programming Answer 6:: Matrix Fibonacci numbers +* Programming Answer 7:: Harmonic number greater than 4 +* Programming Answer 8:: Newton's method +* Programming Answer 9:: Digamma function +* Programming Answer 10:: Unpacking a polynomial +* Programming Answer 11:: Recursive Stirling numbers +* Programming Answer 12:: Stirling numbers with rewrites +@end menu + +@c The following kludgery prevents the individual answers from +@c being entered on the table of contents. +@tex +\global\let\oldwrite=\write +\gdef\skipwrite#1#2{\let\write=\oldwrite} +\global\let\oldchapternofonts=\chapternofonts +\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts} +@end tex + +@node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises +@subsection RPN Tutorial Exercise 1 + +@noindent +@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -} + +The result is @c{$1 - (2 \times (3 + 4)) = -13$} +@cite{1 - (2 * (3 + 4)) = -13}. + +@node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises +@subsection RPN Tutorial Exercise 2 + +@noindent +@c{$2\times4 + 7\times9.5 + {5\over4} = 75.75$} +@cite{2*4 + 7*9.5 + 5/4 = 75.75} + +After computing the intermediate term @c{$2\times4 = 8$} +@cite{2*4 = 8}, you can leave +that result on the stack while you compute the second term. With +both of these results waiting on the stack you can then compute the +final term, then press @kbd{+ +} to add everything up. + +@group +@smallexample +2: 2 1: 8 3: 8 2: 8 +1: 4 . 2: 7 1: 66.5 + . 1: 9.5 . + . + + 2 RET 4 * 7 RET 9.5 * + +@end smallexample +@end group +@noindent +@group +@smallexample +4: 8 3: 8 2: 8 1: 75.75 +3: 66.5 2: 66.5 1: 67.75 . +2: 5 1: 1.25 . +1: 4 . + . + + 5 RET 4 / + + +@end smallexample +@end group + +Alternatively, you could add the first two terms before going on +with the third term. + +@group +@smallexample +2: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75 +1: 66.5 . 2: 5 1: 1.25 . + . 1: 4 . + . + + ... + 5 RET 4 / + +@end smallexample +@end group + +On an old-style RPN calculator this second method would have the +advantage of using only three stack levels. But since Calc's stack +can grow arbitrarily large this isn't really an issue. Which method +you choose is purely a matter of taste. + +@node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises +@subsection RPN Tutorial Exercise 3 + +@noindent +The @key{TAB} key provides a way to operate on the number in level 2. + +@group +@smallexample +3: 10 3: 10 4: 10 3: 10 3: 10 +2: 20 2: 30 3: 30 2: 30 2: 21 +1: 30 1: 20 2: 20 1: 21 1: 30 + . . 1: 1 . . + . + + TAB 1 + TAB +@end smallexample +@end group + +Similarly, @key{M-TAB} gives you access to the number in level 3. + +@group +@smallexample +3: 10 3: 21 3: 21 3: 30 3: 11 +2: 21 2: 30 2: 30 2: 11 2: 21 +1: 30 1: 10 1: 11 1: 21 1: 30 + . . . . . + + M-TAB 1 + M-TAB M-TAB +@end smallexample +@end group + +@node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises +@subsection RPN Tutorial Exercise 4 + +@noindent +Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked, +but using both the comma and the space at once yields: + +@group +@smallexample +1: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ... + . 1: 2 . 1: (2, ... 1: (2, 3) + . . . + + ( 2 , SPC 3 ) +@end smallexample +@end group + +Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the +extra incomplete object to the top of the stack and delete it. +But a feature of Calc is that @key{DEL} on an incomplete object +deletes just one component out of that object, so he had to press +@key{DEL} twice to finish the job. + +@group +@smallexample +2: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3) +1: (2, 3) 1: (2, ... 1: ( ... . + . . . + + TAB DEL DEL +@end smallexample +@end group + +(As it turns out, deleting the second-to-top stack entry happens often +enough that Calc provides a special key, @kbd{M-DEL}, to do just that. +@kbd{M-DEL} is just like @kbd{TAB DEL}, except that it doesn't exhibit +the ``feature'' that tripped poor Joe.) + +@node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises +@subsection Algebraic Entry Tutorial Exercise 1 + +@noindent +Type @kbd{' sqrt($) @key{RET}}. + +If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}. +Or, RPN style, @kbd{0.5 ^}. + +(Actually, @samp{$^1:2}, using the fraction one-half as the power, is +a closer equivalent, since @samp{9^0.5} yields @cite{3.0} whereas +@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @cite{3}.) + +@node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises +@subsection Algebraic Entry Tutorial Exercise 2 + +@noindent +In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function +name with @samp{1+y} as its argument. Assigning a value to a variable +has no relation to a function by the same name. Joe needed to use an +explicit @samp{*} symbol here: @samp{2 x*(1+y)}. + +@node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises +@subsection Algebraic Entry Tutorial Exercise 3 + +@noindent +The result from @kbd{1 @key{RET} 0 /} will be the formula @cite{1 / 0}. +The ``function'' @samp{/} cannot be evaluated when its second argument +is zero, so it is left in symbolic form. When you now type @kbd{0 *}, +the result will be zero because Calc uses the general rule that ``zero +times anything is zero.'' + +@c [fix-ref Infinities] +The @kbd{m i} command enables an @dfn{infinite mode} in which @cite{1 / 0} +results in a special symbol that represents ``infinity.'' If you +multiply infinity by zero, Calc uses another special new symbol to +show that the answer is ``indeterminate.'' @xref{Infinities}, for +further discussion of infinite and indeterminate values. + +@node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises +@subsection Modes Tutorial Exercise 1 + +@noindent +Calc always stores its numbers in decimal, so even though one-third has +an exact base-3 representation (@samp{3#0.1}), it is still stored as +0.3333333 (chopped off after 12 or however many decimal digits) inside +the calculator's memory. When this inexact number is converted back +to base 3 for display, it may still be slightly inexact. When we +multiply this number by 3, we get 0.999999, also an inexact value. + +When Calc displays a number in base 3, it has to decide how many digits +to show. If the current precision is 12 (decimal) digits, that corresponds +to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an +exact integer, Calc shows only 25 digits, with the result that stored +numbers carry a little bit of extra information that may not show up on +the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666 +happened to round to a pleasing value when it lost that last 0.15 of a +digit, but it was still inexact in Calc's memory. When he divided by 2, +he still got the dreaded inexact value 0.333333. (Actually, he divided +0.666667 by 2 to get 0.333334, which is why he got something a little +higher than @code{3#0.1} instead of a little lower.) + +If Joe didn't want to be bothered with all this, he could have typed +@kbd{M-24 d n} to display with one less digit than the default. (If +you give @kbd{d n} a negative argument, it uses default-minus-that, +so @kbd{M-- d n} would be an easier way to get the same effect.) Those +inexact results would still be lurking there, but they would now be +rounded to nice, natural-looking values for display purposes. (Remember, +@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding +off one digit will round the number up to @samp{0.1}.) Depending on the +nature of your work, this hiding of the inexactness may be a benefit or +a danger. With the @kbd{d n} command, Calc gives you the choice. + +Incidentally, another consequence of all this is that if you type +@kbd{M-30 d n} to display more digits than are ``really there,'' +you'll see garbage digits at the end of the number. (In decimal +display mode, with decimally-stored numbers, these garbage digits are +always zero so they vanish and you don't notice them.) Because Calc +rounds off that 0.15 digit, there is the danger that two numbers could +be slightly different internally but still look the same. If you feel +uneasy about this, set the @kbd{d n} precision to be a little higher +than normal; you'll get ugly garbage digits, but you'll always be able +to tell two distinct numbers apart. + +An interesting side note is that most computers store their +floating-point numbers in binary, and convert to decimal for display. +Thus everyday programs have the same problem: Decimal 0.1 cannot be +represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10} +comes out as an inexact approximation to 1 on some machines (though +they generally arrange to hide it from you by rounding off one digit as +we did above). Because Calc works in decimal instead of binary, you can +be sure that numbers that look exact @emph{are} exact as long as you stay +in decimal display mode. + +It's not hard to show that any number that can be represented exactly +in binary, octal, or hexadecimal is also exact in decimal, so the kinds +of problems we saw in this exercise are likely to be severe only when +you use a relatively unusual radix like 3. + +@node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises +@subsection Modes Tutorial Exercise 2 + +If the radix is 15 or higher, we can't use the letter @samp{e} to mark +the exponent because @samp{e} is interpreted as a digit. When Calc +needs to display scientific notation in a high radix, it writes +@samp{16#F.E8F*16.^15}. You can enter a number like this as an +algebraic entry. Also, pressing @kbd{e} without any digits before it +normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and +puts you in algebraic entry: @kbd{16#f.e8f RET e 15 RET *} is another +way to enter this number. + +The reason Calc puts a decimal point in the @samp{16.^} is to prevent +huge integers from being generated if the exponent is large (consider +@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant +exact integer and then throw away most of the digits when we multiply +it by the floating-point @samp{16#1.23}). While this wouldn't normally +matter for display purposes, it could give you a nasty surprise if you +copied that number into a file and later moved it back into Calc. + +@node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises +@subsection Modes Tutorial Exercise 3 + +@noindent +The answer he got was @cite{0.5000000000006399}. + +The problem is not that the square operation is inexact, but that the +sine of 45 that was already on the stack was accurate to only 12 places. +Arbitrary-precision calculations still only give answers as good as +their inputs. + +The real problem is that there is no 12-digit number which, when +squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]} +commands decrease or increase a number by one unit in the last +place (according to the current precision). They are useful for +determining facts like this. + +@group +@smallexample +1: 0.707106781187 1: 0.500000000001 + . . + + 45 S 2 ^ + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 0.707106781187 1: 0.707106781186 1: 0.499999999999 + . . . + + U DEL f [ 2 ^ +@end smallexample +@end group + +A high-precision calculation must be carried out in high precision +all the way. The only number in the original problem which was known +exactly was the quantity 45 degrees, so the precision must be raised +before anything is done after the number 45 has been entered in order +for the higher precision to be meaningful. + +@node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises +@subsection Modes Tutorial Exercise 4 + +@noindent +Many calculations involve real-world quantities, like the width and +height of a piece of wood or the volume of a jar. Such quantities +can't be measured exactly anyway, and if the data that is input to +a calculation is inexact, doing exact arithmetic on it is a waste +of time. + +Fractions become unwieldy after too many calculations have been +done with them. For example, the sum of the reciprocals of the +integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is +9304682830147:2329089562800. After a point it will take a long +time to add even one more term to this sum, but a floating-point +calculation of the sum will not have this problem. + +Also, rational numbers cannot express the results of all calculations. +There is no fractional form for the square root of two, so if you type +@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer. + +@node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises +@subsection Arithmetic Tutorial Exercise 1 + +@noindent +Dividing two integers that are larger than the current precision may +give a floating-point result that is inaccurate even when rounded +down to an integer. Consider @cite{123456789 / 2} when the current +precision is 6 digits. The true answer is @cite{61728394.5}, but +with a precision of 6 this will be rounded to @c{$12345700.0/2.0 = 61728500.0$} +@cite{12345700.@: / 2.@: = 61728500.}. +The result, when converted to an integer, will be off by 106. + +Here are two solutions: Raise the precision enough that the +floating-point round-off error is strictly to the right of the +decimal point. Or, convert to fraction mode so that @cite{123456789 / 2} +produces the exact fraction @cite{123456789:2}, which can be rounded +down by the @kbd{F} command without ever switching to floating-point +format. + +@node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises +@subsection Arithmetic Tutorial Exercise 2 + +@noindent +@kbd{27 @key{RET} 9 B} could give the exact result @cite{3:2}, but it +does a floating-point calculation instead and produces @cite{1.5}. + +Calc will find an exact result for a logarithm if the result is an integer +or the reciprocal of an integer. But there is no efficient way to search +the space of all possible rational numbers for an exact answer, so Calc +doesn't try. + +@node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises +@subsection Vector Tutorial Exercise 1 + +@noindent +Duplicate the vector, compute its length, then divide the vector +by its length: @kbd{@key{RET} A /}. + +@group +@smallexample +1: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1. + . 1: 3.74165738677 . . + . + + r 1 RET A / A +@end smallexample +@end group + +The final @kbd{A} command shows that the normalized vector does +indeed have unit length. + +@node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises +@subsection Vector Tutorial Exercise 2 + +@noindent +The average position is equal to the sum of the products of the +positions times their corresponding probabilities. This is the +definition of the dot product operation. So all you need to do +is to put the two vectors on the stack and press @kbd{*}. + +@node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises +@subsection Matrix Tutorial Exercise 1 + +@noindent +The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to +get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum. + +@node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises +@subsection Matrix Tutorial Exercise 2 + +@ifinfo +@group +@example + x + a y = 6 + x + b y = 10 +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ \eqalign{ x &+ a y = 6 \cr + x &+ b y = 10} +$$ +\afterdisplay +@end tex + +Just enter the righthand side vector, then divide by the lefthand side +matrix as usual. + +@group +@smallexample +1: [6, 10] 2: [6, 10] 1: [6 - 4 a / (b - a), 4 / (b - a) ] + . 1: [ [ 1, a ] . + [ 1, b ] ] + . + +' [6 10] RET ' [1 a; 1 b] RET / +@end smallexample +@end group + +This can be made more readable using @kbd{d B} to enable ``big'' display +mode: + +@group +@smallexample + 4 a 4 +1: [6 - -----, -----] + b - a b - a +@end smallexample +@end group + +Type @kbd{d N} to return to ``normal'' display mode afterwards. + +@node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises +@subsection Matrix Tutorial Exercise 3 + +@noindent +To solve @c{$A^T A \, X = A^T B$} +@cite{trn(A) * A * X = trn(A) * B}, first we compute +@c{$A' = A^T A$} +@cite{A2 = trn(A) * A} and @c{$B' = A^T B$} +@cite{B2 = trn(A) * B}; now, we have a +system @c{$A' X = B'$} +@cite{A2 * X = B2} which we can solve using Calc's @samp{/} +command. + +@ifinfo +@group +@example + a + 2b + 3c = 6 + 4a + 5b + 6c = 2 + 7a + 6b = 3 + 2a + 4b + 6c = 11 +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\beforedisplayh +$$ \openup1\jot \tabskip=0pt plus1fil +\halign to\displaywidth{\tabskip=0pt + $\hfil#$&$\hfil{}#{}$& + $\hfil#$&$\hfil{}#{}$& + $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr + a&+&2b&+&3c&=6 \cr + 4a&+&5b&+&6c&=2 \cr + 7a&+&6b& & &=3 \cr + 2a&+&4b&+&6c&=11 \cr} +$$ +\afterdisplayh +@end tex + +The first step is to enter the coefficient matrix. We'll store it in +quick variable number 7 for later reference. Next, we compute the +@c{$B'$} +@cite{B2} vector. + +@group +@smallexample +1: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96] + [ 4, 5, 6 ] [ 2, 5, 6, 4 ] . + [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ] + [ 2, 4, 6 ] ] 1: [6, 2, 3, 11] + . . + +' [1 2 3; 4 5 6; 7 6 0; 2 4 6] RET s 7 v t [6 2 3 11] * +@end smallexample +@end group + +@noindent +Now we compute the matrix @c{$A'$} +@cite{A2} and divide. + +@group +@smallexample +2: [57, 84, 96] 1: [-11.64, 14.08, -3.64] +1: [ [ 70, 72, 39 ] . + [ 72, 81, 60 ] + [ 39, 60, 81 ] ] + . + + r 7 v t r 7 * / +@end smallexample +@end group + +@noindent +(The actual computed answer will be slightly inexact due to +round-off error.) + +Notice that the answers are similar to those for the @c{$3\times3$} +@asis{3x3} system +solved in the text. That's because the fourth equation that was +added to the system is almost identical to the first one multiplied +by two. (If it were identical, we would have gotten the exact same +answer since the @c{$4\times3$} +@asis{4x3} system would be equivalent to the original @c{$3\times3$} +@asis{3x3} +system.) + +Since the first and fourth equations aren't quite equivalent, they +can't both be satisfied at once. Let's plug our answers back into +the original system of equations to see how well they match. + +@group +@smallexample +2: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2] +1: [ [ 1, 2, 3 ] . + [ 4, 5, 6 ] + [ 7, 6, 0 ] + [ 2, 4, 6 ] ] + . + + r 7 TAB * +@end smallexample +@end group + +@noindent +This is reasonably close to our original @cite{B} vector, +@cite{[6, 2, 3, 11]}. + +@node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises +@subsection List Tutorial Exercise 1 + +@noindent +We can use @kbd{v x} to build a vector of integers. This needs to be +adjusted to get the range of integers we desire. Mapping @samp{-} +across the vector will accomplish this, although it turns out the +plain @samp{-} key will work just as well. + +@group +@smallexample +2: 2 2: 2 +1: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4] + . . + + 2 v x 9 RET 5 V M - or 5 - +@end smallexample +@end group + +@noindent +Now we use @kbd{V M ^} to map the exponentiation operator across the +vector. + +@group +@smallexample +1: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16] + . + + V M ^ +@end smallexample +@end group + +@node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises +@subsection List Tutorial Exercise 2 + +@noindent +Given @cite{x} and @cite{y} vectors in quick variables 1 and 2 as before, +the first job is to form the matrix that describes the problem. + +@ifinfo +@example + m*x + b*1 = y +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ m \times x + b \times 1 = y $$ +\afterdisplay +@end tex + +Thus we want a @c{$19\times2$} +@asis{19x2} matrix with our @cite{x} vector as one column and +ones as the other column. So, first we build the column of ones, then +we combine the two columns to form our @cite{A} matrix. + +@group +@smallexample +2: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ] +1: [1, 1, 1, ...] [ 1.41, 1 ] + . [ 1.49, 1 ] + @dots{} + + r 1 1 v b 19 RET M-2 v p v t s 3 +@end smallexample +@end group + +@noindent +Now we compute @c{$A^T y$} +@cite{trn(A) * y} and @c{$A^T A$} +@cite{trn(A) * A} and divide. + +@group +@smallexample +1: [33.36554, 13.613] 2: [33.36554, 13.613] + . 1: [ [ 98.0003, 41.63 ] + [ 41.63, 19 ] ] + . + + v t r 2 * r 3 v t r 3 * +@end smallexample +@end group + +@noindent +(Hey, those numbers look familiar!) + +@group +@smallexample +1: [0.52141679, -0.425978] + . + + / +@end smallexample +@end group + +Since we were solving equations of the form @c{$m \times x + b \times 1 = y$} +@cite{m*x + b*1 = y}, these +numbers should be @cite{m} and @cite{b}, respectively. Sure enough, they +agree exactly with the result computed using @kbd{V M} and @kbd{V R}! + +The moral of this story: @kbd{V M} and @kbd{V R} will probably solve +your problem, but there is often an easier way using the higher-level +arithmetic functions! + +@c [fix-ref Curve Fitting] +In fact, there is a built-in @kbd{a F} command that does least-squares +fits. @xref{Curve Fitting}. + +@node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises +@subsection List Tutorial Exercise 3 + +@noindent +Move to one end of the list and press @kbd{C-@@} (or @kbd{C-SPC} or +whatever) to set the mark, then move to the other end of the list +and type @w{@kbd{M-# g}}. + +@group +@smallexample +1: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5] + . +@end smallexample +@end group + +To make things interesting, let's assume we don't know at a glance +how many numbers are in this list. Then we could type: + +@group +@smallexample +2: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ] +1: [2.3, 6, 22, ... ] 1: 126356422.5 + . . + + RET V R * + +@end smallexample +@end group +@noindent +@group +@smallexample +2: 126356422.5 2: 126356422.5 1: 7.94652913734 +1: [2.3, 6, 22, ... ] 1: 9 . + . . + + TAB v l I ^ +@end smallexample +@end group + +@noindent +(The @kbd{I ^} command computes the @var{n}th root of a number. +You could also type @kbd{& ^} to take the reciprocal of 9 and +then raise the number to that power.) + +@node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises +@subsection List Tutorial Exercise 4 + +@noindent +A number @cite{j} is a divisor of @cite{n} if @c{$n \mathbin{\hbox{\code{\%}}} j = 0$} +@samp{n % j = 0}. The first +step is to get a vector that identifies the divisors. + +@group +@smallexample +2: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...] +1: [1, 2, 3, 4, ...] 1: 0 . + . . + + 30 RET v x 30 RET s 1 V M % 0 V M a = s 2 +@end smallexample +@end group + +@noindent +This vector has 1's marking divisors of 30 and 0's marking non-divisors. + +The zeroth divisor function is just the total number of divisors. +The first divisor function is the sum of the divisors. + +@group +@smallexample +1: 8 3: 8 2: 8 2: 8 + 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72 + 1: [1, 1, 1, 0, ...] . . + . + + V R + r 1 r 2 V M * V R + +@end smallexample +@end group + +@noindent +Once again, the last two steps just compute a dot product for which +a simple @kbd{*} would have worked equally well. + +@node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises +@subsection List Tutorial Exercise 5 + +@noindent +The obvious first step is to obtain the list of factors with @kbd{k f}. +This list will always be in sorted order, so if there are duplicates +they will be right next to each other. A suitable method is to compare +the list with a copy of itself shifted over by one. + +@group +@smallexample +1: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0] + . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19] + . . + + 19551 k f RET 0 | TAB 0 TAB | + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [0, 0, 1, 1, 0, 0] 1: 2 1: 0 + . . . + + V M a = V R + 0 a = +@end smallexample +@end group + +@noindent +Note that we have to arrange for both vectors to have the same length +so that the mapping operation works; no prime factor will ever be +zero, so adding zeros on the left and right is safe. From then on +the job is pretty straightforward. + +Incidentally, Calc provides the @c{\dfn{M\"obius} $\mu$} +@dfn{Moebius mu} function which is +zero if and only if its argument is square-free. It would be a much +more convenient way to do the above test in practice. + +@node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises +@subsection List Tutorial Exercise 6 + +@noindent +First use @kbd{v x 6 RET} to get a list of integers, then @kbd{V M v x} +to get a list of lists of integers! + +@node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises +@subsection List Tutorial Exercise 7 + +@noindent +Here's one solution. First, compute the triangular list from the previous +exercise and type @kbd{1 -} to subtract one from all the elements. + +@group +@smallexample +1: [ [0], + [0, 1], + [0, 1, 2], + @dots{} + + 1 - +@end smallexample +@end group + +The numbers down the lefthand edge of the list we desire are called +the ``triangular numbers'' (now you know why!). The @cite{n}th +triangular number is the sum of the integers from 1 to @cite{n}, and +can be computed directly by the formula @c{$n (n+1) \over 2$} +@cite{n * (n+1) / 2}. + +@group +@smallexample +2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] +1: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15] + . . + + v x 6 RET 1 - V M ' $ ($+1)/2 RET +@end smallexample +@end group + +@noindent +Adding this list to the above list of lists produces the desired +result: + +@group +@smallexample +1: [ [0], + [1, 2], + [3, 4, 5], + [6, 7, 8, 9], + [10, 11, 12, 13, 14], + [15, 16, 17, 18, 19, 20] ] + . + + V M + +@end smallexample +@end group + +If we did not know the formula for triangular numbers, we could have +computed them using a @kbd{V U +} command. We could also have +gotten them the hard way by mapping a reduction across the original +triangular list. + +@group +@smallexample +2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] +1: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15] + . . + + RET V M V R + +@end smallexample +@end group + +@noindent +(This means ``map a @kbd{V R +} command across the vector,'' and +since each element of the main vector is itself a small vector, +@kbd{V R +} computes the sum of its elements.) + +@node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises +@subsection List Tutorial Exercise 8 + +@noindent +The first step is to build a list of values of @cite{x}. + +@group +@smallexample +1: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5] + . . . + + v x 21 RET 1 - 4 / s 1 +@end smallexample +@end group + +Next, we compute the Bessel function values. + +@group +@smallexample +1: [0., 0.124, 0.242, ..., -0.328] + . + + V M ' besJ(1,$) RET +@end smallexample +@end group + +@noindent +(Another way to do this would be @kbd{1 TAB V M f j}.) + +A way to isolate the maximum value is to compute the maximum using +@kbd{V R X}, then compare all the Bessel values with that maximum. + +@group +@smallexample +2: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ] +1: 0.5801562 . 1: 1 + . . + + RET V R X V M a = RET V R + DEL +@end smallexample +@end group + +@noindent +It's a good idea to verify, as in the last step above, that only +one value is equal to the maximum. (After all, a plot of @c{$\sin x$} +@cite{sin(x)} +might have many points all equal to the maximum value, 1.) + +The vector we have now has a single 1 in the position that indicates +the maximum value of @cite{x}. Now it is a simple matter to convert +this back into the corresponding value itself. + +@group +@smallexample +2: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75 +1: [0, 0.25, 0.5, ... ] . . + . + + r 1 V M * V R + +@end smallexample +@end group + +If @kbd{a =} had produced more than one @cite{1} value, this method +would have given the sum of all maximum @cite{x} values; not very +useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector}) +instead. This command deletes all elements of a ``data'' vector that +correspond to zeros in a ``mask'' vector, leaving us with, in this +example, a vector of maximum @cite{x} values. + +The built-in @kbd{a X} command maximizes a function using more +efficient methods. Just for illustration, let's use @kbd{a X} +to maximize @samp{besJ(1,x)} over this same interval. + +@group +@smallexample +2: besJ(1, x) 1: [1.84115, 0.581865] +1: [0 .. 5] . + . + +' besJ(1,x), [0..5] RET a X x RET +@end smallexample +@end group + +@noindent +The output from @kbd{a X} is a vector containing the value of @cite{x} +that maximizes the function, and the function's value at that maximum. +As you can see, our simple search got quite close to the right answer. + +@node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises +@subsection List Tutorial Exercise 9 + +@noindent +Step one is to convert our integer into vector notation. + +@group +@smallexample +1: 25129925999 3: 25129925999 + . 2: 10 + 1: [11, 10, 9, ..., 1, 0] + . + + 25129925999 RET 10 RET 12 RET v x 12 RET - + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 25129925999 1: [0, 2, 25, 251, 2512, ... ] +2: [100000000000, ... ] . + . + + V M ^ s 1 V M \ +@end smallexample +@end group + +@noindent +(Recall, the @kbd{\} command computes an integer quotient.) + +@group +@smallexample +1: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9] + . + + 10 V M % s 2 +@end smallexample +@end group + +Next we must increment this number. This involves adding one to +the last digit, plus handling carries. There is a carry to the +left out of a digit if that digit is a nine and all the digits to +the right of it are nines. + +@group +@smallexample +1: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ] + . . + + 9 V M a = v v + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1] + . . + + V U * v v 1 | +@end smallexample +@end group + +@noindent +Accumulating @kbd{*} across a vector of ones and zeros will preserve +only the initial run of ones. These are the carries into all digits +except the rightmost digit. Concatenating a one on the right takes +care of aligning the carries properly, and also adding one to the +rightmost digit. + +@group +@smallexample +2: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0] +1: [0, 0, 2, 5, ... ] . + . + + 0 r 2 | V M + 10 V M % +@end smallexample +@end group + +@noindent +Here we have concatenated 0 to the @emph{left} of the original number; +this takes care of shifting the carries by one with respect to the +digits that generated them. + +Finally, we must convert this list back into an integer. + +@group +@smallexample +3: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ] +2: 1000000000000 1: [1000000000000, 100000000000, ... ] +1: [100000000000, ... ] . + . + + 10 RET 12 ^ r 1 | + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000 + . . + + V M * V R + +@end smallexample +@end group + +@noindent +Another way to do this final step would be to reduce the formula +@w{@samp{10 $$ + $}} across the vector of digits. + +@group +@smallexample +1: [0, 0, 2, 5, ... ] 1: 25129926000 + . . + + V R ' 10 $$ + $ RET +@end smallexample +@end group + +@node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises +@subsection List Tutorial Exercise 10 + +@noindent +For the list @cite{[a, b, c, d]}, the result is @cite{((a = b) = c) = d}, +which will compare @cite{a} and @cite{b} to produce a 1 or 0, which is +then compared with @cite{c} to produce another 1 or 0, which is then +compared with @cite{d}. This is not at all what Joe wanted. + +Here's a more correct method: + +@group +@smallexample +1: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7] + . 1: 7 + . + + ' [7,7,7,8,7] RET RET v r 1 RET + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [1, 1, 1, 0, 1] 1: 0 + . . + + V M a = V R * +@end smallexample +@end group + +@node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises +@subsection List Tutorial Exercise 11 + +@noindent +The circle of unit radius consists of those points @cite{(x,y)} for which +@cite{x^2 + y^2 < 1}. We start by generating a vector of @cite{x^2} +and a vector of @cite{y^2}. + +We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} +commands. + +@group +@smallexample +2: [2., 2., ..., 2.] 2: [2., 2., ..., 2.] +1: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81] + . . + + v . t . 2. v b 100 RET RET V M k r + +@end smallexample +@end group +@noindent +@group +@smallexample +2: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036] +1: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094] + . . + + 1 - 2 V M ^ TAB V M k r 1 - 2 V M ^ +@end smallexample +@end group + +Now we sum the @cite{x^2} and @cite{y^2} values, compare with 1 to +get a vector of 1/0 truth values, then sum the truth values. + +@group +@smallexample +1: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84 + . . . + + + 1 V M a < V R + +@end smallexample +@end group + +@noindent +The ratio @cite{84/100} should approximate the ratio @c{$\pi/4$} +@cite{pi/4}. + +@group +@smallexample +1: 0.84 1: 3.36 2: 3.36 1: 1.0695 + . . 1: 3.14159 . + + 100 / 4 * P / +@end smallexample +@end group + +@noindent +Our estimate, 3.36, is off by about 7%. We could get a better estimate +by taking more points (say, 1000), but it's clear that this method is +not very efficient! + +(Naturally, since this example uses random numbers your own answer +will be slightly different from the one shown here!) + +If you typed @kbd{v .} and @kbd{t .} before, type them again to +return to full-sized display of vectors. + +@node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises +@subsection List Tutorial Exercise 12 + +@noindent +This problem can be made a lot easier by taking advantage of some +symmetries. First of all, after some thought it's clear that the +@cite{y} axis can be ignored altogether. Just pick a random @cite{x} +component for one end of the match, pick a random direction @c{$\theta$} +@cite{theta}, +and see if @cite{x} and @c{$x + \cos \theta$} +@cite{x + cos(theta)} (which is the @cite{x} +coordinate of the other endpoint) cross a line. The lines are at +integer coordinates, so this happens when the two numbers surround +an integer. + +Since the two endpoints are equivalent, we may as well choose the leftmost +of the two endpoints as @cite{x}. Then @cite{theta} is an angle pointing +to the right, in the range -90 to 90 degrees. (We could use radians, but +it would feel like cheating to refer to @c{$\pi/2$} +@cite{pi/2} radians while trying +to estimate @c{$\pi$} +@cite{pi}!) + +In fact, since the field of lines is infinite we can choose the +coordinates 0 and 1 for the lines on either side of the leftmost +endpoint. The rightmost endpoint will be between 0 and 1 if the +match does not cross a line, or between 1 and 2 if it does. So: +Pick random @cite{x} and @c{$\theta$} +@cite{theta}, compute @c{$x + \cos \theta$} +@cite{x + cos(theta)}, +and count how many of the results are greater than one. Simple! + +We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} +commands. + +@group +@smallexample +1: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72] + . 1: [78.4, 64.5, ..., -42.9] + . + +v . t . 1. v b 100 RET V M k r 180. v b 100 RET V M k r 90 - +@end smallexample +@end group + +@noindent +(The next step may be slow, depending on the speed of your computer.) + +@group +@smallexample +2: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45] +1: [0.20, 0.43, ..., 0.73] . + . + + m d V M C + + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [0, 1, ..., 1] 1: 0.64 1: 3.125 + . . . + + 1 V M a > V R + 100 / 2 TAB / +@end smallexample +@end group + +Let's try the third method, too. We'll use random integers up to +one million. The @kbd{k r} command with an integer argument picks +a random integer. + +@group +@smallexample +2: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975] +1: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450] + . . + + 1000000 v b 100 RET RET V M k r TAB V M k r + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56 + . . . + + V M k g 1 V M a = V R + 100 / + +@end smallexample +@end group +@noindent +@group +@smallexample +1: 10.714 1: 3.273 + . . + + 6 TAB / Q +@end smallexample +@end group + +For a proof of this property of the GCD function, see section 4.5.2, +exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II. + +If you typed @kbd{v .} and @kbd{t .} before, type them again to +return to full-sized display of vectors. + +@node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises +@subsection List Tutorial Exercise 13 + +@noindent +First, we put the string on the stack as a vector of ASCII codes. + +@group +@smallexample +1: [84, 101, 115, ..., 51] + . + + "Testing, 1, 2, 3 RET +@end smallexample +@end group + +@noindent +Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so +there was no need to type an apostrophe. Also, Calc didn't mind that +we omitted the closing @kbd{"}. (The same goes for all closing delimiters +like @kbd{)} and @kbd{]} at the end of a formula. + +We'll show two different approaches here. In the first, we note that +if the input vector is @cite{[a, b, c, d]}, then the hash code is +@cite{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words, +it's a sum of descending powers of three times the ASCII codes. + +@group +@smallexample +2: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51] +1: 16 1: [15, 14, 13, ..., 0] + . . + + RET v l v x 16 RET - + +@end smallexample +@end group +@noindent +@group +@smallexample +2: [84, 101, 115, ..., 51] 1: 1960915098 1: 121 +1: [14348907, ..., 1] . . + . + + 3 TAB V M ^ * 511 % +@end smallexample +@end group + +@noindent +Once again, @kbd{*} elegantly summarizes most of the computation. +But there's an even more elegant approach: Reduce the formula +@kbd{3 $$ + $} across the vector. Recall that this represents a +function of two arguments that computes its first argument times three +plus its second argument. + +@group +@smallexample +1: [84, 101, 115, ..., 51] 1: 1960915098 + . . + + "Testing, 1, 2, 3 RET V R ' 3$$+$ RET +@end smallexample +@end group + +@noindent +If you did the decimal arithmetic exercise, this will be familiar. +Basically, we're turning a base-3 vector of digits into an integer, +except that our ``digits'' are much larger than real digits. + +Instead of typing @kbd{511 %} again to reduce the result, we can be +cleverer still and notice that rather than computing a huge integer +and taking the modulo at the end, we can take the modulo at each step +without affecting the result. While this means there are more +arithmetic operations, the numbers we operate on remain small so +the operations are faster. + +@group +@smallexample +1: [84, 101, 115, ..., 51] 1: 121 + . . + + "Testing, 1, 2, 3 RET V R ' (3$$+$)%511 RET +@end smallexample +@end group + +Why does this work? Think about a two-step computation: +@w{@cite{3 (3a + b) + c}}. Taking a result modulo 511 basically means +subtracting off enough 511's to put the result in the desired range. +So the result when we take the modulo after every step is, + +@ifinfo +@example +3 (3 a + b - 511 m) + c - 511 n +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ 3 (3 a + b - 511 m) + c - 511 n $$ +\afterdisplay +@end tex + +@noindent +for some suitable integers @cite{m} and @cite{n}. Expanding out by +the distributive law yields + +@ifinfo +@example +9 a + 3 b + c - 511*3 m - 511 n +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ 9 a + 3 b + c - 511\times3 m - 511 n $$ +\afterdisplay +@end tex + +@noindent +The @cite{m} term in the latter formula is redundant because any +contribution it makes could just as easily be made by the @cite{n} +term. So we can take it out to get an equivalent formula with +@cite{n' = 3m + n}, + +@ifinfo +@example +9 a + 3 b + c - 511 n' +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ 9 a + 3 b + c - 511 n' $$ +\afterdisplay +@end tex + +@noindent +which is just the formula for taking the modulo only at the end of +the calculation. Therefore the two methods are essentially the same. + +Later in the tutorial we will encounter @dfn{modulo forms}, which +basically automate the idea of reducing every intermediate result +modulo some value @i{M}. + +@node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises +@subsection List Tutorial Exercise 14 + +We want to use @kbd{H V U} to nest a function which adds a random +step to an @cite{(x,y)} coordinate. The function is a bit long, but +otherwise the problem is quite straightforward. + +@group +@smallexample +2: [0, 0] 1: [ [ 0, 0 ] +1: 50 [ 0.4288, -0.1695 ] + . [ -0.4787, -0.9027 ] + ... + + [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> RET +@end smallexample +@end group + +Just as the text recommended, we used @samp{< >} nameless function +notation to keep the two @code{random} calls from being evaluated +before nesting even begins. + +We now have a vector of @cite{[x, y]} sub-vectors, which by Calc's +rules acts like a matrix. We can transpose this matrix and unpack +to get a pair of vectors, @cite{x} and @cite{y}, suitable for graphing. + +@group +@smallexample +2: [ 0, 0.4288, -0.4787, ... ] +1: [ 0, -0.1696, -0.9027, ... ] + . + + v t v u g f +@end smallexample +@end group + +Incidentally, because the @cite{x} and @cite{y} are completely +independent in this case, we could have done two separate commands +to create our @cite{x} and @cite{y} vectors of numbers directly. + +To make a random walk of unit steps, we note that @code{sincos} of +a random direction exactly gives us an @cite{[x, y]} step of unit +length; in fact, the new nesting function is even briefer, though +we might want to lower the precision a bit for it. + +@group +@smallexample +2: [0, 0] 1: [ [ 0, 0 ] +1: 50 [ 0.1318, 0.9912 ] + . [ -0.5965, 0.3061 ] + ... + + [0,0] 50 m d p 6 RET H V U ' <# + sincos(random(360.0))> RET +@end smallexample +@end group + +Another @kbd{v t v u g f} sequence will graph this new random walk. + +An interesting twist on these random walk functions would be to use +complex numbers instead of 2-vectors to represent points on the plane. +In the first example, we'd use something like @samp{random + random*(0,1)}, +and in the second we could use polar complex numbers with random phase +angles. (This exercise was first suggested in this form by Randal +Schwartz.) + +@node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises +@subsection Types Tutorial Exercise 1 + +@noindent +If the number is the square root of @c{$\pi$} +@cite{pi} times a rational number, +then its square, divided by @c{$\pi$} +@cite{pi}, should be a rational number. + +@group +@smallexample +1: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627 + . . . + + 2 ^ P / c F +@end smallexample +@end group + +@noindent +Technically speaking this is a rational number, but not one that is +likely to have arisen in the original problem. More likely, it just +happens to be the fraction which most closely represents some +irrational number to within 12 digits. + +But perhaps our result was not quite exact. Let's reduce the +precision slightly and try again: + +@group +@smallexample +1: 0.509433962268 1: 27:53 + . . + + U p 10 RET c F +@end smallexample +@end group + +@noindent +Aha! It's unlikely that an irrational number would equal a fraction +this simple to within ten digits, so our original number was probably +@c{$\sqrt{27 \pi / 53}$} +@cite{sqrt(27 pi / 53)}. + +Notice that we didn't need to re-round the number when we reduced the +precision. Remember, arithmetic operations always round their inputs +to the current precision before they begin. + +@node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises +@subsection Types Tutorial Exercise 2 + +@noindent +@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer. +But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too. + +@samp{exp(inf) = inf}. It's tempting to say that the exponential +of infinity must be ``bigger'' than ``regular'' infinity, but as +far as Calc is concerned all infinities are as just as big. +In other words, as @cite{x} goes to infinity, @cite{e^x} also goes +to infinity, but the fact the @cite{e^x} grows much faster than +@cite{x} is not relevant here. + +@samp{exp(-inf) = 0}. Here we have a finite answer even though +the input is infinite. + +@samp{sqrt(-inf) = (0, 1) inf}. Remember that @cite{(0, 1)} +represents the imaginary number @cite{i}. Here's a derivation: +@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}. +The first part is, by definition, @cite{i}; the second is @code{inf} +because, once again, all infinities are the same size. + +@samp{sqrt(uinf) = uinf}. In fact, we do know something about the +direction because @code{sqrt} is defined to return a value in the +right half of the complex plane. But Calc has no notation for this, +so it settles for the conservative answer @code{uinf}. + +@samp{abs(uinf) = inf}. No matter which direction @cite{x} points, +@samp{abs(x)} always points along the positive real axis. + +@samp{ln(0) = -inf}. Here we have an infinite answer to a finite +input. As in the @cite{1 / 0} case, Calc will only use infinities +here if you have turned on ``infinite'' mode. Otherwise, it will +treat @samp{ln(0)} as an error. + +@node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises +@subsection Types Tutorial Exercise 3 + +@noindent +We can make @samp{inf - inf} be any real number we like, say, +@cite{a}, just by claiming that we added @cite{a} to the first +infinity but not to the second. This is just as true for complex +values of @cite{a}, so @code{nan} can stand for a complex number. +(And, similarly, @code{uinf} can stand for an infinity that points +in any direction in the complex plane, such as @samp{(0, 1) inf}). + +In fact, we can multiply the first @code{inf} by two. Surely +@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}. +So @code{nan} can even stand for infinity. Obviously it's just +as easy to make it stand for minus infinity as for plus infinity. + +The moral of this story is that ``infinity'' is a slippery fish +indeed, and Calc tries to handle it by having a very simple model +for infinities (only the direction counts, not the ``size''); but +Calc is careful to write @code{nan} any time this simple model is +unable to tell what the true answer is. + +@node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises +@subsection Types Tutorial Exercise 4 + +@group +@smallexample +2: 0@@ 47' 26" 1: 0@@ 2' 47.411765" +1: 17 . + . + + 0@@ 47' 26" RET 17 / +@end smallexample +@end group + +@noindent +The average song length is two minutes and 47.4 seconds. + +@group +@smallexample +2: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005" +1: 0@@ 0' 20" . . + . + + 20" + 17 * +@end smallexample +@end group + +@noindent +The album would be 53 minutes and 6 seconds long. + +@node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises +@subsection Types Tutorial Exercise 5 + +@noindent +Let's suppose it's January 14, 1991. The easiest thing to do is +to keep trying 13ths of months until Calc reports a Friday. +We can do this by manually entering dates, or by using @kbd{t I}: + +@group +@smallexample +1: <Wed Feb 13, 1991> 1: <Wed Mar 13, 1991> 1: <Sat Apr 13, 1991> + . . . + + ' <2/13> RET DEL ' <3/13> RET t I +@end smallexample +@end group + +@noindent +(Calc assumes the current year if you don't say otherwise.) + +This is getting tedious---we can keep advancing the date by typing +@kbd{t I} over and over again, but let's automate the job by using +vector mapping. The @kbd{t I} command actually takes a second +``how-many-months'' argument, which defaults to one. This +argument is exactly what we want to map over: + +@group +@smallexample +2: <Sat Apr 13, 1991> 1: [<Mon May 13, 1991>, <Thu Jun 13, 1991>, +1: [1, 2, 3, 4, 5, 6] <Sat Jul 13, 1991>, <Tue Aug 13, 1991>, + . <Fri Sep 13, 1991>, <Sun Oct 13, 1991>] + . + + v x 6 RET V M t I +@end smallexample +@end group + +@ifinfo +@noindent +Et voila, September 13, 1991 is a Friday. +@end ifinfo +@tex +\noindent +{\it Et voil{\accent"12 a}}, September 13, 1991 is a Friday. +@end tex + +@group +@smallexample +1: 242 + . + +' <sep 13> - <jan 14> RET +@end smallexample +@end group + +@noindent +And the answer to our original question: 242 days to go. + +@node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises +@subsection Types Tutorial Exercise 6 + +@noindent +The full rule for leap years is that they occur in every year divisible +by four, except that they don't occur in years divisible by 100, except +that they @emph{do} in years divisible by 400. We could work out the +answer by carefully counting the years divisible by four and the +exceptions, but there is a much simpler way that works even if we +don't know the leap year rule. + +Let's assume the present year is 1991. Years have 365 days, except +that leap years (whenever they occur) have 366 days. So let's count +the number of days between now and then, and compare that to the +number of years times 365. The number of extra days we find must be +equal to the number of leap years there were. + +@group +@smallexample +1: <Mon Jan 1, 10001> 2: <Mon Jan 1, 10001> 1: 2925593 + . 1: <Tue Jan 1, 1991> . + . + + ' <jan 1 10001> RET ' <jan 1 1991> RET - + +@end smallexample +@end group +@noindent +@group +@smallexample +3: 2925593 2: 2925593 2: 2925593 1: 1943 +2: 10001 1: 8010 1: 2923650 . +1: 1991 . . + . + + 10001 RET 1991 - 365 * - +@end smallexample +@end group + +@c [fix-ref Date Forms] +@noindent +There will be 1943 leap years before the year 10001. (Assuming, +of course, that the algorithm for computing leap years remains +unchanged for that long. @xref{Date Forms}, for some interesting +background information in that regard.) + +@node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises +@subsection Types Tutorial Exercise 7 + +@noindent +The relative errors must be converted to absolute errors so that +@samp{+/-} notation may be used. + +@group +@smallexample +1: 1. 2: 1. + . 1: 0.2 + . + + 20 RET .05 * 4 RET .05 * +@end smallexample +@end group + +Now we simply chug through the formula. + +@group +@smallexample +1: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21 + . . . + + 2 P 2 ^ * 20 p 1 * 4 p .2 RET 2 ^ * +@end smallexample +@end group + +It turns out the @kbd{v u} command will unpack an error form as +well as a vector. This saves us some retyping of numbers. + +@group +@smallexample +3: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21 +2: 6316.5 1: 0.1118 +1: 706.21 . + . + + RET v u TAB / +@end smallexample +@end group + +@noindent +Thus the volume is 6316 cubic centimeters, within about 11 percent. + +@node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises +@subsection Types Tutorial Exercise 8 + +@noindent +The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}. +Since a number in the interval @samp{(0 .. 10)} can get arbitrarily +close to zero, its reciprocal can get arbitrarily large, so the answer +is an interval that effectively means, ``any number greater than 0.1'' +but with no upper bound. + +The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}. + +Calc normally treats division by zero as an error, so that the formula +@w{@samp{1 / 0}} is left unsimplified. Our third problem, +@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero +is now a member of the interval. So Calc leaves this one unevaluated, too. + +If you turn on ``infinite'' mode by pressing @kbd{m i}, you will +instead get the answer @samp{[0.1 .. inf]}, which includes infinity +as a possible value. + +The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem. +Zero is buried inside the interval, but it's still a possible value. +It's not hard to see that the actual result of @samp{1 / (-10 .. 10)} +will be either greater than @i{0.1}, or less than @i{-0.1}. Thus +the interval goes from minus infinity to plus infinity, with a ``hole'' +in it from @i{-0.1} to @i{0.1}. Calc doesn't have any way to +represent this, so it just reports @samp{[-inf .. inf]} as the answer. +It may be disappointing to hear ``the answer lies somewhere between +minus infinity and plus infinity, inclusive,'' but that's the best +that interval arithmetic can do in this case. + +@node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises +@subsection Types Tutorial Exercise 9 + +@group +@smallexample +1: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9] + . 1: [0 .. 9] 1: [-9 .. 9] + . . + + [ 3 n .. 3 ] RET 2 ^ TAB RET * +@end smallexample +@end group + +@noindent +In the first case the result says, ``if a number is between @i{-3} and +3, its square is between 0 and 9.'' The second case says, ``the product +of two numbers each between @i{-3} and 3 is between @i{-9} and 9.'' + +An interval form is not a number; it is a symbol that can stand for +many different numbers. Two identical-looking interval forms can stand +for different numbers. + +The same issue arises when you try to square an error form. + +@node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises +@subsection Types Tutorial Exercise 10 + +@noindent +Testing the first number, we might arbitrarily choose 17 for @cite{x}. + +@group +@smallexample +1: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613 + . 811749612 . + . + + 17 M 811749613 RET 811749612 ^ +@end smallexample +@end group + +@noindent +Since 533694123 is (considerably) different from 1, the number 811749613 +must not be prime. + +It's awkward to type the number in twice as we did above. There are +various ways to avoid this, and algebraic entry is one. In fact, using +a vector mapping operation we can perform several tests at once. Let's +use this method to test the second number. + +@group +@smallexample +2: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ] +1: 15485863 . + . + + [17 42 100000] 15485863 RET V M ' ($$ mod $)^($-1) RET +@end smallexample +@end group + +@noindent +The result is three ones (modulo @cite{n}), so it's very probable that +15485863 is prime. (In fact, this number is the millionth prime.) + +Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $} +would have been hopelessly inefficient, since they would have calculated +the power using full integer arithmetic. + +Calc has a @kbd{k p} command that does primality testing. For small +numbers it does an exact test; for large numbers it uses a variant +of the Fermat test we used here. You can use @kbd{k p} repeatedly +to prove that a large integer is prime with any desired probability. + +@node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises +@subsection Types Tutorial Exercise 11 + +@noindent +There are several ways to insert a calculated number into an HMS form. +One way to convert a number of seconds to an HMS form is simply to +multiply the number by an HMS form representing one second: + +@group +@smallexample +1: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359" + . 1: 0@@ 0' 1" . + . + + P 1e7 * 0@@ 0' 1" * + +@end smallexample +@end group +@noindent +@group +@smallexample +2: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0" +1: 15@@ 27' 16" mod 24@@ 0' 0" . + . + + x time RET + +@end smallexample +@end group + +@noindent +It will be just after six in the morning. + +The algebraic @code{hms} function can also be used to build an +HMS form: + +@group +@smallexample +1: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359" + . . + + ' hms(0, 0, 1e7 pi) RET = +@end smallexample +@end group + +@noindent +The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to +the actual number 3.14159... + +@node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises +@subsection Types Tutorial Exercise 12 + +@noindent +As we recall, there are 17 songs of about 2 minutes and 47 seconds +each. + +@group +@smallexample +2: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"] +1: [0@@ 0' 20" .. 0@@ 1' 0"] . + . + + [ 0@@ 20" .. 0@@ 1' ] + + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [0@@ 52' 59." .. 1@@ 4' 19."] + . + + 17 * +@end smallexample +@end group + +@noindent +No matter how long it is, the album will fit nicely on one CD. + +@node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises +@subsection Types Tutorial Exercise 13 + +@noindent +Type @kbd{' 1 yr RET u c s RET}. The answer is 31557600 seconds. + +@node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises +@subsection Types Tutorial Exercise 14 + +@noindent +How long will it take for a signal to get from one end of the computer +to the other? + +@group +@smallexample +1: m / c 1: 3.3356 ns + . . + + ' 1 m / c RET u c ns RET +@end smallexample +@end group + +@noindent +(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.) + +@group +@smallexample +1: 3.3356 ns 1: 0.81356 ns / ns 1: 0.81356 +2: 4.1 ns . . + . + + ' 4.1 ns RET / u s +@end smallexample +@end group + +@noindent +Thus a signal could take up to 81 percent of a clock cycle just to +go from one place to another inside the computer, assuming the signal +could actually attain the full speed of light. Pretty tight! + +@node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises +@subsection Types Tutorial Exercise 15 + +@noindent +The speed limit is 55 miles per hour on most highways. We want to +find the ratio of Sam's speed to the US speed limit. + +@group +@smallexample +1: 55 mph 2: 55 mph 3: 11 hr mph / yd + . 1: 5 yd / hr . + . + + ' 55 mph RET ' 5 yd/hr RET / +@end smallexample +@end group + +The @kbd{u s} command cancels out these units to get a plain +number. Now we take the logarithm base two to find the final +answer, assuming that each successive pill doubles his speed. + +@group +@smallexample +1: 19360. 2: 19360. 1: 14.24 + . 1: 2 . + . + + u s 2 B +@end smallexample +@end group + +@noindent +Thus Sam can take up to 14 pills without a worry. + +@node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises +@subsection Algebra Tutorial Exercise 1 + +@noindent +@c [fix-ref Declarations] +The result @samp{sqrt(x)^2} is simplified back to @cite{x} by the +Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens +if @w{@cite{x = -4}}.) If @cite{x} is real, this formula could be +simplified to @samp{abs(x)}, but for general complex arguments even +that is not safe. (@xref{Declarations}, for a way to tell Calc +that @cite{x} is known to be real.) + +@node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises +@subsection Algebra Tutorial Exercise 2 + +@noindent +Suppose our roots are @cite{[a, b, c]}. We want a polynomial which +is zero when @cite{x} is any of these values. The trivial polynomial +@cite{x-a} is zero when @cite{x=a}, so the product @cite{(x-a)(x-b)(x-c)} +will do the job. We can use @kbd{a c x} to write this in a more +familiar form. + +@group +@smallexample +1: 34 x - 24 x^3 1: [1.19023, -1.19023, 0] + . . + + r 2 a P x RET + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [x - 1.19023, x + 1.19023, x] 1: (x - 1.19023) (x + 1.19023) x + . . + + V M ' x-$ RET V R * + +@end smallexample +@end group +@noindent +@group +@smallexample +1: x^3 - 1.41666 x 1: 34 x - 24 x^3 + . . + + a c x RET 24 n * a x +@end smallexample +@end group + +@noindent +Sure enough, our answer (multiplied by a suitable constant) is the +same as the original polynomial. + +@node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises +@subsection Algebra Tutorial Exercise 3 + +@group +@smallexample +1: x sin(pi x) 1: (sin(pi x) - pi x cos(pi x)) / pi^2 + . . + + ' x sin(pi x) RET m r a i x RET + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [y, 1] +2: (sin(pi x) - pi x cos(pi x)) / pi^2 + . + + ' [y,1] RET TAB + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [(sin(pi y) - pi y cos(pi y)) / pi^2, (sin(pi) - pi cos(pi)) / pi^2] + . + + V M $ RET + +@end smallexample +@end group +@noindent +@group +@smallexample +1: (sin(pi y) - pi y cos(pi y)) / pi^2 + (pi cos(pi) - sin(pi)) / pi^2 + . + + V R - + +@end smallexample +@end group +@noindent +@group +@smallexample +1: (sin(3.14159 y) - 3.14159 y cos(3.14159 y)) / 9.8696 - 0.3183 + . + + = + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [0., -0.95493, 0.63662, -1.5915, 1.2732] + . + + v x 5 RET TAB V M $ RET +@end smallexample +@end group + +@node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises +@subsection Algebra Tutorial Exercise 4 + +@noindent +The hard part is that @kbd{V R +} is no longer sufficient to add up all +the contributions from the slices, since the slices have varying +coefficients. So first we must come up with a vector of these +coefficients. Here's one way: + +@group +@smallexample +2: -1 2: 3 1: [4, 2, ..., 4] +1: [1, 2, ..., 9] 1: [-1, 1, ..., -1] . + . . + + 1 n v x 9 RET V M ^ 3 TAB - + +@end smallexample +@end group +@noindent +@group +@smallexample +1: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1] + . . + + 1 | 1 TAB | +@end smallexample +@end group + +@noindent +Now we compute the function values. Note that for this method we need +eleven values, including both endpoints of the desired interval. + +@group +@smallexample +2: [1, 4, 2, ..., 4, 1] +1: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.] + . + + 11 RET 1 RET .1 RET C-u v x + +@end smallexample +@end group +@noindent +@group +@smallexample +2: [1, 4, 2, ..., 4, 1] +1: [0., 0.084941, 0.16993, ... ] + . + + ' sin(x) ln(x) RET m r p 5 RET V M $ RET +@end smallexample +@end group + +@noindent +Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the +same thing. + +@group +@smallexample +1: 11.22 1: 1.122 1: 0.374 + . . . + + * .1 * 3 / +@end smallexample +@end group + +@noindent +Wow! That's even better than the result from the Taylor series method. + +@node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises +@subsection Rewrites Tutorial Exercise 1 + +@noindent +We'll use Big mode to make the formulas more readable. + +@group +@smallexample + ___ + 2 + V 2 +1: (2 + sqrt(2)) / (1 + sqrt(2)) 1: -------- + . ___ + 1 + V 2 + + . + + ' (2+sqrt(2)) / (1+sqrt(2)) RET d B +@end smallexample +@end group + +@noindent +Multiplying by the conjugate helps because @cite{(a+b) (a-b) = a^2 - b^2}. + +@group +@smallexample + ___ ___ +1: (2 + V 2 ) (V 2 - 1) + . + + a r a/(b+c) := a*(b-c) / (b^2-c^2) RET + +@end smallexample +@end group +@noindent +@group +@smallexample + ___ ___ +1: 2 + V 2 - 2 1: V 2 + . . + + a r a*(b+c) := a*b + a*c a s +@end smallexample +@end group + +@noindent +(We could have used @kbd{a x} instead of a rewrite rule for the +second step.) + +The multiply-by-conjugate rule turns out to be useful in many +different circumstances, such as when the denominator involves +sines and cosines or the imaginary constant @code{i}. + +@node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises +@subsection Rewrites Tutorial Exercise 2 + +@noindent +Here is the rule set: + +@group +@smallexample +[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1, + fib(1, x, y) := x, + fib(n, x, y) := fib(n-1, y, x+y) ] +@end smallexample +@end group + +@noindent +The first rule turns a one-argument @code{fib} that people like to write +into a three-argument @code{fib} that makes computation easier. The +second rule converts back from three-argument form once the computation +is done. The third rule does the computation itself. It basically +says that if @cite{x} and @cite{y} are two consecutive Fibonacci numbers, +then @cite{y} and @cite{x+y} are the next (overlapping) pair of Fibonacci +numbers. + +Notice that because the number @cite{n} was ``validated'' by the +conditions on the first rule, there is no need to put conditions on +the other rules because the rule set would never get that far unless +the input were valid. That further speeds computation, since no +extra conditions need to be checked at every step. + +Actually, a user with a nasty sense of humor could enter a bad +three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)}, +which would get the rules into an infinite loop. One thing that would +help keep this from happening by accident would be to use something like +@samp{ZzFib} instead of @code{fib} as the name of the three-argument +function. + +@node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises +@subsection Rewrites Tutorial Exercise 3 + +@noindent +He got an infinite loop. First, Calc did as expected and rewrote +@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to +apply the rule again, and found that @samp{f(2, 3, x)} looks like +@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to +@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)} +around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r} +to make sure the rule applied only once. + +(Actually, even the first step didn't work as he expected. What Calc +really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)}, +treating 2 as the ``variable,'' and @samp{3 x} as a constant being added +to it. While this may seem odd, it's just as valid a solution as the +``obvious'' one. One way to fix this would be to add the condition +@samp{:: variable(x)} to the rule, to make sure the thing that matches +@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)} +on the lefthand side, so that the rule matches the actual variable +@samp{x} rather than letting @samp{x} stand for something else.) + +@node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises +@subsection Rewrites Tutorial Exercise 4 + +@noindent +@c @starindex +@tindex seq +Here is a suitable set of rules to solve the first part of the problem: + +@group +@smallexample +[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0, + seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ] +@end smallexample +@end group + +Given the initial formula @samp{seq(6, 0)}, application of these +rules produces the following sequence of formulas: + +@example +seq( 3, 1) +seq(10, 2) +seq( 5, 3) +seq(16, 4) +seq( 8, 5) +seq( 4, 6) +seq( 2, 7) +seq( 1, 8) +@end example + +@noindent +whereupon neither of the rules match, and rewriting stops. + +We can pretty this up a bit with a couple more rules: + +@group +@smallexample +[ seq(n) := seq(n, 0), + seq(1, c) := c, + ... ] +@end smallexample +@end group + +@noindent +Now, given @samp{seq(6)} as the starting configuration, we get 8 +as the result. + +The change to return a vector is quite simple: + +@group +@smallexample +[ seq(n) := seq(n, []) :: integer(n) :: n > 0, + seq(1, v) := v | 1, + seq(n, v) := seq(n/2, v | n) :: n%2 = 0, + seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ] +@end smallexample +@end group + +@noindent +Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. + +Notice that the @cite{n > 1} guard is no longer necessary on the last +rule since the @cite{n = 1} case is now detected by another rule. +But a guard has been added to the initial rule to make sure the +initial value is suitable before the computation begins. + +While still a good idea, this guard is not as vitally important as it +was for the @code{fib} function, since calling, say, @samp{seq(x, [])} +will not get into an infinite loop. Calc will not be able to prove +the symbol @samp{x} is either even or odd, so none of the rules will +apply and the rewrites will stop right away. + +@node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises +@subsection Rewrites Tutorial Exercise 5 + +@noindent +@c @starindex +@tindex nterms +If @cite{x} is the sum @cite{a + b}, then `@t{nterms(}@i{x}@t{)}' must +be `@t{nterms(}@i{a}@t{)}' plus `@t{nterms(}@i{b}@t{)}'. If @cite{x} +is not a sum, then `@t{nterms(}@i{x}@t{)}' = 1. + +@group +@smallexample +[ nterms(a + b) := nterms(a) + nterms(b), + nterms(x) := 1 ] +@end smallexample +@end group + +@noindent +Here we have taken advantage of the fact that earlier rules always +match before later rules; @samp{nterms(x)} will only be tried if we +already know that @samp{x} is not a sum. + +@node Rewrites Answer 6, Rewrites Answer 7, Rewrites Answer 5, Answers to Exercises +@subsection Rewrites Tutorial Exercise 6 + +Just put the rule @samp{0^0 := 1} into @code{EvalRules}. For example, +before making this definition we have: + +@group +@smallexample +2: [-2, -1, 0, 1, 2] 1: [1, 1, 0^0, 1, 1] +1: 0 . + . + + v x 5 RET 3 - 0 V M ^ +@end smallexample +@end group + +@noindent +But then: + +@group +@smallexample +2: [-2, -1, 0, 1, 2] 1: [1, 1, 1, 1, 1] +1: 0 . + . + + U ' 0^0:=1 RET s t EvalRules RET V M ^ +@end smallexample +@end group + +Perhaps more surprisingly, this rule still works with infinite mode +turned on. Calc tries @code{EvalRules} before any built-in rules for +a function. This allows you to override the default behavior of any +Calc feature: Even though Calc now wants to evaluate @cite{0^0} to +@code{nan}, your rule gets there first and evaluates it to 1 instead. + +Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}. +What happens? (Be sure to remove this rule afterward, or you might get +a nasty surprise when you use Calc to balance your checkbook!) + +@node Rewrites Answer 7, Programming Answer 1, Rewrites Answer 6, Answers to Exercises +@subsection Rewrites Tutorial Exercise 7 + +@noindent +Here is a rule set that will do the job: + +@group +@smallexample +[ a*(b + c) := a*b + a*c, + opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m + :: constant(a) :: constant(b), + opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m + :: constant(a) :: constant(b), + a O(x^n) := O(x^n) :: constant(a), + x^opt(m) O(x^n) := O(x^(n+m)), + O(x^n) O(x^m) := O(x^(n+m)) ] +@end smallexample +@end group + +If we really want the @kbd{+} and @kbd{*} keys to operate naturally +on power series, we should put these rules in @code{EvalRules}. For +testing purposes, it is better to put them in a different variable, +say, @code{O}, first. + +The first rule just expands products of sums so that the rest of the +rules can assume they have an expanded-out polynomial to work with. +Note that this rule does not mention @samp{O} at all, so it will +apply to any product-of-sum it encounters---this rule may surprise +you if you put it into @code{EvalRules}! + +In the second rule, the sum of two O's is changed to the smaller O. +The optional constant coefficients are there mostly so that +@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled +as well as @samp{O(x^2) + O(x^3)}. + +The third rule absorbs higher powers of @samp{x} into O's. + +The fourth rule says that a constant times a negligible quantity +is still negligible. (This rule will also match @samp{O(x^3) / 4}, +with @samp{a = 1/4}.) + +The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}. +(It is easy to see that if one of these forms is negligible, the other +is, too.) Notice the @samp{x^opt(m)} to pick up terms like +@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1} +but not 1 as @samp{x^0}. This turns out to be exactly what we want here. + +The sixth rule is the corresponding rule for products of two O's. + +Another way to solve this problem would be to create a new ``data type'' +that represents truncated power series. We might represent these as +function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is +a vector of coefficients for @cite{x^0}, @cite{x^1}, @cite{x^2}, and so +on. Rules would exist for sums and products of such @code{series} +objects, and as an optional convenience could also know how to combine a +@code{series} object with a normal polynomial. (With this, and with a +rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form, +you could still enter power series in exactly the same notation as +before.) Operations on such objects would probably be more efficient, +although the objects would be a bit harder to read. + +@c [fix-ref Compositions] +Some other symbolic math programs provide a power series data type +similar to this. Mathematica, for example, has an object that looks +like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin}, +@var{nmax}, @var{den}]}, where @var{x0} is the point about which the +power series is taken (we've been assuming this was always zero), +and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series +with fractional or negative powers. Also, the @code{PowerSeries} +objects have a special display format that makes them look like +@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions}, +for a way to do this in Calc, although for something as involved as +this it would probably be better to write the formatting routine +in Lisp.) + +@node Programming Answer 1, Programming Answer 2, Rewrites Answer 7, Answers to Exercises +@subsection Programming Tutorial Exercise 1 + +@noindent +Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type +@kbd{Z F}, and answer the questions. Since this formula contains two +variables, the default argument list will be @samp{(t x)}. We want to +change this to @samp{(x)} since @cite{t} is really a dummy variable +to be used within @code{ninteg}. + +The exact keystrokes are @kbd{Z F s Si RET RET C-b C-b DEL DEL RET y}. +(The @kbd{C-b C-b DEL DEL} are what fix the argument list.) + +@node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises +@subsection Programming Tutorial Exercise 2 + +@noindent +One way is to move the number to the top of the stack, operate on +it, then move it back: @kbd{C-x ( M-TAB n M-TAB M-TAB C-x )}. + +Another way is to negate the top three stack entries, then negate +again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}. + +Finally, it turns out that a negative prefix argument causes a +command like @kbd{n} to operate on the specified stack entry only, +which is just what we want: @kbd{C-x ( M-- 3 n C-x )}. + +Just for kicks, let's also do it algebraically: +@w{@kbd{C-x ( ' -$$$, $$, $ RET C-x )}}. + +@node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises +@subsection Programming Tutorial Exercise 3 + +@noindent +Each of these functions can be computed using the stack, or using +algebraic entry, whichever way you prefer: + +@noindent +Computing @c{$\displaystyle{\sin x \over x}$} +@cite{sin(x) / x}: + +Using the stack: @kbd{C-x ( RET S TAB / C-x )}. + +Using algebraic entry: @kbd{C-x ( ' sin($)/$ RET C-x )}. + +@noindent +Computing the logarithm: + +Using the stack: @kbd{C-x ( TAB B C-x )} + +Using algebraic entry: @kbd{C-x ( ' log($,$$) RET C-x )}. + +@noindent +Computing the vector of integers: + +Using the stack: @kbd{C-x ( 1 RET 1 C-u v x C-x )}. (Recall that +@kbd{C-u v x} takes the vector size, starting value, and increment +from the stack.) + +Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a +number from the stack and uses it as the prefix argument for the +next command.) + +Using algebraic entry: @kbd{C-x ( ' index($) RET C-x )}. + +@node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises +@subsection Programming Tutorial Exercise 4 + +@noindent +Here's one way: @kbd{C-x ( RET V R + TAB v l / C-x )}. + +@node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises +@subsection Programming Tutorial Exercise 5 + +@group +@smallexample +2: 1 1: 1.61803398502 2: 1.61803398502 +1: 20 . 1: 1.61803398875 + . . + + 1 RET 20 Z < & 1 + Z > I H P +@end smallexample +@end group + +@noindent +This answer is quite accurate. + +@node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises +@subsection Programming Tutorial Exercise 6 + +@noindent +Here is the matrix: + +@example +[ [ 0, 1 ] * [a, b] = [b, a + b] + [ 1, 1 ] ] +@end example + +@noindent +Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @cite{n+1} +and @cite{n+2}. Here's one program that does the job: + +@example +C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] RET v u DEL C-x ) +@end example + +@noindent +This program is quite efficient because Calc knows how to raise a +matrix (or other value) to the power @cite{n} in only @c{$\log_2 n$} +@cite{log(n,2)} +steps. For example, this program can compute the 1000th Fibonacci +number (a 209-digit integer!) in about 10 steps; even though the +@kbd{Z < ... Z >} solution had much simpler steps, it would have +required so many steps that it would not have been practical. + +@node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises +@subsection Programming Tutorial Exercise 7 + +@noindent +The trick here is to compute the harmonic numbers differently, so that +the loop counter itself accumulates the sum of reciprocals. We use +a separate variable to hold the integer counter. + +@group +@smallexample +1: 1 2: 1 1: . + . 1: 4 + . + + 1 t 1 1 RET 4 Z ( t 2 r 1 1 + s 1 & Z ) +@end smallexample +@end group + +@noindent +The body of the loop goes as follows: First save the harmonic sum +so far in variable 2. Then delete it from the stack; the for loop +itself will take care of remembering it for us. Next, recall the +count from variable 1, add one to it, and feed its reciprocal to +the for loop to use as the step value. The for loop will increase +the ``loop counter'' by that amount and keep going until the +loop counter exceeds 4. + +@group +@smallexample +2: 31 3: 31 +1: 3.99498713092 2: 3.99498713092 + . 1: 4.02724519544 + . + + r 1 r 2 RET 31 & + +@end smallexample +@end group + +Thus we find that the 30th harmonic number is 3.99, and the 31st +harmonic number is 4.02. + +@node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises +@subsection Programming Tutorial Exercise 8 + +@noindent +The first step is to compute the derivative @cite{f'(x)} and thus +the formula @c{$\displaystyle{x - {f(x) \over f'(x)}}$} +@cite{x - f(x)/f'(x)}. + +(Because this definition is long, it will be repeated in concise form +below. You can use @w{@kbd{M-# m}} to load it from there. While you are +entering a @kbd{Z ` Z '} body in a macro, Calc simply collects +keystrokes without executing them. In the following diagrams we'll +pretend Calc actually executed the keystrokes as you typed them, +just for purposes of illustration.) + +@group +@smallexample +2: sin(cos(x)) - 0.5 3: 4.5 +1: 4.5 2: sin(cos(x)) - 0.5 + . 1: -(sin(x) cos(cos(x))) + . + +' sin(cos(x))-0.5 RET 4.5 m r C-x ( Z ` TAB RET a d x RET + +@end smallexample +@end group +@noindent +@group +@smallexample +2: 4.5 +1: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x)) + . + + / ' x RET TAB - t 1 +@end smallexample +@end group + +Now, we enter the loop. We'll use a repeat loop with a 20-repetition +limit just in case the method fails to converge for some reason. +(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20 +repetitions are done.) + +@group +@smallexample +1: 4.5 3: 4.5 2: 4.5 + . 2: x + (sin(cos(x)) ... 1: 5.24196456928 + 1: 4.5 . + . + + 20 Z < RET r 1 TAB s l x RET +@end smallexample +@end group + +This is the new guess for @cite{x}. Now we compare it with the +old one to see if we've converged. + +@group +@smallexample +3: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348 +2: 5.24196 1: 0 . . +1: 4.5 . + . + + RET M-TAB a = Z / Z > Z ' C-x ) +@end smallexample +@end group + +The loop converges in just a few steps to this value. To check +the result, we can simply substitute it back into the equation. + +@group +@smallexample +2: 5.26345856348 +1: 0.499999999997 + . + + RET ' sin(cos($)) RET +@end smallexample +@end group + +Let's test the new definition again: + +@group +@smallexample +2: x^2 - 9 1: 3. +1: 1 . + . + + ' x^2-9 RET 1 X +@end smallexample +@end group + +Once again, here's the full Newton's Method definition: + +@group +@example +C-x ( Z ` TAB RET a d x RET / ' x RET TAB - t 1 + 20 Z < RET r 1 TAB s l x RET + RET M-TAB a = Z / + Z > + Z ' +C-x ) +@end example +@end group + +@c [fix-ref Nesting and Fixed Points] +It turns out that Calc has a built-in command for applying a formula +repeatedly until it converges to a number. @xref{Nesting and Fixed Points}, +to see how to use it. + +@c [fix-ref Root Finding] +Also, of course, @kbd{a R} is a built-in command that uses Newton's +method (among others) to look for numerical solutions to any equation. +@xref{Root Finding}. + +@node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises +@subsection Programming Tutorial Exercise 9 + +@noindent +The first step is to adjust @cite{z} to be greater than 5. A simple +``for'' loop will do the job here. If @cite{z} is less than 5, we +reduce the problem using @c{$\psi(z) = \psi(z+1) - 1/z$} +@cite{psi(z) = psi(z+1) - 1/z}. We go +on to compute @c{$\psi(z+1)$} +@cite{psi(z+1)}, and remember to add back a factor of +@cite{-1/z} when we're done. This step is repeated until @cite{z > 5}. + +(Because this definition is long, it will be repeated in concise form +below. You can use @w{@kbd{M-# m}} to load it from there. While you are +entering a @kbd{Z ` Z '} body in a macro, Calc simply collects +keystrokes without executing them. In the following diagrams we'll +pretend Calc actually executed the keystrokes as you typed them, +just for purposes of illustration.) + +@group +@smallexample +1: 1. 1: 1. + . . + + 1.0 RET C-x ( Z ` s 1 0 t 2 +@end smallexample +@end group + +Here, variable 1 holds @cite{z} and variable 2 holds the adjustment +factor. If @cite{z < 5}, we use a loop to increase it. + +(By the way, we started with @samp{1.0} instead of the integer 1 because +otherwise the calculation below will try to do exact fractional arithmetic, +and will never converge because fractions compare equal only if they +are exactly equal, not just equal to within the current precision.) + +@group +@smallexample +3: 1. 2: 1. 1: 6. +2: 1. 1: 1 . +1: 5 . + . + + RET 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] +@end smallexample +@end group + +Now we compute the initial part of the sum: @c{$\ln z - {1 \over 2z}$} +@cite{ln(z) - 1/2z} +minus the adjustment factor. + +@group +@smallexample +2: 1.79175946923 2: 1.7084261359 1: -0.57490719743 +1: 0.0833333333333 1: 2.28333333333 . + . . + + L r 1 2 * & - r 2 - +@end smallexample +@end group + +Now we evaluate the series. We'll use another ``for'' loop counting +up the value of @cite{2 n}. (Calc does have a summation command, +@kbd{a +}, but we'll use loops just to get more practice with them.) + +@group +@smallexample +3: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749 +2: 2 2: 1:6 3: 1:6 1: 2.3148e-3 +1: 40 1: 2 2: 2 . + . . 1: 36. + . + + 2 RET 40 Z ( RET k b TAB RET r 1 TAB ^ * / + +@end smallexample +@end group +@noindent +@group +@smallexample +3: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892 +2: -0.5749 2: -0.5772 1: 0 . +1: 2.3148e-3 1: -0.5749 . + . . + + TAB RET M-TAB - RET M-TAB a = Z / 2 Z ) Z ' C-x ) +@end smallexample +@end group + +This is the value of @c{$-\gamma$} +@cite{- gamma}, with a slight bit of roundoff error. +To get a full 12 digits, let's use a higher precision: + +@group +@smallexample +2: -0.577215664892 2: -0.577215664892 +1: 1. 1: -0.577215664901532 + + 1. RET p 16 RET X +@end smallexample +@end group + +Here's the complete sequence of keystrokes: + +@group +@example +C-x ( Z ` s 1 0 t 2 + RET 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] + L r 1 2 * & - r 2 - + 2 RET 40 Z ( RET k b TAB RET r 1 TAB ^ * / + TAB RET M-TAB - RET M-TAB a = Z / + 2 Z ) + Z ' +C-x ) +@end example +@end group + +@node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises +@subsection Programming Tutorial Exercise 10 + +@noindent +Taking the derivative of a term of the form @cite{x^n} will produce +a term like @c{$n x^{n-1}$} +@cite{n x^(n-1)}. Taking the derivative of a constant +produces zero. From this it is easy to see that the @cite{n}th +derivative of a polynomial, evaluated at @cite{x = 0}, will equal the +coefficient on the @cite{x^n} term times @cite{n!}. + +(Because this definition is long, it will be repeated in concise form +below. You can use @w{@kbd{M-# m}} to load it from there. While you are +entering a @kbd{Z ` Z '} body in a macro, Calc simply collects +keystrokes without executing them. In the following diagrams we'll +pretend Calc actually executed the keystrokes as you typed them, +just for purposes of illustration.) + +@group +@smallexample +2: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2 +1: 6 2: 0 + . 1: 6 + . + + ' 5 x^4 + (x+1)^2 RET 6 C-x ( Z ` [ ] t 1 0 TAB +@end smallexample +@end group + +@noindent +Variable 1 will accumulate the vector of coefficients. + +@group +@smallexample +2: 0 3: 0 2: 5 x^4 + ... +1: 5 x^4 + ... 2: 5 x^4 + ... 1: 1 + . 1: 1 . + . + + Z ( TAB RET 0 s l x RET M-TAB ! / s | 1 +@end smallexample +@end group + +@noindent +Note that @kbd{s | 1} appends the top-of-stack value to the vector +in a variable; it is completely analogous to @kbd{s + 1}. We could +have written instead, @kbd{r 1 TAB | t 1}. + +@group +@smallexample +1: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0] + . . . + + a d x RET 1 Z ) DEL r 1 Z ' C-x ) +@end smallexample +@end group + +To convert back, a simple method is just to map the coefficients +against a table of powers of @cite{x}. + +@group +@smallexample +2: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0] +1: 6 1: [0, 1, 2, 3, 4, 5, 6] + . . + + 6 RET 1 + 0 RET 1 C-u v x + +@end smallexample +@end group +@noindent +@group +@smallexample +2: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4 +1: [1, x, x^2, x^3, ... ] . + . + + ' x RET TAB V M ^ * +@end smallexample +@end group + +Once again, here are the whole polynomial to/from vector programs: + +@group +@example +C-x ( Z ` [ ] t 1 0 TAB + Z ( TAB RET 0 s l x RET M-TAB ! / s | 1 + a d x RET + 1 Z ) r 1 + Z ' +C-x ) + +C-x ( 1 + 0 RET 1 C-u v x ' x RET TAB V M ^ * C-x ) +@end example +@end group + +@node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises +@subsection Programming Tutorial Exercise 11 + +@noindent +First we define a dummy program to go on the @kbd{z s} key. The true +@w{@kbd{z s}} key is supposed to take two numbers from the stack and +return one number, so @kbd{DEL} as a dummy definition will make +sure the stack comes out right. + +@group +@smallexample +2: 4 1: 4 2: 4 +1: 2 . 1: 2 + . . + + 4 RET 2 C-x ( DEL C-x ) Z K s RET 2 +@end smallexample +@end group + +The last step replaces the 2 that was eaten during the creation +of the dummy @kbd{z s} command. Now we move on to the real +definition. The recurrence needs to be rewritten slightly, +to the form @cite{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}. + +(Because this definition is long, it will be repeated in concise form +below. You can use @kbd{M-# m} to load it from there.) + +@group +@smallexample +2: 4 4: 4 3: 4 2: 4 +1: 2 3: 2 2: 2 1: 2 + . 2: 4 1: 0 . + 1: 2 . + . + + C-x ( M-2 RET a = Z [ DEL DEL 1 Z : + +@end smallexample +@end group +@noindent +@group +@smallexample +4: 4 2: 4 2: 3 4: 3 4: 3 3: 3 +3: 2 1: 2 1: 2 3: 2 3: 2 2: 2 +2: 2 . . 2: 3 2: 3 1: 3 +1: 0 1: 2 1: 1 . + . . . + + RET 0 a = Z [ DEL DEL 0 Z : TAB 1 - TAB M-2 RET 1 - z s +@end smallexample +@end group + +@noindent +(Note that the value 3 that our dummy @kbd{z s} produces is not correct; +it is merely a placeholder that will do just as well for now.) + +@group +@smallexample +3: 3 4: 3 3: 3 2: 3 1: -6 +2: 3 3: 3 2: 3 1: 9 . +1: 2 2: 3 1: 3 . + . 1: 2 . + . + + M-TAB M-TAB TAB RET M-TAB z s * - + +@end smallexample +@end group +@noindent +@group +@smallexample +1: -6 2: 4 1: 11 2: 11 + . 1: 2 . 1: 11 + . . + + Z ] Z ] C-x ) Z K s RET DEL 4 RET 2 z s M-RET k s +@end smallexample +@end group + +Even though the result that we got during the definition was highly +bogus, once the definition is complete the @kbd{z s} command gets +the right answers. + +Here's the full program once again: + +@group +@example +C-x ( M-2 RET a = + Z [ DEL DEL 1 + Z : RET 0 a = + Z [ DEL DEL 0 + Z : TAB 1 - TAB M-2 RET 1 - z s + M-TAB M-TAB TAB RET M-TAB z s * - + Z ] + Z ] +C-x ) +@end example +@end group + +You can read this definition using @kbd{M-# m} (@code{read-kbd-macro}) +followed by @kbd{Z K s}, without having to make a dummy definition +first, because @code{read-kbd-macro} doesn't need to execute the +definition as it reads it in. For this reason, @code{M-# m} is often +the easiest way to create recursive programs in Calc. + +@node Programming Answer 12, , Programming Answer 11, Answers to Exercises +@subsection Programming Tutorial Exercise 12 + +@noindent +This turns out to be a much easier way to solve the problem. Let's +denote Stirling numbers as calls of the function @samp{s}. + +First, we store the rewrite rules corresponding to the definition of +Stirling numbers in a convenient variable: + +@smallexample +s e StirlingRules RET +[ s(n,n) := 1 :: n >= 0, + s(n,0) := 0 :: n > 0, + s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ] +C-c C-c +@end smallexample + +Now, it's just a matter of applying the rules: + +@group +@smallexample +2: 4 1: s(4, 2) 1: 11 +1: 2 . . + . + + 4 RET 2 C-x ( ' s($$,$) RET a r StirlingRules RET C-x ) +@end smallexample +@end group + +As in the case of the @code{fib} rules, it would be useful to put these +rules in @code{EvalRules} and to add a @samp{:: remember} condition to +the last rule. + +@c This ends the table-of-contents kludge from above: +@tex +\global\let\chapternofonts=\oldchapternofonts +@end tex + +@c [reference] + +@node Introduction, Data Types, Tutorial, Top +@chapter Introduction + +@noindent +This chapter is the beginning of the Calc reference manual. +It covers basic concepts such as the stack, algebraic and +numeric entry, undo, numeric prefix arguments, etc. + +@c [when-split] +@c (Chapter 2, the Tutorial, has been printed in a separate volume.) + +@menu +* Basic Commands:: +* Help Commands:: +* Stack Basics:: +* Numeric Entry:: +* Algebraic Entry:: +* Quick Calculator:: +* Keypad Mode:: +* Prefix Arguments:: +* Undo:: +* Error Messages:: +* Multiple Calculators:: +* Troubleshooting Commands:: +@end menu + +@node Basic Commands, Help Commands, Introduction, Introduction +@section Basic Commands + +@noindent +@pindex calc +@pindex calc-mode +@cindex Starting the Calculator +@cindex Running the Calculator +To start the Calculator in its standard interface, type @kbd{M-x calc}. +By default this creates a pair of small windows, @samp{*Calculator*} +and @samp{*Calc Trail*}. The former displays the contents of the +Calculator stack and is manipulated exclusively through Calc commands. +It is possible (though not usually necessary) to create several Calc +Mode buffers each of which has an independent stack, undo list, and +mode settings. There is exactly one Calc Trail buffer; it records a +list of the results of all calculations that have been done. The +Calc Trail buffer uses a variant of Calc Mode, so Calculator commands +still work when the trail buffer's window is selected. It is possible +to turn the trail window off, but the @samp{*Calc Trail*} buffer itself +still exists and is updated silently. @xref{Trail Commands}.@refill + +@kindex M-# c +@kindex M-# M-# +@c @mindex @null +@kindex M-# # +In most installations, the @kbd{M-# c} key sequence is a more +convenient way to start the Calculator. Also, @kbd{M-# M-#} and +@kbd{M-# #} are synonyms for @kbd{M-# c} unless you last used Calc +in its ``keypad'' mode. + +@kindex x +@kindex M-x +@pindex calc-execute-extended-command +Most Calc commands use one or two keystrokes. Lower- and upper-case +letters are distinct. Commands may also be entered in full @kbd{M-x} form; +for some commands this is the only form. As a convenience, the @kbd{x} +key (@code{calc-execute-extended-command}) +is like @kbd{M-x} except that it enters the initial string @samp{calc-} +for you. For example, the following key sequences are equivalent: +@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}.@refill + +@cindex Extensions module +@cindex @file{calc-ext} module +The Calculator exists in many parts. When you type @kbd{M-# c}, the +Emacs ``auto-load'' mechanism will bring in only the first part, which +contains the basic arithmetic functions. The other parts will be +auto-loaded the first time you use the more advanced commands like trig +functions or matrix operations. This is done to improve the response time +of the Calculator in the common case when all you need to do is a +little arithmetic. If for some reason the Calculator fails to load an +extension module automatically, you can force it to load all the +extensions by using the @kbd{M-# L} (@code{calc-load-everything}) +command. @xref{Mode Settings}.@refill + +If you type @kbd{M-x calc} or @kbd{M-# c} with any numeric prefix argument, +the Calculator is loaded if necessary, but it is not actually started. +If the argument is positive, the @file{calc-ext} extensions are also +loaded if necessary. User-written Lisp code that wishes to make use +of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)} +to auto-load the Calculator.@refill + +@kindex M-# b +@pindex full-calc +If you type @kbd{M-# b}, then next time you use @kbd{M-# c} you +will get a Calculator that uses the full height of the Emacs screen. +When full-screen mode is on, @kbd{M-# c} runs the @code{full-calc} +command instead of @code{calc}. From the Unix shell you can type +@samp{emacs -f full-calc} to start a new Emacs specifically for use +as a calculator. When Calc is started from the Emacs command line +like this, Calc's normal ``quit'' commands actually quit Emacs itself. + +@kindex M-# o +@pindex calc-other-window +The @kbd{M-# o} command is like @kbd{M-# c} except that the Calc +window is not actually selected. If you are already in the Calc +window, @kbd{M-# o} switches you out of it. (The regular Emacs +@kbd{C-x o} command would also work for this, but it has a +tendency to drop you into the Calc Trail window instead, which +@kbd{M-# o} takes care not to do.) + +@c @mindex M-# q +For one quick calculation, you can type @kbd{M-# q} (@code{quick-calc}) +which prompts you for a formula (like @samp{2+3/4}). The result is +displayed at the bottom of the Emacs screen without ever creating +any special Calculator windows. @xref{Quick Calculator}. + +@c @mindex M-# k +Finally, if you are using the X window system you may want to try +@kbd{M-# k} (@code{calc-keypad}) which runs Calc with a +``calculator keypad'' picture as well as a stack display. Click on +the keys with the mouse to operate the calculator. @xref{Keypad Mode}. + +@kindex q +@pindex calc-quit +@cindex Quitting the Calculator +@cindex Exiting the Calculator +The @kbd{q} key (@code{calc-quit}) exits Calc Mode and closes the +Calculator's window(s). It does not delete the Calculator buffers. +If you type @kbd{M-x calc} again, the Calculator will reappear with the +contents of the stack intact. Typing @kbd{M-# c} or @kbd{M-# M-#} +again from inside the Calculator buffer is equivalent to executing +@code{calc-quit}; you can think of @kbd{M-# M-#} as toggling the +Calculator on and off.@refill + +@kindex M-# x +The @kbd{M-# x} command also turns the Calculator off, no matter which +user interface (standard, Keypad, or Embedded) is currently active. +It also cancels @code{calc-edit} mode if used from there. + +@kindex d SPC +@pindex calc-refresh +@cindex Refreshing a garbled display +@cindex Garbled displays, refreshing +The @kbd{d SPC} key sequence (@code{calc-refresh}) redraws the contents +of the Calculator buffer from memory. Use this if the contents of the +buffer have been damaged somehow. + +@c @mindex o +The @kbd{o} key (@code{calc-realign}) moves the cursor back to its +``home'' position at the bottom of the Calculator buffer. + +@kindex < +@kindex > +@pindex calc-scroll-left +@pindex calc-scroll-right +@cindex Horizontal scrolling +@cindex Scrolling +@cindex Wide text, scrolling +The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and +@code{calc-scroll-right}. These are just like the normal horizontal +scrolling commands except that they scroll one half-screen at a time by +default. (Calc formats its output to fit within the bounds of the +window whenever it can.)@refill + +@kindex @{ +@kindex @} +@pindex calc-scroll-down +@pindex calc-scroll-up +@cindex Vertical scrolling +The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down} +and @code{calc-scroll-up}. They scroll up or down by one-half the +height of the Calc window.@refill + +@kindex M-# 0 +@pindex calc-reset +The @kbd{M-# 0} command (@code{calc-reset}; that's @kbd{M-#} followed +by a zero) resets the Calculator to its default state. This clears +the stack, resets all the modes, clears the caches (@pxref{Caches}), +and so on. (It does @emph{not} erase the values of any variables.) +With a numeric prefix argument, @kbd{M-# 0} preserves the contents +of the stack but resets everything else. + +@pindex calc-version +The @kbd{M-x calc-version} command displays the current version number +of Calc and the name of the person who installed it on your system. +(This information is also present in the @samp{*Calc Trail*} buffer, +and in the output of the @kbd{h h} command.) + +@node Help Commands, Stack Basics, Basic Commands, Introduction +@section Help Commands + +@noindent +@cindex Help commands +@kindex ? +@pindex calc-help +The @kbd{?} key (@code{calc-help}) displays a series of brief help messages. +Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs' +@key{ESC} and @kbd{C-x} prefixes. You can type +@kbd{?} after a prefix to see a list of commands beginning with that +prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again +to see additional commands for that prefix.) + +@kindex h h +@pindex calc-full-help +The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?} +responses at once. When printed, this makes a nice, compact (three pages) +summary of Calc keystrokes. + +In general, the @kbd{h} key prefix introduces various commands that +provide help within Calc. Many of the @kbd{h} key functions are +Calc-specific analogues to the @kbd{C-h} functions for Emacs help. + +@kindex h i +@kindex M-# i +@kindex i +@pindex calc-info +The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system +to read this manual on-line. This is basically the same as typing +@kbd{C-h i} (the regular way to run the Info system), then, if Info +is not already in the Calc manual, selecting the beginning of the +manual. The @kbd{M-# i} command is another way to read the Calc +manual; it is different from @kbd{h i} in that it works any time, +not just inside Calc. The plain @kbd{i} key is also equivalent to +@kbd{h i}, though this key is obsolete and may be replaced with a +different command in a future version of Calc. + +@kindex h t +@kindex M-# t +@pindex calc-tutorial +The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on +the Tutorial section of the Calc manual. It is like @kbd{h i}, +except that it selects the starting node of the tutorial rather +than the beginning of the whole manual. (It actually selects the +node ``Interactive Tutorial'' which tells a few things about +using the Info system before going on to the actual tutorial.) +The @kbd{M-# t} key is equivalent to @kbd{h t} (but it works at +all times). + +@kindex h s +@kindex M-# s +@pindex calc-info-summary +The @kbd{h s} (@code{calc-info-summary}) command runs the Info system +on the Summary node of the Calc manual. @xref{Summary}. The @kbd{M-# s} +key is equivalent to @kbd{h s}. + +@kindex h k +@pindex calc-describe-key +The @kbd{h k} (@code{calc-describe-key}) command looks up a key +sequence in the Calc manual. For example, @kbd{h k H a S} looks +up the documentation on the @kbd{H a S} (@code{calc-solve-for}) +command. This works by looking up the textual description of +the key(s) in the Key Index of the manual, then jumping to the +node indicated by the index. + +Most Calc commands do not have traditional Emacs documentation +strings, since the @kbd{h k} command is both more convenient and +more instructive. This means the regular Emacs @kbd{C-h k} +(@code{describe-key}) command will not be useful for Calc keystrokes. + +@kindex h c +@pindex calc-describe-key-briefly +The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a +key sequence and displays a brief one-line description of it at +the bottom of the screen. It looks for the key sequence in the +Summary node of the Calc manual; if it doesn't find the sequence +there, it acts just like its regular Emacs counterpart @kbd{C-h c} +(@code{describe-key-briefly}). For example, @kbd{h c H a S} +gives the description: + +@smallexample +H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes) +@end smallexample + +@noindent +which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for} +takes a value @cite{a} from the stack, prompts for a value @cite{v}, +then applies the algebraic function @code{fsolve} to these values. +The @samp{?=notes} message means you can now type @kbd{?} to see +additional notes from the summary that apply to this command. + +@kindex h f +@pindex calc-describe-function +The @kbd{h f} (@code{calc-describe-function}) command looks up an +algebraic function or a command name in the Calc manual. The +prompt initially contains @samp{calcFunc-}; follow this with an +algebraic function name to look up that function in the Function +Index. Or, backspace and enter a command name beginning with +@samp{calc-} to look it up in the Command Index. This command +will also look up operator symbols that can appear in algebraic +formulas, like @samp{%} and @samp{=>}. + +@kindex h v +@pindex calc-describe-variable +The @kbd{h v} (@code{calc-describe-variable}) command looks up a +variable in the Calc manual. The prompt initially contains the +@samp{var-} prefix; just add a variable name like @code{pi} or +@code{PlotRejects}. + +@kindex h b +@pindex describe-bindings +The @kbd{h b} (@code{calc-describe-bindings}) command is just like +@kbd{C-h b}, except that only local (Calc-related) key bindings are +listed. + +@kindex h n +The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays +the ``news'' or change history of Calc. This is kept in the file +@file{README}, which Calc looks for in the same directory as the Calc +source files. + +@kindex h C-c +@kindex h C-d +@kindex h C-w +The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying, +distribution, and warranty information about Calc. These work by +pulling up the appropriate parts of the ``Copying'' or ``Reporting +Bugs'' sections of the manual. + +@node Stack Basics, Numeric Entry, Help Commands, Introduction +@section Stack Basics + +@noindent +@cindex Stack basics +@c [fix-tut RPN Calculations and the Stack] +Calc uses RPN notation. If you are not familar with RPN, @pxref{RPN +Tutorial}. + +To add the numbers 1 and 2 in Calc you would type the keys: +@kbd{1 @key{RET} 2 +}. +(@key{RET} corresponds to the @key{ENTER} key on most calculators.) +The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The +@kbd{+} key always ``pops'' the top two numbers from the stack, adds them, +and pushes the result (3) back onto the stack. This number is ready for +further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the +3 and 5, subtracts them, and pushes the result (@i{-2}).@refill + +Note that the ``top'' of the stack actually appears at the @emph{bottom} +of the buffer. A line containing a single @samp{.} character signifies +the end of the buffer; Calculator commands operate on the number(s) +directly above this line. The @kbd{d t} (@code{calc-truncate-stack}) +command allows you to move the @samp{.} marker up and down in the stack; +@pxref{Truncating the Stack}. + +@kindex d l +@pindex calc-line-numbering +Stack elements are numbered consecutively, with number 1 being the top of +the stack. These line numbers are ordinarily displayed on the lefthand side +of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls +whether these numbers appear. (Line numbers may be turned off since they +slow the Calculator down a bit and also clutter the display.) + +@kindex o +@pindex calc-realign +The unshifted letter @kbd{o} (@code{calc-realign}) command repositions +the cursor to its top-of-stack ``home'' position. It also undoes any +horizontal scrolling in the window. If you give it a numeric prefix +argument, it instead moves the cursor to the specified stack element. + +The @key{RET} (or equivalent @key{SPC}) key is only required to separate +two consecutive numbers. +(After all, if you typed @kbd{1 2} by themselves the Calculator +would enter the number 12.) If you press @kbd{RET} or @kbd{SPC} @emph{not} +right after typing a number, the key duplicates the number on the top of +the stack. @kbd{@key{RET} *} is thus a handy way to square a number.@refill + +The @key{DEL} key pops and throws away the top number on the stack. +The @key{TAB} key swaps the top two objects on the stack. +@xref{Stack and Trail}, for descriptions of these and other stack-related +commands.@refill + +@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction +@section Numeric Entry + +@noindent +@kindex 0-9 +@kindex . +@kindex e +@cindex Numeric entry +@cindex Entering numbers +Pressing a digit or other numeric key begins numeric entry using the +minibuffer. The number is pushed on the stack when you press the @key{RET} +or @key{SPC} keys. If you press any other non-numeric key, the number is +pushed onto the stack and the appropriate operation is performed. If +you press a numeric key which is not valid, the key is ignored. + +@cindex Minus signs +@cindex Negative numbers, entering +@kindex _ +There are three different concepts corresponding to the word ``minus,'' +typified by @cite{a-b} (subtraction), @cite{-x} +(change-sign), and @cite{-5} (negative number). Calc uses three +different keys for these operations, respectively: +@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts +the two numbers on the top of the stack. The @kbd{n} key changes the sign +of the number on the top of the stack or the number currently being entered. +The @kbd{_} key begins entry of a negative number or changes the sign of +the number currently being entered. The following sequences all enter the +number @i{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}}, +@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}.@refill + +Some other keys are active during numeric entry, such as @kbd{#} for +non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms. +These notations are described later in this manual with the corresponding +data types. @xref{Data Types}. + +During numeric entry, the only editing key available is @kbd{DEL}. + +@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction +@section Algebraic Entry + +@noindent +@kindex ' +@pindex calc-algebraic-entry +@cindex Algebraic notation +@cindex Formulas, entering +Calculations can also be entered in algebraic form. This is accomplished +by typing the apostrophe key, @kbd{'}, followed by the expression in +standard format: @kbd{@key{'} 2+3*4 @key{RET}} computes +@c{$2+(3\times4) = 14$} +@cite{2+(3*4) = 14} and pushes that on the stack. If you wish you can +ignore the RPN aspect of Calc altogether and simply enter algebraic +expressions in this way. You may want to use @key{DEL} every so often to +clear previous results off the stack.@refill + +You can press the apostrophe key during normal numeric entry to switch +the half-entered number into algebraic entry mode. One reason to do this +would be to use the full Emacs cursor motion and editing keys, which are +available during algebraic entry but not during numeric entry. + +In the same vein, during either numeric or algebraic entry you can +press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where +you complete your half-finished entry in a separate buffer. +@xref{Editing Stack Entries}. + +@kindex m a +@pindex calc-algebraic-mode +@cindex Algebraic mode +If you prefer algebraic entry, you can use the command @kbd{m a} +(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode, +digits and other keys that would normally start numeric entry instead +start full algebraic entry; as long as your formula begins with a digit +you can omit the apostrophe. Open parentheses and square brackets also +begin algebraic entry. You can still do RPN calculations in this mode, +but you will have to press @key{RET} to terminate every number: +@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same +thing as @kbd{2*3+4 @key{RET}}.@refill + +@cindex Incomplete algebraic mode +If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a} +command, it enables Incomplete Algebraic mode; this is like regular +Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys +only. Numeric keys still begin a numeric entry in this mode. + +@kindex m t +@pindex calc-total-algebraic-mode +@cindex Total algebraic mode +The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even +stronger algebraic-entry mode, in which @emph{all} regular letter and +punctuation keys begin algebraic entry. Use this if you prefer typing +@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of +@kbd{a f}, and so on. To type regular Calc commands when you are in +``total'' algebraic mode, hold down the @key{META} key. Thus @kbd{M-q} +is the command to quit Calc, @kbd{M-p} sets the precision, and +@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns total algebraic +mode back off again. Meta keys also terminate algebraic entry, so +that @kbd{2+3 M-S} is equivalent to @kbd{2+3 RET M-S}. The symbol +@samp{Alg*} will appear in the mode line whenever you are in this mode. + +Pressing @kbd{'} (the apostrophe) a second time re-enters the previous +algebraic formula. You can then use the normal Emacs editing keys to +modify this formula to your liking before pressing @key{RET}. + +@kindex $ +@cindex Formulas, referring to stack +Within a formula entered from the keyboard, the symbol @kbd{$} +represents the number on the top of the stack. If an entered formula +contains any @kbd{$} characters, the Calculator replaces the top of +stack with that formula rather than simply pushing the formula onto the +stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2 +@key{RET}} replaces it with 6. Note that the @kbd{$} key always +initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the +first character in the new formula.@refill + +Higher stack elements can be accessed from an entered formula with the +symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements +removed (to be replaced by the entered values) equals the number of dollar +signs in the longest such symbol in the formula. For example, @samp{$$+$$$} +adds the second and third stack elements, replacing the top three elements +with the answer. (All information about the top stack element is thus lost +since no single @samp{$} appears in this formula.)@refill + +A slightly different way to refer to stack elements is with a dollar +sign followed by a number: @samp{$1}, @samp{$2}, and so on are much +like @samp{$}, @samp{$$}, etc., except that stack entries referred +to numerically are not replaced by the algebraic entry. That is, while +@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5 +on the stack and pushes an additional 6. + +If a sequence of formulas are entered separated by commas, each formula +is pushed onto the stack in turn. For example, @samp{1,2,3} pushes +those three numbers onto the stack (leaving the 3 at the top), and +@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also, +@samp{$,$$} exchanges the top two elements of the stack, just like the +@key{TAB} key. + +You can finish an algebraic entry with @kbd{M-=} or @kbd{M-RET} instead +of @key{RET}. This uses @kbd{=} to evaluate the variables in each +formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes +the variable @samp{pi}, but @kbd{' pi M-RET} pushes 3.1415.) + +If you finish your algebraic entry by pressing @kbd{LFD} (or @kbd{C-j}) +instead of @key{RET}, Calc disables the default simplifications +(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry +is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3 +on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @cite{1+2}; +you might then press @kbd{=} when it is time to evaluate this formula. + +@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction +@section ``Quick Calculator'' Mode + +@noindent +@kindex M-# q +@pindex quick-calc +@cindex Quick Calculator +There is another way to invoke the Calculator if all you need to do +is make one or two quick calculations. Type @kbd{M-# q} (or +@kbd{M-x quick-calc}), then type any formula as an algebraic entry. +The Calculator will compute the result and display it in the echo +area, without ever actually putting up a Calc window. + +You can use the @kbd{$} character in a Quick Calculator formula to +refer to the previous Quick Calculator result. Older results are +not retained; the Quick Calculator has no effect on the full +Calculator's stack or trail. If you compute a result and then +forget what it was, just run @code{M-# q} again and enter +@samp{$} as the formula. + +If this is the first time you have used the Calculator in this Emacs +session, the @kbd{M-# q} command will create the @code{*Calculator*} +buffer and perform all the usual initializations; it simply will +refrain from putting that buffer up in a new window. The Quick +Calculator refers to the @code{*Calculator*} buffer for all mode +settings. Thus, for example, to set the precision that the Quick +Calculator uses, simply run the full Calculator momentarily and use +the regular @kbd{p} command. + +If you use @code{M-# q} from inside the Calculator buffer, the +effect is the same as pressing the apostrophe key (algebraic entry). + +The result of a Quick calculation is placed in the Emacs ``kill ring'' +as well as being displayed. A subsequent @kbd{C-y} command will +yank the result into the editing buffer. You can also use this +to yank the result into the next @kbd{M-# q} input line as a more +explicit alternative to @kbd{$} notation, or to yank the result +into the Calculator stack after typing @kbd{M-# c}. + +If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead +of @key{RET}, the result is inserted immediately into the current +buffer rather than going into the kill ring. + +Quick Calculator results are actually evaluated as if by the @kbd{=} +key (which replaces variable names by their stored values, if any). +If the formula you enter is an assignment to a variable using the +@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1}, +then the result of the evaluation is stored in that Calc variable. +@xref{Store and Recall}. + +If the result is an integer and the current display radix is decimal, +the number will also be displayed in hex and octal formats. If the +integer is in the range from 1 to 126, it will also be displayed as +an ASCII character. + +For example, the quoted character @samp{"x"} produces the vector +result @samp{[120]} (because 120 is the ASCII code of the lower-case +`x'; @pxref{Strings}). Since this is a vector, not an integer, it +is displayed only according to the current mode settings. But +running Quick Calc again and entering @samp{120} will produce the +result @samp{120 (16#78, 8#170, x)} which shows the number in its +decimal, hexadecimal, octal, and ASCII forms. + +Please note that the Quick Calculator is not any faster at loading +or computing the answer than the full Calculator; the name ``quick'' +merely refers to the fact that it's much less hassle to use for +small calculations. + +@node Prefix Arguments, Undo, Quick Calculator, Introduction +@section Numeric Prefix Arguments + +@noindent +Many Calculator commands use numeric prefix arguments. Some, such as +@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of +the prefix argument or use a default if you don't use a prefix. +Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument +and prompt for a number if you don't give one as a prefix.@refill + +As a rule, stack-manipulation commands accept a numeric prefix argument +which is interpreted as an index into the stack. A positive argument +operates on the top @var{n} stack entries; a negative argument operates +on the @var{n}th stack entry in isolation; and a zero argument operates +on the entire stack. + +Most commands that perform computations (such as the arithmetic and +scientific functions) accept a numeric prefix argument that allows the +operation to be applied across many stack elements. For unary operations +(that is, functions of one argument like absolute value or complex +conjugate), a positive prefix argument applies that function to the top +@var{n} stack entries simultaneously, and a negative argument applies it +to the @var{n}th stack entry only. For binary operations (functions of +two arguments like addition, GCD, and vector concatenation), a positive +prefix argument ``reduces'' the function across the top @var{n} +stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries; +@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top +@var{n} stack elements with the top stack element as a second argument +(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements). +This feature is not available for operations which use the numeric prefix +argument for some other purpose. + +Numeric prefixes are specified the same way as always in Emacs: Press +a sequence of @key{META}-digits, or press @key{ESC} followed by digits, +or press @kbd{C-u} followed by digits. Some commands treat plain +@kbd{C-u} (without any actual digits) specially.@refill + +@kindex ~ +@pindex calc-num-prefix +You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the +top of the stack and enter it as the numeric prefix for the next command. +For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate +(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2 +to the fourth power and set the precision to that value.@refill + +Conversely, if you have typed a numeric prefix argument the @kbd{~} key +pushes it onto the stack in the form of an integer. + +@node Undo, Error Messages, Prefix Arguments, Introduction +@section Undoing Mistakes + +@noindent +@kindex U +@kindex C-_ +@pindex calc-undo +@cindex Mistakes, undoing +@cindex Undoing mistakes +@cindex Errors, undoing +The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation. +If that operation added or dropped objects from the stack, those objects +are removed or restored. If it was a ``store'' operation, you are +queried whether or not to restore the variable to its original value. +The @kbd{U} key may be pressed any number of times to undo successively +farther back in time; with a numeric prefix argument it undoes a +specified number of operations. The undo history is cleared only by the +@kbd{q} (@code{calc-quit}) command. (Recall that @kbd{M-# c} is +synonymous with @code{calc-quit} while inside the Calculator; this +also clears the undo history.) + +Currently the mode-setting commands (like @code{calc-precision}) are not +undoable. You can undo past a point where you changed a mode, but you +will need to reset the mode yourself. + +@kindex D +@pindex calc-redo +@cindex Redoing after an Undo +The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was +mistakenly undone. Pressing @kbd{U} with a negative prefix argument is +equivalent to executing @code{calc-redo}. You can redo any number of +times, up to the number of recent consecutive undo commands. Redo +information is cleared whenever you give any command that adds new undo +information, i.e., if you undo, then enter a number on the stack or make +any other change, then it will be too late to redo. + +@kindex M-RET +@pindex calc-last-args +@cindex Last-arguments feature +@cindex Arguments, restoring +The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that +it restores the arguments of the most recent command onto the stack; +however, it does not remove the result of that command. Given a numeric +prefix argument, this command applies to the @cite{n}th most recent +command which removed items from the stack; it pushes those items back +onto the stack. + +The @kbd{K} (@code{calc-keep-args}) command provides a related function +to @kbd{M-@key{RET}}. @xref{Stack and Trail}. + +It is also possible to recall previous results or inputs using the trail. +@xref{Trail Commands}. + +The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}. + +@node Error Messages, Multiple Calculators, Undo, Introduction +@section Error Messages + +@noindent +@kindex w +@pindex calc-why +@cindex Errors, messages +@cindex Why did an error occur? +Many situations that would produce an error message in other calculators +simply create unsimplified formulas in the Emacs Calculator. For example, +@kbd{1 @key{RET} 0 /} pushes the formula @cite{1 / 0}; @w{@kbd{0 L}} pushes +the formula @samp{ln(0)}. Floating-point overflow and underflow are also +reasons for this to happen. + +When a function call must be left in symbolic form, Calc usually +produces a message explaining why. Messages that are probably +surprising or indicative of user errors are displayed automatically. +Other messages are simply kept in Calc's memory and are displayed only +if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if +the same computation results in several messages. (The first message +will end with @samp{[w=more]} in this case.) + +@kindex d w +@pindex calc-auto-why +The @kbd{d w} (@code{calc-auto-why}) command controls when error messages +are displayed automatically. (Calc effectively presses @kbd{w} for you +after your computation finishes.) By default, this occurs only for +``important'' messages. The other possible modes are to report +@emph{all} messages automatically, or to report none automatically (so +that you must always press @kbd{w} yourself to see the messages). + +@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction +@section Multiple Calculators + +@noindent +@pindex another-calc +It is possible to have any number of Calc Mode buffers at once. +Usually this is done by executing @kbd{M-x another-calc}, which +is similar to @kbd{M-# c} except that if a @samp{*Calculator*} +buffer already exists, a new, independent one with a name of the +form @samp{*Calculator*<@var{n}>} is created. You can also use the +command @code{calc-mode} to put any buffer into Calculator mode, but +this would ordinarily never be done. + +The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer; +it only closes its window. Use @kbd{M-x kill-buffer} to destroy a +Calculator buffer. + +Each Calculator buffer keeps its own stack, undo list, and mode settings +such as precision, angular mode, and display formats. In Emacs terms, +variables such as @code{calc-stack} are buffer-local variables. The +global default values of these variables are used only when a new +Calculator buffer is created. The @code{calc-quit} command saves +the stack and mode settings of the buffer being quit as the new defaults. + +There is only one trail buffer, @samp{*Calc Trail*}, used by all +Calculator buffers. + +@node Troubleshooting Commands, , Multiple Calculators, Introduction +@section Troubleshooting Commands + +@noindent +This section describes commands you can use in case a computation +incorrectly fails or gives the wrong answer. + +@xref{Reporting Bugs}, if you find a problem that appears to be due +to a bug or deficiency in Calc. + +@menu +* Autoloading Problems:: +* Recursion Depth:: +* Caches:: +* Debugging Calc:: +@end menu + +@node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands +@subsection Autoloading Problems + +@noindent +The Calc program is split into many component files; components are +loaded automatically as you use various commands that require them. +Occasionally Calc may lose track of when a certain component is +necessary; typically this means you will type a command and it won't +work because some function you've never heard of was undefined. + +@kindex M-# L +@pindex calc-load-everything +If this happens, the easiest workaround is to type @kbd{M-# L} +(@code{calc-load-everything}) to force all the parts of Calc to be +loaded right away. This will cause Emacs to take up a lot more +memory than it would otherwise, but it's guaranteed to fix the problem. + +If you seem to run into this problem no matter what you do, or if +even the @kbd{M-# L} command crashes, Calc may have been improperly +installed. @xref{Installation}, for details of the installation +process. + +@node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands +@subsection Recursion Depth + +@noindent +@kindex M +@kindex I M +@pindex calc-more-recursion-depth +@pindex calc-less-recursion-depth +@cindex Recursion depth +@cindex ``Computation got stuck'' message +@cindex @code{max-lisp-eval-depth} +@cindex @code{max-specpdl-size} +Calc uses recursion in many of its calculations. Emacs Lisp keeps a +variable @code{max-lisp-eval-depth} which limits the amount of recursion +possible in an attempt to recover from program bugs. If a calculation +ever halts incorrectly with the message ``Computation got stuck or +ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth}) +to increase this limit. (Of course, this will not help if the +calculation really did get stuck due to some problem inside Calc.)@refill + +The limit is always increased (multiplied) by a factor of two. There +is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which +decreases this limit by a factor of two, down to a minimum value of 200. +The default value is 1000. + +These commands also double or halve @code{max-specpdl-size}, another +internal Lisp recursion limit. The minimum value for this limit is 600. + +@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands +@subsection Caches + +@noindent +@cindex Caches +@cindex Flushing caches +Calc saves certain values after they have been computed once. For +example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the +constant @c{$\pi$} +@cite{pi} to about 20 decimal places; if the current precision +is greater than this, it will recompute @c{$\pi$} +@cite{pi} using a series +approximation. This value will not need to be recomputed ever again +unless you raise the precision still further. Many operations such as +logarithms and sines make use of similarly cached values such as +@c{$\pi \over 4$} +@cite{pi/4} and @c{$\ln 2$} +@cite{ln(2)}. The visible effect of caching is that +high-precision computations may seem to do extra work the first time. +Other things cached include powers of two (for the binary arithmetic +functions), matrix inverses and determinants, symbolic integrals, and +data points computed by the graphing commands. + +@pindex calc-flush-caches +If you suspect a Calculator cache has become corrupt, you can use the +@code{calc-flush-caches} command to reset all caches to the empty state. +(This should only be necessary in the event of bugs in the Calculator.) +The @kbd{M-# 0} (with the zero key) command also resets caches along +with all other aspects of the Calculator's state. + +@node Debugging Calc, , Caches, Troubleshooting Commands +@subsection Debugging Calc + +@noindent +A few commands exist to help in the debugging of Calc commands. +@xref{Programming}, to see the various ways that you can write +your own Calc commands. + +@kindex Z T +@pindex calc-timing +The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode +in which the timing of slow commands is reported in the Trail. +Any Calc command that takes two seconds or longer writes a line +to the Trail showing how many seconds it took. This value is +accurate only to within one second. + +All steps of executing a command are included; in particular, time +taken to format the result for display in the stack and trail is +counted. Some prompts also count time taken waiting for them to +be answered, while others do not; this depends on the exact +implementation of the command. For best results, if you are timing +a sequence that includes prompts or multiple commands, define a +keyboard macro to run the whole sequence at once. Calc's @kbd{X} +command (@pxref{Keyboard Macros}) will then report the time taken +to execute the whole macro. + +Another advantage of the @kbd{X} command is that while it is +executing, the stack and trail are not updated from step to step. +So if you expect the output of your test sequence to leave a result +that may take a long time to format and you don't wish to count +this formatting time, end your sequence with a @key{DEL} keystroke +to clear the result from the stack. When you run the sequence with +@kbd{X}, Calc will never bother to format the large result. + +Another thing @kbd{Z T} does is to increase the Emacs variable +@code{gc-cons-threshold} to a much higher value (two million; the +usual default in Calc is 250,000) for the duration of each command. +This generally prevents garbage collection during the timing of +the command, though it may cause your Emacs process to grow +abnormally large. (Garbage collection time is a major unpredictable +factor in the timing of Emacs operations.) + +Another command that is useful when debugging your own Lisp +extensions to Calc is @kbd{M-x calc-pass-errors}, which disables +the error handler that changes the ``@code{max-lisp-eval-depth} +exceeded'' message to the much more friendly ``Computation got +stuck or ran too long.'' This handler interferes with the Emacs +Lisp debugger's @code{debug-on-error} mode. Errors are reported +in the handler itself rather than at the true location of the +error. After you have executed @code{calc-pass-errors}, Lisp +errors will be reported correctly but the user-friendly message +will be lost. + +@node Data Types, Stack and Trail, Introduction, Top +@chapter Data Types + +@noindent +This chapter discusses the various types of objects that can be placed +on the Calculator stack, how they are displayed, and how they are +entered. (@xref{Data Type Formats}, for information on how these data +types are represented as underlying Lisp objects.)@refill + +Integers, fractions, and floats are various ways of describing real +numbers. HMS forms also for many purposes act as real numbers. These +types can be combined to form complex numbers, modulo forms, error forms, +or interval forms. (But these last four types cannot be combined +arbitrarily:@: error forms may not contain modulo forms, for example.) +Finally, all these types of numbers may be combined into vectors, +matrices, or algebraic formulas. + +@menu +* Integers:: The most basic data type. +* Fractions:: This and above are called @dfn{rationals}. +* Floats:: This and above are called @dfn{reals}. +* Complex Numbers:: This and above are called @dfn{numbers}. +* Infinities:: +* Vectors and Matrices:: +* Strings:: +* HMS Forms:: +* Date Forms:: +* Modulo Forms:: +* Error Forms:: +* Interval Forms:: +* Incomplete Objects:: +* Variables:: +* Formulas:: +@end menu + +@node Integers, Fractions, Data Types, Data Types +@section Integers + +@noindent +@cindex Integers +The Calculator stores integers to arbitrary precision. Addition, +subtraction, and multiplication of integers always yields an exact +integer result. (If the result of a division or exponentiation of +integers is not an integer, it is expressed in fractional or +floating-point form according to the current Fraction Mode. +@xref{Fraction Mode}.) + +A decimal integer is represented as an optional sign followed by a +sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to +insert a comma at every third digit for display purposes, but you +must not type commas during the entry of numbers.@refill + +@kindex # +A non-decimal integer is represented as an optional sign, a radix +between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11 +and above, the letters A through Z (upper- or lower-case) count as +digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how +to set the default radix for display of integers. Numbers of any radix +may be entered at any time. If you press @kbd{#} at the beginning of a +number, the current display radix is used.@refill + +@node Fractions, Floats, Integers, Data Types +@section Fractions + +@noindent +@cindex Fractions +A @dfn{fraction} is a ratio of two integers. Fractions are traditionally +written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key +performs RPN division; the following two sequences push the number +@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /} +assuming Fraction Mode has been enabled.) +When the Calculator produces a fractional result it always reduces it to +simplest form, which may in fact be an integer.@refill + +Fractions may also be entered in a three-part form, where @samp{2:3:4} +represents two-and-three-quarters. @xref{Fraction Formats}, for fraction +display formats.@refill + +Non-decimal fractions are entered and displayed as +@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part +form). The numerator and denominator always use the same radix.@refill + +@node Floats, Complex Numbers, Fractions, Data Types +@section Floats + +@noindent +@cindex Floating-point numbers +A floating-point number or @dfn{float} is a number stored in scientific +notation. The number of significant digits in the fractional part is +governed by the current floating precision (@pxref{Precision}). The +range of acceptable values is from @c{$10^{-3999999}$} +@cite{10^-3999999} (inclusive) +to @c{$10^{4000000}$} +@cite{10^4000000} +(exclusive), plus the corresponding negative +values and zero. + +Calculations that would exceed the allowable range of values (such +as @samp{exp(exp(20))}) are left in symbolic form by Calc. The +messages ``floating-point overflow'' or ``floating-point underflow'' +indicate that during the calculation a number would have been produced +that was too large or too close to zero, respectively, to be represented +by Calc. This does not necessarily mean the final result would have +overflowed, just that an overflow occurred while computing the result. +(In fact, it could report an underflow even though the final result +would have overflowed!) + +If a rational number and a float are mixed in a calculation, the result +will in general be expressed as a float. Commands that require an integer +value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued +floats, i.e., floating-point numbers with nothing after the decimal point. + +Floats are identified by the presence of a decimal point and/or an +exponent. In general a float consists of an optional sign, digits +including an optional decimal point, and an optional exponent consisting +of an @samp{e}, an optional sign, and up to seven exponent digits. +For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power, +or 0.235. + +Floating-point numbers are normally displayed in decimal notation with +all significant figures shown. Exceedingly large or small numbers are +displayed in scientific notation. Various other display options are +available. @xref{Float Formats}. + +@cindex Accuracy of calculations +Floating-point numbers are stored in decimal, not binary. The result +of each operation is rounded to the nearest value representable in the +number of significant digits specified by the current precision, +rounding away from zero in the case of a tie. Thus (in the default +display mode) what you see is exactly what you get. Some operations such +as square roots and transcendental functions are performed with several +digits of extra precision and then rounded down, in an effort to make the +final result accurate to the full requested precision. However, +accuracy is not rigorously guaranteed. If you suspect the validity of a +result, try doing the same calculation in a higher precision. The +Calculator's arithmetic is not intended to be IEEE-conformant in any +way.@refill + +While floats are always @emph{stored} in decimal, they can be entered +and displayed in any radix just like integers and fractions. The +notation @samp{@var{radix}#@var{ddd}.@var{ddd}} is a floating-point +number whose digits are in the specified radix. Note that the @samp{.} +is more aptly referred to as a ``radix point'' than as a decimal +point in this case. The number @samp{8#123.4567} is defined as +@samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can use +@samp{e} notation to write a non-decimal number in scientific notation. +The exponent is written in decimal, and is considered to be a power +of the radix: @samp{8#1234567e-4}. If the radix is 15 or above, the +letter @samp{e} is a digit, so scientific notation must be written +out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the +Modes Tutorial explore some of the properties of non-decimal floats. + +@node Complex Numbers, Infinities, Floats, Data Types +@section Complex Numbers + +@noindent +@cindex Complex numbers +There are two supported formats for complex numbers: rectangular and +polar. The default format is rectangular, displayed in the form +@samp{(@var{real},@var{imag})} where @var{real} is the real part and +@var{imag} is the imaginary part, each of which may be any real number. +Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i} +notation; @pxref{Complex Formats}.@refill + +Polar complex numbers are displayed in the form `@t{(}@var{r}@t{;}@c{$\theta$} +@var{theta}@t{)}' +where @var{r} is the nonnegative magnitude and @c{$\theta$} +@var{theta} is the argument +or phase angle. The range of @c{$\theta$} +@var{theta} depends on the current angular +mode (@pxref{Angular Modes}); it is generally between @i{-180} and +@i{+180} degrees or the equivalent range in radians.@refill + +Complex numbers are entered in stages using incomplete objects. +@xref{Incomplete Objects}. + +Operations on rectangular complex numbers yield rectangular complex +results, and similarly for polar complex numbers. Where the two types +are mixed, or where new complex numbers arise (as for the square root of +a negative real), the current @dfn{Polar Mode} is used to determine the +type. @xref{Polar Mode}. + +A complex result in which the imaginary part is zero (or the phase angle +is 0 or 180 degrees or @c{$\pi$} +@cite{pi} radians) is automatically converted to a real +number. + +@node Infinities, Vectors and Matrices, Complex Numbers, Data Types +@section Infinities + +@noindent +@cindex Infinity +@cindex @code{inf} variable +@cindex @code{uinf} variable +@cindex @code{nan} variable +@vindex inf +@vindex uinf +@vindex nan +The word @code{inf} represents the mathematical concept of @dfn{infinity}. +Calc actually has three slightly different infinity-like values: +@code{inf}, @code{uinf}, and @code{nan}. These are just regular +variable names (@pxref{Variables}); you should avoid using these +names for your own variables because Calc gives them special +treatment. Infinities, like all variable names, are normally +entered using algebraic entry. + +Mathematically speaking, it is not rigorously correct to treat +``infinity'' as if it were a number, but mathematicians often do +so informally. When they say that @samp{1 / inf = 0}, what they +really mean is that @cite{1 / x}, as @cite{x} becomes larger and +larger, becomes arbitrarily close to zero. So you can imagine +that if @cite{x} got ``all the way to infinity,'' then @cite{1 / x} +would go all the way to zero. Similarly, when they say that +@samp{exp(inf) = inf}, they mean that @c{$e^x$} +@cite{exp(x)} grows without +bound as @cite{x} grows. The symbol @samp{-inf} likewise stands +for an infinitely negative real value; for example, we say that +@samp{exp(-inf) = 0}. You can have an infinity pointing in any +direction on the complex plane: @samp{sqrt(-inf) = i inf}. + +The same concept of limits can be used to define @cite{1 / 0}. We +really want the value that @cite{1 / x} approaches as @cite{x} +approaches zero. But if all we have is @cite{1 / 0}, we can't +tell which direction @cite{x} was coming from. If @cite{x} was +positive and decreasing toward zero, then we should say that +@samp{1 / 0 = inf}. But if @cite{x} was negative and increasing +toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @cite{x} +could be an imaginary number, giving the answer @samp{i inf} or +@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean +@dfn{undirected infinity}, i.e., a value which is infinitely +large but with an unknown sign (or direction on the complex plane). + +Calc actually has three modes that say how infinities are handled. +Normally, infinities never arise from calculations that didn't +already have them. Thus, @cite{1 / 0} is treated simply as an +error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode}) +command (@pxref{Infinite Mode}) enables a mode in which +@cite{1 / 0} evaluates to @code{uinf} instead. There is also +an alternative type of infinite mode which says to treat zeros +as if they were positive, so that @samp{1 / 0 = inf}. While this +is less mathematically correct, it may be the answer you want in +some cases. + +Since all infinities are ``as large'' as all others, Calc simplifies, +e.g., @samp{5 inf} to @samp{inf}. Another example is +@samp{5 - inf = -inf}, where the @samp{-inf} is so large that +adding a finite number like five to it does not affect it. +Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes +that variables like @code{a} always stand for finite quantities. +Just to show that infinities really are all the same size, +note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's +notation. + +It's not so easy to define certain formulas like @samp{0 * inf} and +@samp{inf / inf}. Depending on where these zeros and infinities +came from, the answer could be literally anything. The latter +formula could be the limit of @cite{x / x} (giving a result of one), +or @cite{2 x / x} (giving two), or @cite{x^2 / x} (giving @code{inf}), +or @cite{x / x^2} (giving zero). Calc uses the symbol @code{nan} +to represent such an @dfn{indeterminate} value. (The name ``nan'' +comes from analogy with the ``NAN'' concept of IEEE standard +arithmetic; it stands for ``Not A Number.'' This is somewhat of a +misnomer, since @code{nan} @emph{does} stand for some number or +infinity, it's just that @emph{which} number it stands for +cannot be determined.) In Calc's notation, @samp{0 * inf = nan} +and @samp{inf / inf = nan}. A few other common indeterminate +expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also, +@samp{0 / 0 = nan} if you have turned on ``infinite mode'' +(as described above). + +Infinities are especially useful as parts of @dfn{intervals}. +@xref{Interval Forms}. + +@node Vectors and Matrices, Strings, Infinities, Data Types +@section Vectors and Matrices + +@noindent +@cindex Vectors +@cindex Plain vectors +@cindex Matrices +The @dfn{vector} data type is flexible and general. A vector is simply a +list of zero or more data objects. When these objects are numbers, the +whole is a vector in the mathematical sense. When these objects are +themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}. +A vector which is not a matrix is referred to here as a @dfn{plain vector}. + +A vector is displayed as a list of values separated by commas and enclosed +in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by +3 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex +numbers, are entered as incomplete objects. @xref{Incomplete Objects}. +During algebraic entry, vectors are entered all at once in the usual +brackets-and-commas form. Matrices may be entered algebraically as nested +vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}}, +with rows separated by semicolons. The commas may usually be omitted +when entering vectors: @samp{[1 2 3]}. Curly braces may be used in +place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in +this case. + +Traditional vector and matrix arithmetic is also supported; +@pxref{Basic Arithmetic} and @pxref{Matrix Functions}. +Many other operations are applied to vectors element-wise. For example, +the complex conjugate of a vector is a vector of the complex conjugates +of its elements.@refill + +@c @starindex +@tindex vec +Algebraic functions for building vectors include @samp{vec(a, b, c)} +to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an @c{$n\times m$} +@asis{@var{n}x@var{m}} +matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers +from 1 to @samp{n}. + +@node Strings, HMS Forms, Vectors and Matrices, Data Types +@section Strings + +@noindent +@kindex " +@cindex Strings +@cindex Character strings +Character strings are not a special data type in the Calculator. +Rather, a string is represented simply as a vector all of whose +elements are integers in the range 0 to 255 (ASCII codes). You can +enter a string at any time by pressing the @kbd{"} key. Quotation +marks and backslashes are written @samp{\"} and @samp{\\}, respectively, +inside strings. Other notations introduced by backslashes are: + +@group +@example +\a 7 \^@@ 0 +\b 8 \^a-z 1-26 +\e 27 \^[ 27 +\f 12 \^\\ 28 +\n 10 \^] 29 +\r 13 \^^ 30 +\t 9 \^_ 31 + \^? 127 +@end example +@end group + +@noindent +Finally, a backslash followed by three octal digits produces any +character from its ASCII code. + +@kindex d " +@pindex calc-display-strings +Strings are normally displayed in vector-of-integers form. The +@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in +which any vectors of small integers are displayed as quoted strings +instead. + +The backslash notations shown above are also used for displaying +strings. Characters 128 and above are not translated by Calc; unless +you have an Emacs modified for 8-bit fonts, these will show up in +backslash-octal-digits notation. For characters below 32, and +for character 127, Calc uses the backslash-letter combination if +there is one, or otherwise uses a @samp{\^} sequence. + +The only Calc feature that uses strings is @dfn{compositions}; +@pxref{Compositions}. Strings also provide a convenient +way to do conversions between ASCII characters and integers. + +@c @starindex +@tindex string +There is a @code{string} function which provides a different display +format for strings. Basically, @samp{string(@var{s})}, where @var{s} +is a vector of integers in the proper range, is displayed as the +corresponding string of characters with no surrounding quotation +marks or other modifications. Thus @samp{string("ABC")} (or +@samp{string([65 66 67])}) will look like @samp{ABC} on the stack. +This happens regardless of whether @w{@kbd{d "}} has been used. The +only way to turn it off is to use @kbd{d U} (unformatted language +mode) which will display @samp{string("ABC")} instead. + +Control characters are displayed somewhat differently by @code{string}. +Characters below 32, and character 127, are shown using @samp{^} notation +(same as shown above, but without the backslash). The quote and +backslash characters are left alone, as are characters 128 and above. + +@c @starindex +@tindex bstring +The @code{bstring} function is just like @code{string} except that +the resulting string is breakable across multiple lines if it doesn't +fit all on one line. Potential break points occur at every space +character in the string. + +@node HMS Forms, Date Forms, Strings, Data Types +@section HMS Forms + +@noindent +@cindex Hours-minutes-seconds forms +@cindex Degrees-minutes-seconds forms +@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular +argument, the interpretation is Degrees-Minutes-Seconds. All functions +that operate on angles accept HMS forms. These are interpreted as +degrees regardless of the current angular mode. It is also possible to +use HMS as the angular mode so that calculated angles are expressed in +degrees, minutes, and seconds. + +@kindex @@ +@c @mindex @null +@kindex ' (HMS forms) +@c @mindex @null +@kindex " (HMS forms) +@c @mindex @null +@kindex h (HMS forms) +@c @mindex @null +@kindex o (HMS forms) +@c @mindex @null +@kindex m (HMS forms) +@c @mindex @null +@kindex s (HMS forms) +The default format for HMS values is +@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters +@samp{h} (for ``hours'') or +@samp{o} (approximating the ``degrees'' symbol) are accepted as well as +@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is +accepted in place of @samp{"}. +The @var{hours} value is an integer (or integer-valued float). +The @var{mins} value is an integer or integer-valued float between 0 and 59. +The @var{secs} value is a real number between 0 (inclusive) and 60 +(exclusive). A positive HMS form is interpreted as @var{hours} + +@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted +as @i{- @var{hours}} @i{-} @var{mins}/60 @i{-} @var{secs}/3600. +Display format for HMS forms is quite flexible. @xref{HMS Formats}.@refill + +HMS forms can be added and subtracted. When they are added to numbers, +the numbers are interpreted according to the current angular mode. HMS +forms can also be multiplied and divided by real numbers. Dividing +two HMS forms produces a real-valued ratio of the two angles. + +@pindex calc-time +@cindex Time of day +Just for kicks, @kbd{M-x calc-time} pushes the current time of day on +the stack as an HMS form. + +@node Date Forms, Modulo Forms, HMS Forms, Data Types +@section Date Forms + +@noindent +@cindex Date forms +A @dfn{date form} represents a date and possibly an associated time. +Simple date arithmetic is supported: Adding a number to a date +produces a new date shifted by that many days; adding an HMS form to +a date shifts it by that many hours. Subtracting two date forms +computes the number of days between them (represented as a simple +number). Many other operations, such as multiplying two date forms, +are nonsensical and are not allowed by Calc. + +Date forms are entered and displayed enclosed in @samp{< >} brackets. +The default format is, e.g., @samp{<Wed Jan 9, 1991>} for dates, +or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times. +Input is flexible; date forms can be entered in any of the usual +notations for dates and times. @xref{Date Formats}. + +Date forms are stored internally as numbers, specifically the number +of days since midnight on the morning of January 1 of the year 1 AD. +If the internal number is an integer, the form represents a date only; +if the internal number is a fraction or float, the form represents +a date and time. For example, @samp{<6:00am Wed Jan 9, 1991>} +is represented by the number 726842.25. The standard precision of +12 decimal digits is enough to ensure that a (reasonable) date and +time can be stored without roundoff error. + +If the current precision is greater than 12, date forms will keep +additional digits in the seconds position. For example, if the +precision is 15, the seconds will keep three digits after the +decimal point. Decreasing the precision below 12 may cause the +time part of a date form to become inaccurate. This can also happen +if astronomically high years are used, though this will not be an +issue in everyday (or even everymillenium) use. Note that date +forms without times are stored as exact integers, so roundoff is +never an issue for them. + +You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u} +(@code{calc-unpack}) commands to get at the numerical representation +of a date form. @xref{Packing and Unpacking}. + +Date forms can go arbitrarily far into the future or past. Negative +year numbers represent years BC. Calc uses a combination of the +Gregorian and Julian calendars, following the history of Great +Britain and the British colonies. This is the same calendar that +is used by the @code{cal} program in most Unix implementations. + +@cindex Julian calendar +@cindex Gregorian calendar +Some historical background: The Julian calendar was created by +Julius Caesar in the year 46 BC as an attempt to fix the gradual +drift caused by the lack of leap years in the calendar used +until that time. The Julian calendar introduced an extra day in +all years divisible by four. After some initial confusion, the +calendar was adopted around the year we call 8 AD. Some centuries +later it became apparent that the Julian year of 365.25 days was +itself not quite right. In 1582 Pope Gregory XIII introduced the +Gregorian calendar, which added the new rule that years divisible +by 100, but not by 400, were not to be considered leap years +despite being divisible by four. Many countries delayed adoption +of the Gregorian calendar because of religious differences; +in Britain it was put off until the year 1752, by which time +the Julian calendar had fallen eleven days behind the true +seasons. So the switch to the Gregorian calendar in early +September 1752 introduced a discontinuity: The day after +Sep 2, 1752 is Sep 14, 1752. Calc follows this convention. +To take another example, Russia waited until 1918 before +adopting the new calendar, and thus needed to remove thirteen +days (between Feb 1, 1918 and Feb 14, 1918). This means that +Calc's reckoning will be inconsistent with Russian history between +1752 and 1918, and similarly for various other countries. + +Today's timekeepers introduce an occasional ``leap second'' as +well, but Calc does not take these minor effects into account. +(If it did, it would have to report a non-integer number of days +between, say, @samp{<12:00am Mon Jan 1, 1900>} and +@samp{<12:00am Sat Jan 1, 2000>}.) + +Calc uses the Julian calendar for all dates before the year 1752, +including dates BC when the Julian calendar technically had not +yet been invented. Thus the claim that day number @i{-10000} is +called ``August 16, 28 BC'' should be taken with a grain of salt. + +Please note that there is no ``year 0''; the day before +@samp{<Sat Jan 1, +1>} is @samp{<Fri Dec 31, -1>}. These are +days 0 and @i{-1} respectively in Calc's internal numbering scheme. + +@cindex Julian day counting +Another day counting system in common use is, confusingly, also +called ``Julian.'' It was invented in 1583 by Joseph Justus +Scaliger, who named it in honor of his father Julius Caesar +Scaliger. For obscure reasons he chose to start his day +numbering on Jan 1, 4713 BC at noon, which in Calc's scheme +is @i{-1721423.5} (recall that Calc starts at midnight instead +of noon). Thus to convert a Calc date code obtained by +unpacking a date form into a Julian day number, simply add +1721423.5. The Julian code for @samp{6:00am Jan 9, 1991} +is 2448265.75. The built-in @kbd{t J} command performs +this conversion for you. + +@cindex Unix time format +The Unix operating system measures time as an integer number of +seconds since midnight, Jan 1, 1970. To convert a Calc date +value into a Unix time stamp, first subtract 719164 (the code +for @samp{<Jan 1, 1970>}), then multiply by 86400 (the number of +seconds in a day) and press @kbd{R} to round to the nearest +integer. If you have a date form, you can simply subtract the +day @samp{<Jan 1, 1970>} instead of unpacking and subtracting +719164. Likewise, divide by 86400 and add @samp{<Jan 1, 1970>} +to convert from Unix time to a Calc date form. (Note that +Unix normally maintains the time in the GMT time zone; you may +need to subtract five hours to get New York time, or eight hours +for California time. The same is usually true of Julian day +counts.) The built-in @kbd{t U} command performs these +conversions. + +@node Modulo Forms, Error Forms, Date Forms, Data Types +@section Modulo Forms + +@noindent +@cindex Modulo forms +A @dfn{modulo form} is a real number which is taken modulo (i.e., within +an integer multiple of) some value @cite{M}. Arithmetic modulo @cite{M} +often arises in number theory. Modulo forms are written +`@i{a} @t{mod} @i{M}', +where @cite{a} and @cite{M} are real numbers or HMS forms, and +@c{$0 \le a < M$} +@cite{0 <= a < @var{M}}. +In many applications @cite{a} and @cite{M} will be +integers but this is not required.@refill + +Modulo forms are not to be confused with the modulo operator @samp{%}. +The expression @samp{27 % 10} means to compute 27 modulo 10 to produce +the result 7. Further computations treat this 7 as just a regular integer. +The expression @samp{27 mod 10} produces the result @samp{7 mod 10}; +further computations with this value are again reduced modulo 10 so that +the result always lies in the desired range. + +When two modulo forms with identical @cite{M}'s are added or multiplied, +the Calculator simply adds or multiplies the values, then reduces modulo +@cite{M}. If one argument is a modulo form and the other a plain number, +the plain number is treated like a compatible modulo form. It is also +possible to raise modulo forms to powers; the result is the value raised +to the power, then reduced modulo @cite{M}. (When all values involved +are integers, this calculation is done much more efficiently than +actually computing the power and then reducing.) + +@cindex Modulo division +Two modulo forms `@i{a} @t{mod} @i{M}' and `@i{b} @t{mod} @i{M}' +can be divided if @cite{a}, @cite{b}, and @cite{M} are all +integers. The result is the modulo form which, when multiplied by +`@i{b} @t{mod} @i{M}', produces `@i{a} @t{mod} @i{M}'. If +there is no solution to this equation (which can happen only when +@cite{M} is non-prime), or if any of the arguments are non-integers, the +division is left in symbolic form. Other operations, such as square +roots, are not yet supported for modulo forms. (Note that, although +@w{`@t{(}@i{a} @t{mod} @i{M}@t{)^.5}'} will compute a ``modulo square root'' +in the sense of reducing @c{$\sqrt a$} +@cite{sqrt(a)} modulo @cite{M}, this is not a +useful definition from the number-theoretical point of view.)@refill + +@c @mindex M +@kindex M (modulo forms) +@c @mindex mod +@tindex mod (operator) +To create a modulo form during numeric entry, press the shift-@kbd{M} +key to enter the word @samp{mod}. As a special convenience, pressing +shift-@kbd{M} a second time automatically enters the value of @cite{M} +that was most recently used before. During algebraic entry, either +type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}). +Once again, pressing this a second time enters the current modulo.@refill + +You can also use @kbd{v p} and @kbd{%} to modify modulo forms. +@xref{Building Vectors}. @xref{Basic Arithmetic}. + +It is possible to mix HMS forms and modulo forms. For example, an +HMS form modulo 24 could be used to manipulate clock times; an HMS +form modulo 360 would be suitable for angles. Making the modulo @cite{M} +also be an HMS form eliminates troubles that would arise if the angular +mode were inadvertently set to Radians, in which case +@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo +24 radians! + +Modulo forms cannot have variables or formulas for components. If you +enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus +to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}. + +@c @starindex +@tindex makemod +The algebraic function @samp{makemod(a, m)} builds the modulo form +@w{@samp{a mod m}}. + +@node Error Forms, Interval Forms, Modulo Forms, Data Types +@section Error Forms + +@noindent +@cindex Error forms +@cindex Standard deviations +An @dfn{error form} is a number with an associated standard +deviation, as in @samp{2.3 +/- 0.12}. The notation +`@i{x} @t{+/-} @c{$\sigma$} +@asis{sigma}' stands for an uncertain value which follows a normal or +Gaussian distribution of mean @cite{x} and standard deviation or +``error'' @c{$\sigma$} +@cite{sigma}. Both the mean and the error can be either numbers or +formulas. Generally these are real numbers but the mean may also be +complex. If the error is negative or complex, it is changed to its +absolute value. An error form with zero error is converted to a +regular number by the Calculator.@refill + +All arithmetic and transcendental functions accept error forms as input. +Operations on the mean-value part work just like operations on regular +numbers. The error part for any function @cite{f(x)} (such as @c{$\sin x$} +@cite{sin(x)}) +is defined by the error of @cite{x} times the derivative of @cite{f} +evaluated at the mean value of @cite{x}. For a two-argument function +@cite{f(x,y)} (such as addition) the error is the square root of the sum +of the squares of the errors due to @cite{x} and @cite{y}. +@tex +$$ \eqalign{ + f(x \hbox{\code{ +/- }} \sigma) + &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr + f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y) + &= f(x,y) \hbox{\code{ +/- }} + \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x} + \right| \right)^2 + +\left(\sigma_y \left| {\partial f(x,y) \over \partial y} + \right| \right)^2 } \cr +} $$ +@end tex +Note that this +definition assumes the errors in @cite{x} and @cite{y} are uncorrelated. +A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)} +is not the same as @samp{(2 +/- 1)^2}; the former represents the product +of two independent values which happen to have the same probability +distributions, and the latter is the product of one random value with itself. +The former will produce an answer with less error, since on the average +the two independent errors can be expected to cancel out.@refill + +Consult a good text on error analysis for a discussion of the proper use +of standard deviations. Actual errors often are neither Gaussian-distributed +nor uncorrelated, and the above formulas are valid only when errors +are small. As an example, the error arising from +`@t{sin(}@i{x} @t{+/-} @c{$\sigma$} +@i{sigma}@t{)}' is +`@c{$\sigma$\nobreak} +@i{sigma} @t{abs(cos(}@i{x}@t{))}'. When @cite{x} is close to zero, +@c{$\cos x$} +@cite{cos(x)} is +close to one so the error in the sine is close to @c{$\sigma$} +@cite{sigma}; this makes sense, since @c{$\sin x$} +@cite{sin(x)} is approximately @cite{x} near zero, so a given +error in @cite{x} will produce about the same error in the sine. Likewise, +near 90 degrees @c{$\cos x$} +@cite{cos(x)} is nearly zero and so the computed error is +small: The sine curve is nearly flat in that region, so an error in @cite{x} +has relatively little effect on the value of @c{$\sin x$} +@cite{sin(x)}. However, consider +@samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so Calc will report +zero error! We get an obviously wrong result because we have violated +the small-error approximation underlying the error analysis. If the error +in @cite{x} had been small, the error in @c{$\sin x$} +@cite{sin(x)} would indeed have been negligible.@refill + +@c @mindex p +@kindex p (error forms) +@tindex +/- +To enter an error form during regular numeric entry, use the @kbd{p} +(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually +typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's +@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-p} to +type the @samp{+/-} symbol, or type it out by hand. + +Error forms and complex numbers can be mixed; the formulas shown above +are used for complex numbers, too; note that if the error part evaluates +to a complex number its absolute value (or the square root of the sum of +the squares of the absolute values of the two error contributions) is +used. Mathematically, this corresponds to a radially symmetric Gaussian +distribution of numbers on the complex plane. However, note that Calc +considers an error form with real components to represent a real number, +not a complex distribution around a real mean. + +Error forms may also be composed of HMS forms. For best results, both +the mean and the error should be HMS forms if either one is. + +@c @starindex +@tindex sdev +The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}. + +@node Interval Forms, Incomplete Objects, Error Forms, Data Types +@section Interval Forms + +@noindent +@cindex Interval forms +An @dfn{interval} is a subset of consecutive real numbers. For example, +the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4, +inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you +obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if +you multiply some number in the range @samp{[2 ..@: 4]} by some other +number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range +from 1 to 8. Interval arithmetic is used to get a worst-case estimate +of the possible range of values a computation will produce, given the +set of possible values of the input. + +@ifinfo +Calc supports several varieties of intervals, including @dfn{closed} +intervals of the type shown above, @dfn{open} intervals such as +@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4 +@emph{exclusive}, and @dfn{semi-open} intervals in which one end +uses a round parenthesis and the other a square bracket. In mathematical +terms, +@samp{[2 ..@: 4]} means @cite{2 <= x <= 4}, whereas +@samp{[2 ..@: 4)} represents @cite{2 <= x < 4}, +@samp{(2 ..@: 4]} represents @cite{2 < x <= 4}, and +@samp{(2 ..@: 4)} represents @cite{2 < x < 4}.@refill +@end ifinfo +@tex +Calc supports several varieties of intervals, including \dfn{closed} +intervals of the type shown above, \dfn{open} intervals such as +\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4 +\emph{exclusive}, and \dfn{semi-open} intervals in which one end +uses a round parenthesis and the other a square bracket. In mathematical +terms, +$$ \eqalign{ + [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr + [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr + (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr + (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr +} $$ +@end tex + +The lower and upper limits of an interval must be either real numbers +(or HMS or date forms), or symbolic expressions which are assumed to be +real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit +must be less than the upper limit. A closed interval containing only +one value, @samp{[3 ..@: 3]}, is converted to a plain number (3) +automatically. An interval containing no values at all (such as +@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not +guaranteed to behave well when used in arithmetic. Note that the +interval @samp{[3 .. inf)} represents all real numbers greater than +or equal to 3, and @samp{(-inf .. inf)} represents all real numbers. +In fact, @samp{[-inf .. inf]} represents all real numbers including +the real infinities. + +Intervals are entered in the notation shown here, either as algebraic +formulas, or using incomplete forms. (@xref{Incomplete Objects}.) +In algebraic formulas, multiple periods in a row are collected from +left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2} +rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to +get the other interpretation. If you omit the lower or upper limit, +a default of @samp{-inf} or @samp{inf} (respectively) is furnished. + +``Infinite mode'' also affects operations on intervals +(@pxref{Infinities}). Calc will always introduce an open infinity, +as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities, +@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in infinite mode; +otherwise they are left unevaluated. Note that the ``direction'' of +a zero is not an issue in this case since the zero is always assumed +to be continuous with the rest of the interval. For intervals that +contain zero inside them Calc is forced to give the result, +@samp{1 / (-2 .. 2) = [-inf .. inf]}. + +While it may seem that intervals and error forms are similar, they are +based on entirely different concepts of inexact quantities. An error +form `@i{x} @t{+/-} @c{$\sigma$} +@i{sigma}' means a variable is random, and its value could +be anything but is ``probably'' within one @c{$\sigma$} +@i{sigma} of the mean value @cite{x}. +An interval `@t{[}@i{a} @t{..@:} @i{b}@t{]}' means a variable's value +is unknown, but guaranteed to lie in the specified range. Error forms +are statistical or ``average case'' approximations; interval arithmetic +tends to produce ``worst case'' bounds on an answer.@refill + +Intervals may not contain complex numbers, but they may contain +HMS forms or date forms. + +@xref{Set Operations}, for commands that interpret interval forms +as subsets of the set of real numbers. + +@c @starindex +@tindex intv +The algebraic function @samp{intv(n, a, b)} builds an interval form +from @samp{a} to @samp{b}; @samp{n} is an integer code which must +be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or +3 for @samp{[..]}. + +Please note that in fully rigorous interval arithmetic, care would be +taken to make sure that the computation of the lower bound rounds toward +minus infinity, while upper bound computations round toward plus +infinity. Calc's arithmetic always uses a round-to-nearest mode, +which means that roundoff errors could creep into an interval +calculation to produce intervals slightly smaller than they ought to +be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^} +should yield the interval @samp{[1..2]} again, but in fact it yields the +(slightly too small) interval @samp{[1..1.9999999]} due to roundoff +error. + +@node Incomplete Objects, Variables, Interval Forms, Data Types +@section Incomplete Objects + +@noindent +@c @mindex [ ] +@kindex [ +@c @mindex ( ) +@kindex ( +@kindex , +@c @mindex @null +@kindex ] +@c @mindex @null +@kindex ) +@cindex Incomplete vectors +@cindex Incomplete complex numbers +@cindex Incomplete interval forms +When @kbd{(} or @kbd{[} is typed to begin entering a complex number or +vector, respectively, the effect is to push an @dfn{incomplete} complex +number or vector onto the stack. The @kbd{,} key adds the value(s) at +the top of the stack onto the current incomplete object. The @kbd{)} +and @kbd{]} keys ``close'' the incomplete object after adding any values +on the top of the stack in front of the incomplete object. + +As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]} +pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )} +pushes the complex number @samp{(1, 1.414)} (approximately). + +If several values lie on the stack in front of the incomplete object, +all are collected and appended to the object. Thus the @kbd{,} key +is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people +prefer the equivalent @key{SPC} key to @key{RET}.@refill + +As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or +@kbd{,} adds a zero or duplicates the preceding value in the list being +formed. Typing @key{DEL} during incomplete entry removes the last item +from the list. + +@kindex ; +The @kbd{;} key is used in the same way as @kbd{,} to create polar complex +numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for +creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is +equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}. + +@kindex .. +@pindex calc-dots +Incomplete entry is also used to enter intervals. For example, +@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type +the first period, it will be interpreted as a decimal point, but when +you type a second period immediately afterward, it is re-interpreted as +part of the interval symbol. Typing @kbd{..} corresponds to executing +the @code{calc-dots} command. + +If you find incomplete entry distracting, you may wish to enter vectors +and complex numbers as algebraic formulas by pressing the apostrophe key. + +@node Variables, Formulas, Incomplete Objects, Data Types +@section Variables + +@noindent +@cindex Variables, in formulas +A @dfn{variable} is somewhere between a storage register on a conventional +calculator, and a variable in a programming language. (In fact, a Calc +variable is really just an Emacs Lisp variable that contains a Calc number +or formula.) A variable's name is normally composed of letters and digits. +Calc also allows apostrophes and @code{#} signs in variable names. +The Calc variable @code{foo} corresponds to the Emacs Lisp variable +@code{var-foo}. Commands like @kbd{s s} (@code{calc-store}) that operate +on variables can be made to use any arbitrary Lisp variable simply by +backspacing over the @samp{var-} prefix in the minibuffer.@refill + +In a command that takes a variable name, you can either type the full +name of a variable, or type a single digit to use one of the special +convenience variables @code{var-q0} through @code{var-q9}. For example, +@kbd{3 s s 2} stores the number 3 in variable @code{var-q2}, and +@w{@kbd{3 s s foo @key{RET}}} stores that number in variable +@code{var-foo}.@refill + +To push a variable itself (as opposed to the variable's value) on the +stack, enter its name as an algebraic expression using the apostrophe +(@key{'}) key. Variable names in algebraic formulas implicitly have +@samp{var-} prefixed to their names. The @samp{#} character in variable +names used in algebraic formulas corresponds to a dash @samp{-} in the +Lisp variable name. If the name contains any dashes, the prefix @samp{var-} +is @emph{not} automatically added. Thus the two formulas @samp{foo + 1} +and @samp{var#foo + 1} both refer to the same variable. + +@kindex = +@pindex calc-evaluate +@cindex Evaluation of variables in a formula +@cindex Variables, evaluation +@cindex Formulas, evaluation +The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by +replacing all variables in the formula which have been given values by a +@code{calc-store} or @code{calc-let} command by their stored values. +Other variables are left alone. Thus a variable that has not been +stored acts like an abstract variable in algebra; a variable that has +been stored acts more like a register in a traditional calculator. +With a positive numeric prefix argument, @kbd{=} evaluates the top +@var{n} stack entries; with a negative argument, @kbd{=} evaluates +the @var{n}th stack entry. + +@cindex @code{e} variable +@cindex @code{pi} variable +@cindex @code{i} variable +@cindex @code{phi} variable +@cindex @code{gamma} variable +@vindex e +@vindex pi +@vindex i +@vindex phi +@vindex gamma +A few variables are called @dfn{special constants}. Their names are +@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}. +(@xref{Scientific Functions}.) When they are evaluated with @kbd{=}, +their values are calculated if necessary according to the current precision +or complex polar mode. If you wish to use these symbols for other purposes, +simply undefine or redefine them using @code{calc-store}.@refill + +The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for +infinite or indeterminate values. It's best not to use them as +regular variables, since Calc uses special algebraic rules when +it manipulates them. Calc displays a warning message if you store +a value into any of these special variables. + +@xref{Store and Recall}, for a discussion of commands dealing with variables. + +@node Formulas, , Variables, Data Types +@section Formulas + +@noindent +@cindex Formulas +@cindex Expressions +@cindex Operators in formulas +@cindex Precedence of operators +When you press the apostrophe key you may enter any expression or formula +in algebraic form. (Calc uses the terms ``expression'' and ``formula'' +interchangeably.) An expression is built up of numbers, variable names, +and function calls, combined with various arithmetic operators. +Parentheses may +be used to indicate grouping. Spaces are ignored within formulas, except +that spaces are not permitted within variable names or numbers. +Arithmetic operators, in order from highest to lowest precedence, and +with their equivalent function names, are: + +@samp{_} [@code{subscr}] (subscripts); + +postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25}); + +prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x}) +and prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x}); + +@samp{+/-} [@code{sdev}] (the standard deviation symbol) and +@samp{mod} [@code{makemod}] (the symbol for modulo forms); + +postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!}) +and postfix @samp{!!} [@code{dfact}] (double factorial); + +@samp{^} [@code{pow}] (raised-to-the-power-of); + +@samp{*} [@code{mul}]; + +@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and +@samp{\} [@code{idiv}] (integer division); + +infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y}); + +@samp{|} [@code{vconcat}] (vector concatenation); + +relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}], +@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}]; + +@samp{&&} [@code{land}] (logical ``and''); + +@samp{||} [@code{lor}] (logical ``or''); + +the C-style ``if'' operator @samp{a?b:c} [@code{if}]; + +@samp{!!!} [@code{pnot}] (rewrite pattern ``not''); + +@samp{&&&} [@code{pand}] (rewrite pattern ``and''); + +@samp{|||} [@code{por}] (rewrite pattern ``or''); + +@samp{:=} [@code{assign}] (for assignments and rewrite rules); + +@samp{::} [@code{condition}] (rewrite pattern condition); + +@samp{=>} [@code{evalto}]. + +Note that, unlike in usual computer notation, multiplication binds more +strongly than division: @samp{a*b/c*d} is equivalent to @c{$a b \over c d$} +@cite{(a*b)/(c*d)}. + +@cindex Multiplication, implicit +@cindex Implicit multiplication +The multiplication sign @samp{*} may be omitted in many cases. In particular, +if the righthand side is a number, variable name, or parenthesized +expression, the @samp{*} may be omitted. Implicit multiplication has the +same precedence as the explicit @samp{*} operator. The one exception to +the rule is that a variable name followed by a parenthesized expression, +as in @samp{f(x)}, +is interpreted as a function call, not an implicit @samp{*}. In many +cases you must use a space if you omit the @samp{*}: @samp{2a} is the +same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab} +is a variable called @code{ab}, @emph{not} the product of @samp{a} and +@samp{b}! Also note that @samp{f (x)} is still a function call.@refill + +@cindex Implicit comma in vectors +The rules are slightly different for vectors written with square brackets. +In vectors, the space character is interpreted (like the comma) as a +separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is +equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent +to @samp{2*a*b + c*d}. +Note that spaces around the brackets, and around explicit commas, are +ignored. To force spaces to be interpreted as multiplication you can +enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is +interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted +between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}.@refill + +Vectors that contain commas (not embedded within nested parentheses or +brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector +of two elements. Also, if it would be an error to treat spaces as +separators, but not otherwise, then Calc will ignore spaces: +@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is +a vector of two elements. Finally, vectors entered with curly braces +instead of square brackets do not give spaces any special treatment. +When Calc displays a vector that does not contain any commas, it will +insert parentheses if necessary to make the meaning clear: +@w{@samp{[(a b)]}}. + +The expression @samp{5%-2} is ambiguous; is this five-percent minus two, +or five modulo minus-two? Calc always interprets the leftmost symbol as +an infix operator preferentially (modulo, in this case), so you would +need to write @samp{(5%)-2} to get the former interpretation. + +@cindex Function call notation +A function call is, e.g., @samp{sin(1+x)}. Function names follow the same +rules as variable names except that the default prefix @samp{calcFunc-} is +used (instead of @samp{var-}) for the internal Lisp form. +Most mathematical Calculator commands like +@code{calc-sin} have function equivalents like @code{sin}. +If no Lisp function is defined for a function called by a formula, the +call is left as it is during algebraic manipulation: @samp{f(x+y)} is +left alone. Beware that many innocent-looking short names like @code{in} +and @code{re} have predefined meanings which could surprise you; however, +single letters or single letters followed by digits are always safe to +use for your own function names. @xref{Function Index}.@refill + +In the documentation for particular commands, the notation @kbd{H S} +(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the +command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all +represent the same operation.@refill + +Commands that interpret (``parse'') text as algebraic formulas include +algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse +the contents of the editing buffer when you finish, the @kbd{M-# g} +and @w{@kbd{M-# r}} commands, the @kbd{C-y} command, the X window system +``paste'' mouse operation, and Embedded Mode. All of these operations +use the same rules for parsing formulas; in particular, language modes +(@pxref{Language Modes}) affect them all in the same way. + +When you read a large amount of text into the Calculator (say a vector +which represents a big set of rewrite rules; @pxref{Rewrite Rules}), +you may wish to include comments in the text. Calc's formula parser +ignores the symbol @samp{%%} and anything following it on a line: + +@example +[ a + b, %% the sum of "a" and "b" + c + d, + %% last line is coming up: + e + f ] +@end example + +@noindent +This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}. + +@xref{Syntax Tables}, for a way to create your own operators and other +input notations. @xref{Compositions}, for a way to create new display +formats. + +@xref{Algebra}, for commands for manipulating formulas symbolically. + +@node Stack and Trail, Mode Settings, Data Types, Top +@chapter Stack and Trail Commands + +@noindent +This chapter describes the Calc commands for manipulating objects on the +stack and in the trail buffer. (These commands operate on objects of any +type, such as numbers, vectors, formulas, and incomplete objects.) + +@menu +* Stack Manipulation:: +* Editing Stack Entries:: +* Trail Commands:: +* Keep Arguments:: +@end menu + +@node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail +@section Stack Manipulation Commands + +@noindent +@kindex RET +@kindex SPC +@pindex calc-enter +@cindex Duplicating stack entries +To duplicate the top object on the stack, press @key{RET} or @key{SPC} +(two equivalent keys for the @code{calc-enter} command). +Given a positive numeric prefix argument, these commands duplicate +several elements at the top of the stack. +Given a negative argument, +these commands duplicate the specified element of the stack. +Given an argument of zero, they duplicate the entire stack. +For example, with @samp{10 20 30} on the stack, +@key{RET} creates @samp{10 20 30 30}, +@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30}, +@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and +@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}.@refill + +@kindex LFD +@pindex calc-over +The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you +have it, else on @kbd{C-j}) is like @code{calc-enter} +except that the sign of the numeric prefix argument is interpreted +oppositely. Also, with no prefix argument the default argument is 2. +Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}} +are both equivalent to @kbd{C-u - 2 @key{RET}}, producing +@samp{10 20 30 20}.@refill + +@kindex DEL +@kindex C-d +@pindex calc-pop +@cindex Removing stack entries +@cindex Deleting stack entries +To remove the top element from the stack, press @key{DEL} (@code{calc-pop}). +The @kbd{C-d} key is a synonym for @key{DEL}. +(If the top element is an incomplete object with at least one element, the +last element is removed from it.) Given a positive numeric prefix argument, +several elements are removed. Given a negative argument, the specified +element of the stack is deleted. Given an argument of zero, the entire +stack is emptied. +For example, with @samp{10 20 30} on the stack, +@key{DEL} leaves @samp{10 20}, +@kbd{C-u 2 @key{DEL}} leaves @samp{10}, +@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and +@kbd{C-u 0 @key{DEL}} leaves an empty stack.@refill + +@kindex M-DEL +@pindex calc-pop-above +The @key{M-DEL} (@code{calc-pop-above}) command is to @key{DEL} what +@key{LFD} is to @key{RET}: It interprets the sign of the numeric +prefix argument in the opposite way, and the default argument is 2. +Thus @key{M-DEL} by itself removes the second-from-top stack element, +leaving the first, third, fourth, and so on; @kbd{M-3 M-DEL} deletes +the third stack element. + +@kindex TAB +@pindex calc-roll-down +To exchange the top two elements of the stack, press @key{TAB} +(@code{calc-roll-down}). Given a positive numeric prefix argument, the +specified number of elements at the top of the stack are rotated downward. +Given a negative argument, the entire stack is rotated downward the specified +number of times. Given an argument of zero, the entire stack is reversed +top-for-bottom. +For example, with @samp{10 20 30 40 50} on the stack, +@key{TAB} creates @samp{10 20 30 50 40}, +@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40}, +@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and +@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}.@refill + +@kindex M-TAB +@pindex calc-roll-up +The command @key{M-TAB} (@code{calc-roll-up}) is analogous to @key{TAB} +except that it rotates upward instead of downward. Also, the default +with no prefix argument is to rotate the top 3 elements. +For example, with @samp{10 20 30 40 50} on the stack, +@key{M-TAB} creates @samp{10 20 40 50 30}, +@kbd{C-u 4 @key{M-TAB}} creates @samp{10 30 40 50 20}, +@kbd{C-u - 2 @key{M-TAB}} creates @samp{30 40 50 10 20}, and +@kbd{C-u 0 @key{M-TAB}} creates @samp{50 40 30 20 10}.@refill + +A good way to view the operation of @key{TAB} and @key{M-TAB} is in +terms of moving a particular element to a new position in the stack. +With a positive argument @i{n}, @key{TAB} moves the top stack +element down to level @i{n}, making room for it by pulling all the +intervening stack elements toward the top. @key{M-TAB} moves the +element at level @i{n} up to the top. (Compare with @key{LFD}, +which copies instead of moving the element in level @i{n}.) + +With a negative argument @i{-n}, @key{TAB} rotates the stack +to move the object in level @i{n} to the deepest place in the +stack, and the object in level @i{n+1} to the top. @key{M-TAB} +rotates the deepest stack element to be in level @i{n}, also +putting the top stack element in level @i{n+1}. + +@xref{Selecting Subformulas}, for a way to apply these commands to +any portion of a vector or formula on the stack. + +@node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail +@section Editing Stack Entries + +@noindent +@kindex ` +@pindex calc-edit +@pindex calc-edit-finish +@cindex Editing the stack with Emacs +The backquote, @kbd{`} (@code{calc-edit}) command creates a temporary +buffer (@samp{*Calc Edit*}) for editing the top-of-stack value using +regular Emacs commands. With a numeric prefix argument, it edits the +specified number of stack entries at once. (An argument of zero edits +the entire stack; a negative argument edits one specific stack entry.) + +When you are done editing, press @kbd{M-# M-#} to finish and return +to Calc. The @key{RET} and @key{LFD} keys also work to finish most +sorts of editing, though in some cases Calc leaves @key{RET} with its +usual meaning (``insert a newline'') if it's a situation where you +might want to insert new lines into the editing buffer. The traditional +Emacs ``finish'' key sequence, @kbd{C-c C-c}, also works to finish +editing and may be easier to type, depending on your keyboard. + +When you finish editing, the Calculator parses the lines of text in +the @samp{*Calc Edit*} buffer as numbers or formulas, replaces the +original stack elements in the original buffer with these new values, +then kills the @samp{*Calc Edit*} buffer. The original Calculator buffer +continues to exist during editing, but for best results you should be +careful not to change it until you have finished the edit. You can +also cancel the edit by pressing @kbd{M-# x}. + +The formula is normally reevaluated as it is put onto the stack. +For example, editing @samp{a + 2} to @samp{3 + 2} and pressing +@kbd{M-# M-#} will push 5 on the stack. If you use @key{LFD} to +finish, Calc will put the result on the stack without evaluating it. + +If you give a prefix argument to @kbd{M-# M-#} (or @kbd{C-c C-c}), +Calc will not kill the @samp{*Calc Edit*} buffer. You can switch +back to that buffer and continue editing if you wish. However, you +should understand that if you initiated the edit with @kbd{`}, the +@kbd{M-# M-#} operation will be programmed to replace the top of the +stack with the new edited value, and it will do this even if you have +rearranged the stack in the meanwhile. This is not so much of a problem +with other editing commands, though, such as @kbd{s e} +(@code{calc-edit-variable}; @pxref{Operations on Variables}). + +If the @code{calc-edit} command involves more than one stack entry, +each line of the @samp{*Calc Edit*} buffer is interpreted as a +separate formula. Otherwise, the entire buffer is interpreted as +one formula, with line breaks ignored. (You can use @kbd{C-o} or +@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.) + +The @kbd{`} key also works during numeric or algebraic entry. The +text entered so far is moved to the @code{*Calc Edit*} buffer for +more extensive editing than is convenient in the minibuffer. + +@node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail +@section Trail Commands + +@noindent +@cindex Trail buffer +The commands for manipulating the Calc Trail buffer are two-key sequences +beginning with the @kbd{t} prefix. + +@kindex t d +@pindex calc-trail-display +The @kbd{t d} (@code{calc-trail-display}) command turns display of the +trail on and off. Normally the trail display is toggled on if it was off, +off if it was on. With a numeric prefix of zero, this command always +turns the trail off; with a prefix of one, it always turns the trail on. +The other trail-manipulation commands described here automatically turn +the trail on. Note that when the trail is off values are still recorded +there; they are simply not displayed. To set Emacs to turn the trail +off by default, type @kbd{t d} and then save the mode settings with +@kbd{m m} (@code{calc-save-modes}). + +@kindex t i +@pindex calc-trail-in +@kindex t o +@pindex calc-trail-out +The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o} +(@code{calc-trail-out}) commands switch the cursor into and out of the +Calc Trail window. In practice they are rarely used, since the commands +shown below are a more convenient way to move around in the +trail, and they work ``by remote control'' when the cursor is still +in the Calculator window.@refill + +@cindex Trail pointer +There is a @dfn{trail pointer} which selects some entry of the trail at +any given time. The trail pointer looks like a @samp{>} symbol right +before the selected number. The following commands operate on the +trail pointer in various ways. + +@kindex t y +@pindex calc-trail-yank +@cindex Retrieving previous results +The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in +the trail and pushes it onto the Calculator stack. It allows you to +re-use any previously computed value without retyping. With a numeric +prefix argument @var{n}, it yanks the value @var{n} lines above the current +trail pointer. + +@kindex t < +@pindex calc-trail-scroll-left +@kindex t > +@pindex calc-trail-scroll-right +The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >} +(@code{calc-trail-scroll-right}) commands horizontally scroll the trail +window left or right by one half of its width.@refill + +@kindex t n +@pindex calc-trail-next +@kindex t p +@pindex calc-trail-previous +@kindex t f +@pindex calc-trail-forward +@kindex t b +@pindex calc-trail-backward +The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p} +(@code{calc-trail-previous)} commands move the trail pointer down or up +one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b} +(@code{calc-trail-backward}) commands move the trail pointer down or up +one screenful at a time. All of these commands accept numeric prefix +arguments to move several lines or screenfuls at a time.@refill + +@kindex t [ +@pindex calc-trail-first +@kindex t ] +@pindex calc-trail-last +@kindex t h +@pindex calc-trail-here +The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]} +(@code{calc-trail-last}) commands move the trail pointer to the first or +last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command +moves the trail pointer to the cursor position; unlike the other trail +commands, @kbd{t h} works only when Calc Trail is the selected window.@refill + +@kindex t s +@pindex calc-trail-isearch-forward +@kindex t r +@pindex calc-trail-isearch-backward +@ifinfo +The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} +(@code{calc-trail-isearch-backward}) commands perform an incremental +search forward or backward through the trail. You can press @key{RET} +to terminate the search; the trail pointer moves to the current line. +If you cancel the search with @kbd{C-g}, the trail pointer stays where +it was when the search began.@refill +@end ifinfo +@tex +The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} +(@code{calc-trail-isearch-backward}) com\-mands perform an incremental +search forward or backward through the trail. You can press @key{RET} +to terminate the search; the trail pointer moves to the current line. +If you cancel the search with @kbd{C-g}, the trail pointer stays where +it was when the search began. +@end tex + +@kindex t m +@pindex calc-trail-marker +The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a +line of text of your own choosing into the trail. The text is inserted +after the line containing the trail pointer; this usually means it is +added to the end of the trail. Trail markers are useful mainly as the +targets for later incremental searches in the trail. + +@kindex t k +@pindex calc-trail-kill +The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line +from the trail. The line is saved in the Emacs kill ring suitable for +yanking into another buffer, but it is not easy to yank the text back +into the trail buffer. With a numeric prefix argument, this command +kills the @var{n} lines below or above the selected one. + +The @kbd{t .} (@code{calc-full-trail-vectors}) command is described +elsewhere; @pxref{Vector and Matrix Formats}. + +@node Keep Arguments, , Trail Commands, Stack and Trail +@section Keep Arguments + +@noindent +@kindex K +@pindex calc-keep-args +The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for +the following command. It prevents that command from removing its +arguments from the stack. For example, after @kbd{2 @key{RET} 3 +}, +the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +}, +the stack contains the arguments and the result: @samp{2 3 5}. + +This works for all commands that take arguments off the stack. As +another example, @kbd{K a s} simplifies a formula, pushing the +simplified version of the formula onto the stack after the original +formula (rather than replacing the original formula). + +Note that you could get the same effect by typing @kbd{RET a s}, +copying the formula and then simplifying the copy. One difference +is that for a very large formula the time taken to format the +intermediate copy in @kbd{RET a s} could be noticeable; @kbd{K a s} +would avoid this extra work. + +Even stack manipulation commands are affected. @key{TAB} works by +popping two values and pushing them back in the opposite order, +so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}. + +A few Calc commands provide other ways of doing the same thing. +For example, @kbd{' sin($)} replaces the number on the stack with +its sine using algebraic entry; to push the sine and keep the +original argument you could use either @kbd{' sin($1)} or +@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s} +command is effectively the same as @kbd{K s t}. @xref{Storing Variables}. + +Keyboard macros may interact surprisingly with the @kbd{K} prefix. +If you have defined a keyboard macro to be, say, @samp{Q +} to add +one number to the square root of another, then typing @kbd{K X} will +execute @kbd{K Q +}, probably not what you expected. The @kbd{K} +prefix will apply to just the first command in the macro rather than +the whole macro. + +If you execute a command and then decide you really wanted to keep +the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}). +This command pushes the last arguments that were popped by any command +onto the stack. Note that the order of things on the stack will be +different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves +@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}. + +@node Mode Settings, Arithmetic, Stack and Trail, Top +@chapter Mode Settings + +@noindent +This chapter describes commands that set modes in the Calculator. +They do not affect the contents of the stack, although they may change +the @emph{appearance} or @emph{interpretation} of the stack's contents. + +@menu +* General Mode Commands:: +* Precision:: +* Inverse and Hyperbolic:: +* Calculation Modes:: +* Simplification Modes:: +* Declarations:: +* Display Modes:: +* Language Modes:: +* Modes Variable:: +* Calc Mode Line:: +@end menu + +@node General Mode Commands, Precision, Mode Settings, Mode Settings +@section General Mode Commands + +@noindent +@kindex m m +@pindex calc-save-modes +@cindex Continuous memory +@cindex Saving mode settings +@cindex Permanent mode settings +@cindex @file{.emacs} file, mode settings +You can save all of the current mode settings in your @file{.emacs} file +with the @kbd{m m} (@code{calc-save-modes}) command. This will cause +Emacs to reestablish these modes each time it starts up. The modes saved +in the file include everything controlled by the @kbd{m} and @kbd{d} +prefix keys, the current precision and binary word size, whether or not +the trail is displayed, the current height of the Calc window, and more. +The current interface (used when you type @kbd{M-# M-#}) is also saved. +If there were already saved mode settings in the file, they are replaced. +Otherwise, the new mode information is appended to the end of the file. + +@kindex m R +@pindex calc-mode-record-mode +The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to +record the new mode settings (as if by pressing @kbd{m m}) every +time a mode setting changes. If Embedded Mode is enabled, other +options are available; @pxref{Mode Settings in Embedded Mode}. + +@kindex m F +@pindex calc-settings-file-name +The @kbd{m F} (@code{calc-settings-file-name}) command allows you to +choose a different place than your @file{.emacs} file for @kbd{m m}, +@kbd{Z P}, and similar commands to save permanent information. +You are prompted for a file name. All Calc modes are then reset to +their default values, then settings from the file you named are loaded +if this file exists, and this file becomes the one that Calc will +use in the future for commands like @kbd{m m}. The default settings +file name is @file{~/.emacs}. You can see the current file name by +giving a blank response to the @kbd{m F} prompt. See also the +discussion of the @code{calc-settings-file} variable; @pxref{Installation}. + +If the file name you give contains the string @samp{.emacs} anywhere +inside it, @kbd{m F} will not automatically load the new file. This +is because you are presumably switching to your @file{~/.emacs} file, +which may contain other things you don't want to reread. You can give +a numeric prefix argument of 1 to @kbd{m F} to force it to read the +file no matter what its name. Conversely, an argument of @i{-1} tells +@kbd{m F} @emph{not} to read the new file. An argument of 2 or @i{-2} +tells @kbd{m F} not to reset the modes to their defaults beforehand, +which is useful if you intend your new file to have a variant of the +modes present in the file you were using before. + +@kindex m x +@pindex calc-always-load-extensions +The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode +in which the first use of Calc loads the entire program, including all +extensions modules. Otherwise, the extensions modules will not be loaded +until the various advanced Calc features are used. Since this mode only +has effect when Calc is first loaded, @kbd{m x} is usually followed by +@kbd{m m} to make the mode-setting permanent. To load all of Calc just +once, rather than always in the future, you can press @kbd{M-# L}. + +@kindex m S +@pindex calc-shift-prefix +The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which +all of Calc's letter prefix keys may be typed shifted as well as unshifted. +If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often +you might find it easier to turn this mode on so that you can type +@kbd{A S} instead. When this mode is enabled, the commands that used to +be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can +now be invoked by pressing the shifted letter twice: @kbd{A A}. Note +that the @kbd{v} prefix key always works both shifted and unshifted, and +the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h} +prefix is not affected by this mode. Press @kbd{m S} again to disable +shifted-prefix mode. + +@node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings +@section Precision + +@noindent +@kindex p +@pindex calc-precision +@cindex Precision of calculations +The @kbd{p} (@code{calc-precision}) command controls the precision to +which floating-point calculations are carried. The precision must be +at least 3 digits and may be arbitrarily high, within the limits of +memory and time. This affects only floats: Integer and rational +calculations are always carried out with as many digits as necessary. + +The @kbd{p} key prompts for the current precision. If you wish you +can instead give the precision as a numeric prefix argument. + +Many internal calculations are carried to one or two digits higher +precision than normal. Results are rounded down afterward to the +current precision. Unless a special display mode has been selected, +floats are always displayed with their full stored precision, i.e., +what you see is what you get. Reducing the current precision does not +round values already on the stack, but those values will be rounded +down before being used in any calculation. The @kbd{c 0} through +@kbd{c 9} commands (@pxref{Conversions}) can be used to round an +existing value to a new precision.@refill + +@cindex Accuracy of calculations +It is important to distinguish the concepts of @dfn{precision} and +@dfn{accuracy}. In the normal usage of these words, the number +123.4567 has a precision of 7 digits but an accuracy of 4 digits. +The precision is the total number of digits not counting leading +or trailing zeros (regardless of the position of the decimal point). +The accuracy is simply the number of digits after the decimal point +(again not counting trailing zeros). In Calc you control the precision, +not the accuracy of computations. If you were to set the accuracy +instead, then calculations like @samp{exp(100)} would generate many +more digits than you would typically need, while @samp{exp(-100)} would +probably round to zero! In Calc, both these computations give you +exactly 12 (or the requested number of) significant digits. + +The only Calc features that deal with accuracy instead of precision +are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}), +and the rounding functions like @code{floor} and @code{round} +(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9} +deal with both precision and accuracy depending on the magnitudes +of the numbers involved. + +If you need to work with a particular fixed accuracy (say, dollars and +cents with two digits after the decimal point), one solution is to work +with integers and an ``implied'' decimal point. For example, $8.99 +divided by 6 would be entered @kbd{899 RET 6 /}, yielding 149.833 +(actually $1.49833 with our implied decimal point); pressing @kbd{R} +would round this to 150 cents, i.e., $1.50. + +@xref{Floats}, for still more on floating-point precision and related +issues. + +@node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings +@section Inverse and Hyperbolic Flags + +@noindent +@kindex I +@pindex calc-inverse +There is no single-key equivalent to the @code{calc-arcsin} function. +Instead, you must first press @kbd{I} (@code{calc-inverse}) to set +the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}). +The @kbd{I} key actually toggles the Inverse Flag. When this flag +is set, the word @samp{Inv} appears in the mode line.@refill + +@kindex H +@pindex calc-hyperbolic +Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the +Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}. +If both of these flags are set at once, the effect will be +@code{calc-arcsinh}. (The Hyperbolic flag is also used by some +non-trigonometric commands; for example @kbd{H L} computes a base-10, +instead of base-@i{e}, logarithm.)@refill + +Command names like @code{calc-arcsin} are provided for completeness, and +may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to +toggle the Inverse and/or Hyperbolic flags and then execute the +corresponding base command (@code{calc-sin} in this case). + +The Inverse and Hyperbolic flags apply only to the next Calculator +command, after which they are automatically cleared. (They are also +cleared if the next keystroke is not a Calc command.) Digits you +type after @kbd{I} or @kbd{H} (or @kbd{K}) are treated as prefix +arguments for the next command, not as numeric entries. The same +is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means to +subtract and keep arguments). + +The third Calc prefix flag, @kbd{K} (keep-arguments), is discussed +elsewhere. @xref{Keep Arguments}. + +@node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings +@section Calculation Modes + +@noindent +The commands in this section are two-key sequences beginning with +the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.) +The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere +(@pxref{Algebraic Entry}). + +@menu +* Angular Modes:: +* Polar Mode:: +* Fraction Mode:: +* Infinite Mode:: +* Symbolic Mode:: +* Matrix Mode:: +* Automatic Recomputation:: +* Working Message:: +@end menu + +@node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes +@subsection Angular Modes + +@noindent +@cindex Angular mode +The Calculator supports three notations for angles: radians, degrees, +and degrees-minutes-seconds. When a number is presented to a function +like @code{sin} that requires an angle, the current angular mode is +used to interpret the number as either radians or degrees. If an HMS +form is presented to @code{sin}, it is always interpreted as +degrees-minutes-seconds. + +Functions that compute angles produce a number in radians, a number in +degrees, or an HMS form depending on the current angular mode. If the +result is a complex number and the current mode is HMS, the number is +instead expressed in degrees. (Complex-number calculations would +normally be done in radians mode, though. Complex numbers are converted +to degrees by calculating the complex result in radians and then +multiplying by 180 over @c{$\pi$} +@cite{pi}.) + +@kindex m r +@pindex calc-radians-mode +@kindex m d +@pindex calc-degrees-mode +@kindex m h +@pindex calc-hms-mode +The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}), +and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode. +The current angular mode is displayed on the Emacs mode line. +The default angular mode is degrees.@refill + +@node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes +@subsection Polar Mode + +@noindent +@cindex Polar mode +The Calculator normally ``prefers'' rectangular complex numbers in the +sense that rectangular form is used when the proper form can not be +decided from the input. This might happen by multiplying a rectangular +number by a polar one, by taking the square root of a negative real +number, or by entering @kbd{( 2 @key{SPC} 3 )}. + +@kindex m p +@pindex calc-polar-mode +The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number +preference between rectangular and polar forms. In polar mode, all +of the above example situations would produce polar complex numbers. + +@node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes +@subsection Fraction Mode + +@noindent +@cindex Fraction mode +@cindex Division of integers +Division of two integers normally yields a floating-point number if the +result cannot be expressed as an integer. In some cases you would +rather get an exact fractional answer. One way to accomplish this is +to multiply fractions instead: @kbd{6 @key{RET} 1:4 *} produces @cite{3:2} +even though @kbd{6 @key{RET} 4 /} produces @cite{1.5}. + +@kindex m f +@pindex calc-frac-mode +To set the Calculator to produce fractional results for normal integer +divisions, use the @kbd{m f} (@code{calc-frac-mode}) command. +For example, @cite{8/4} produces @cite{2} in either mode, +but @cite{6/4} produces @cite{3:2} in Fraction Mode, @cite{1.5} in +Float Mode.@refill + +At any time you can use @kbd{c f} (@code{calc-float}) to convert a +fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a +float to a fraction. @xref{Conversions}. + +@node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes +@subsection Infinite Mode + +@noindent +@cindex Infinite mode +The Calculator normally treats results like @cite{1 / 0} as errors; +formulas like this are left in unsimplified form. But Calc can be +put into a mode where such calculations instead produce ``infinite'' +results. + +@kindex m i +@pindex calc-infinite-mode +The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode +on and off. When the mode is off, infinities do not arise except +in calculations that already had infinities as inputs. (One exception +is that infinite open intervals like @samp{[0 .. inf)} can be +generated; however, intervals closed at infinity (@samp{[0 .. inf]}) +will not be generated when infinite mode is off.) + +With infinite mode turned on, @samp{1 / 0} will generate @code{uinf}, +an undirected infinity. @xref{Infinities}, for a discussion of the +difference between @code{inf} and @code{uinf}. Also, @cite{0 / 0} +evaluates to @code{nan}, the ``indeterminate'' symbol. Various other +functions can also return infinities in this mode; for example, +@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again, +note that @samp{exp(inf) = inf} regardless of infinite mode because +this calculation has infinity as an input. + +@cindex Positive infinite mode +The @kbd{m i} command with a numeric prefix argument of zero, +i.e., @kbd{C-u 0 m i}, turns on a ``positive infinite mode'' in +which zero is treated as positive instead of being directionless. +Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode. +Note that zero never actually has a sign in Calc; there are no +separate representations for @i{+0} and @i{-0}. Positive +infinite mode merely changes the interpretation given to the +single symbol, @samp{0}. One consequence of this is that, while +you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0} +is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}. + +@node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes +@subsection Symbolic Mode + +@noindent +@cindex Symbolic mode +@cindex Inexact results +Calculations are normally performed numerically wherever possible. +For example, the @code{calc-sqrt} command, or @code{sqrt} function in an +algebraic expression, produces a numeric answer if the argument is a +number or a symbolic expression if the argument is an expression: +@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}. + +@kindex m s +@pindex calc-symbolic-mode +In @dfn{symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode}) +command, functions which would produce inexact, irrational results are +left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes +@samp{sqrt(2)}. + +@kindex N +@pindex calc-eval-num +The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically +the expression at the top of the stack, by temporarily disabling +@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}). +Given a numeric prefix argument, it also +sets the floating-point precision to the specified value for the duration +of the command.@refill + +To evaluate a formula numerically without expanding the variables it +contains, you can use the key sequence @kbd{m s a v m s} (this uses +@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate +variables.) + +@node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes +@subsection Matrix and Scalar Modes + +@noindent +@cindex Matrix mode +@cindex Scalar mode +Calc sometimes makes assumptions during algebraic manipulation that +are awkward or incorrect when vectors and matrices are involved. +Calc has two modes, @dfn{matrix mode} and @dfn{scalar mode}, which +modify its behavior around vectors in useful ways. + +@kindex m v +@pindex calc-matrix-mode +Press @kbd{m v} (@code{calc-matrix-mode}) once to enter matrix mode. +In this mode, all objects are assumed to be matrices unless provably +otherwise. One major effect is that Calc will no longer consider +multiplication to be commutative. (Recall that in matrix arithmetic, +@samp{A*B} is not the same as @samp{B*A}.) This assumption affects +rewrite rules and algebraic simplification. Another effect of this +mode is that calculations that would normally produce constants like +0 and 1 (e.g., @cite{a - a} and @cite{a / a}, respectively) will now +produce function calls that represent ``generic'' zero or identity +matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function +@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n} +identity matrix; if @var{n} is omitted, it doesn't know what +dimension to use and so the @code{idn} call remains in symbolic +form. However, if this generic identity matrix is later combined +with a matrix whose size is known, it will be converted into +a true identity matrix of the appropriate size. On the other hand, +if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc +will assume it really was a scalar after all and produce, e.g., 3. + +Press @kbd{m v} a second time to get scalar mode. Here, objects are +assumed @emph{not} to be vectors or matrices unless provably so. +For example, normally adding a variable to a vector, as in +@samp{[x, y, z] + a}, will leave the sum in symbolic form because +as far as Calc knows, @samp{a} could represent either a number or +another 3-vector. In scalar mode, @samp{a} is assumed to be a +non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}. + +Press @kbd{m v} a third time to return to the normal mode of operation. + +If you press @kbd{m v} with a numeric prefix argument @var{n}, you +get a special ``dimensioned matrix mode'' in which matrices of +unknown size are assumed to be @var{n}x@var{n} square matrices. +Then, the function call @samp{idn(1)} will expand into an actual +matrix rather than representing a ``generic'' matrix. + +@cindex Declaring scalar variables +Of course these modes are approximations to the true state of +affairs, which is probably that some quantities will be matrices +and others will be scalars. One solution is to ``declare'' +certain variables or functions to be scalar-valued. +@xref{Declarations}, to see how to make declarations in Calc. + +There is nothing stopping you from declaring a variable to be +scalar and then storing a matrix in it; however, if you do, the +results you get from Calc may not be valid. Suppose you let Calc +get the result @samp{[x+a, y+a, z+a]} shown above, and then stored +@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as +for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken +your earlier promise to Calc that @samp{a} would be scalar. + +Another way to mix scalars and matrices is to use selections +(@pxref{Selecting Subformulas}). Use matrix mode when operating on +your formula normally; then, to apply scalar mode to a certain part +of the formula without affecting the rest just select that part, +change into scalar mode and press @kbd{=} to resimplify the part +under this mode, then change back to matrix mode before deselecting. + +@node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes +@subsection Automatic Recomputation + +@noindent +The @dfn{evaluates-to} operator, @samp{=>}, has the special +property that any @samp{=>} formulas on the stack are recomputed +whenever variable values or mode settings that might affect them +are changed. @xref{Evaluates-To Operator}. + +@kindex m C +@pindex calc-auto-recompute +The @kbd{m C} (@code{calc-auto-recompute}) command turns this +automatic recomputation on and off. If you turn it off, Calc will +not update @samp{=>} operators on the stack (nor those in the +attached Embedded Mode buffer, if there is one). They will not +be updated unless you explicitly do so by pressing @kbd{=} or until +you press @kbd{m C} to turn recomputation back on. (While automatic +recomputation is off, you can think of @kbd{m C m C} as a command +to update all @samp{=>} operators while leaving recomputation off.) + +To update @samp{=>} operators in an Embedded buffer while +automatic recomputation is off, use @w{@kbd{M-# u}}. +@xref{Embedded Mode}. + +@node Working Message, , Automatic Recomputation, Calculation Modes +@subsection Working Messages + +@noindent +@cindex Performance +@cindex Working messages +Since the Calculator is written entirely in Emacs Lisp, which is not +designed for heavy numerical work, many operations are quite slow. +The Calculator normally displays the message @samp{Working...} in the +echo area during any command that may be slow. In addition, iterative +operations such as square roots and trigonometric functions display the +intermediate result at each step. Both of these types of messages can +be disabled if you find them distracting. + +@kindex m w +@pindex calc-working +Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to +disable all ``working'' messages. Use a numeric prefix of 1 to enable +only the plain @samp{Working...} message. Use a numeric prefix of 2 to +see intermediate results as well. With no numeric prefix this displays +the current mode.@refill + +While it may seem that the ``working'' messages will slow Calc down +considerably, experiments have shown that their impact is actually +quite small. But if your terminal is slow you may find that it helps +to turn the messages off. + +@node Simplification Modes, Declarations, Calculation Modes, Mode Settings +@section Simplification Modes + +@noindent +The current @dfn{simplification mode} controls how numbers and formulas +are ``normalized'' when being taken from or pushed onto the stack. +Some normalizations are unavoidable, such as rounding floating-point +results to the current precision, and reducing fractions to simplest +form. Others, such as simplifying a formula like @cite{a+a} (or @cite{2+3}), +are done by default but can be turned off when necessary. + +When you press a key like @kbd{+} when @cite{2} and @cite{3} are on the +stack, Calc pops these numbers, normalizes them, creates the formula +@cite{2+3}, normalizes it, and pushes the result. Of course the standard +rules for normalizing @cite{2+3} will produce the result @cite{5}. + +Simplification mode commands consist of the lower-case @kbd{m} prefix key +followed by a shifted letter. + +@kindex m O +@pindex calc-no-simplify-mode +The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional +simplifications. These would leave a formula like @cite{2+3} alone. In +fact, nothing except simple numbers are ever affected by normalization +in this mode. + +@kindex m N +@pindex calc-num-simplify-mode +The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification +of any formulas except those for which all arguments are constants. For +example, @cite{1+2} is simplified to @cite{3}, and @cite{a+(2-2)} is +simplified to @cite{a+0} but no further, since one argument of the sum +is not a constant. Unfortunately, @cite{(a+2)-2} is @emph{not} simplified +because the top-level @samp{-} operator's arguments are not both +constant numbers (one of them is the formula @cite{a+2}). +A constant is a number or other numeric object (such as a constant +error form or modulo form), or a vector all of whose +elements are constant.@refill + +@kindex m D +@pindex calc-default-simplify-mode +The @kbd{m D} (@code{calc-default-simplify-mode}) command restores the +default simplifications for all formulas. This includes many easy and +fast algebraic simplifications such as @cite{a+0} to @cite{a}, and +@cite{a + 2 a} to @cite{3 a}, as well as evaluating functions like +@cite{@t{deriv}(x^2, x)} to @cite{2 x}. + +@kindex m B +@pindex calc-bin-simplify-mode +The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the default +simplifications to a result and then, if the result is an integer, +uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according +to the current binary word size. @xref{Binary Functions}. Real numbers +are rounded to the nearest integer and then clipped; other kinds of +results (after the default simplifications) are left alone. + +@kindex m A +@pindex calc-alg-simplify-mode +The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does algebraic +simplification; it applies all the default simplifications, and also +the more powerful (and slower) simplifications made by @kbd{a s} +(@code{calc-simplify}). @xref{Algebraic Simplifications}. + +@kindex m E +@pindex calc-ext-simplify-mode +The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'' +algebraic simplification, as by the @kbd{a e} (@code{calc-simplify-extended}) +command. @xref{Unsafe Simplifications}. + +@kindex m U +@pindex calc-units-simplify-mode +The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units +simplification; it applies the command @kbd{u s} +(@code{calc-simplify-units}), which in turn +is a superset of @kbd{a s}. In this mode, variable names which +are identifiable as unit names (like @samp{mm} for ``millimeters'') +are simplified with their unit definitions in mind.@refill + +A common technique is to set the simplification mode down to the lowest +amount of simplification you will allow to be applied automatically, then +use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to +perform higher types of simplifications on demand. @xref{Algebraic +Definitions}, for another sample use of no-simplification mode.@refill + +@node Declarations, Display Modes, Simplification Modes, Mode Settings +@section Declarations + +@noindent +A @dfn{declaration} is a statement you make that promises you will +use a certain variable or function in a restricted way. This may +give Calc the freedom to do things that it couldn't do if it had to +take the fully general situation into account. + +@menu +* Declaration Basics:: +* Kinds of Declarations:: +* Functions for Declarations:: +@end menu + +@node Declaration Basics, Kinds of Declarations, Declarations, Declarations +@subsection Declaration Basics + +@noindent +@kindex s d +@pindex calc-declare-variable +The @kbd{s d} (@code{calc-declare-variable}) command is the easiest +way to make a declaration for a variable. This command prompts for +the variable name, then prompts for the declaration. The default +at the declaration prompt is the previous declaration, if any. +You can edit this declaration, or press @kbd{C-k} to erase it and +type a new declaration. (Or, erase it and press @key{RET} to clear +the declaration, effectively ``undeclaring'' the variable.) + +A declaration is in general a vector of @dfn{type symbols} and +@dfn{range} values. If there is only one type symbol or range value, +you can write it directly rather than enclosing it in a vector. +For example, @kbd{s d foo RET real RET} declares @code{foo} to +be a real number, and @kbd{s d bar RET [int, const, [1..6]] RET} +declares @code{bar} to be a constant integer between 1 and 6. +(Actually, you can omit the outermost brackets and Calc will +provide them for you: @kbd{s d bar RET int, const, [1..6] RET}.) + +@cindex @code{Decls} variable +@vindex Decls +Declarations in Calc are kept in a special variable called @code{Decls}. +This variable encodes the set of all outstanding declarations in +the form of a matrix. Each row has two elements: A variable or +vector of variables declared by that row, and the declaration +specifier as described above. You can use the @kbd{s D} command to +edit this variable if you wish to see all the declarations at once. +@xref{Operations on Variables}, for a description of this command +and the @kbd{s p} command that allows you to save your declarations +permanently if you wish. + +Items being declared can also be function calls. The arguments in +the call are ignored; the effect is to say that this function returns +values of the declared type for any valid arguments. The @kbd{s d} +command declares only variables, so if you wish to make a function +declaration you will have to edit the @code{Decls} matrix yourself. + +For example, the declaration matrix + +@group +@smallexample +[ [ foo, real ] + [ [j, k, n], int ] + [ f(1,2,3), [0 .. inf) ] ] +@end smallexample +@end group + +@noindent +declares that @code{foo} represents a real number, @code{j}, @code{k} +and @code{n} represent integers, and the function @code{f} always +returns a real number in the interval shown. + +@vindex All +If there is a declaration for the variable @code{All}, then that +declaration applies to all variables that are not otherwise declared. +It does not apply to function names. For example, using the row +@samp{[All, real]} says that all your variables are real unless they +are explicitly declared without @code{real} in some other row. +The @kbd{s d} command declares @code{All} if you give a blank +response to the variable-name prompt. + +@node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations +@subsection Kinds of Declarations + +@noindent +The type-specifier part of a declaration (that is, the second prompt +in the @kbd{s d} command) can be a type symbol, an interval, or a +vector consisting of zero or more type symbols followed by zero or +more intervals or numbers that represent the set of possible values +for the variable. + +@group +@smallexample +[ [ a, [1, 2, 3, 4, 5] ] + [ b, [1 .. 5] ] + [ c, [int, 1 .. 5] ] ] +@end smallexample +@end group + +Here @code{a} is declared to contain one of the five integers shown; +@code{b} is any number in the interval from 1 to 5 (any real number +since we haven't specified), and @code{c} is any integer in that +interval. Thus the declarations for @code{a} and @code{c} are +nearly equivalent (see below). + +The type-specifier can be the empty vector @samp{[]} to say that +nothing is known about a given variable's value. This is the same +as not declaring the variable at all except that it overrides any +@code{All} declaration which would otherwise apply. + +The initial value of @code{Decls} is the empty vector @samp{[]}. +If @code{Decls} has no stored value or if the value stored in it +is not valid, it is ignored and there are no declarations as far +as Calc is concerned. (The @kbd{s d} command will replace such a +malformed value with a fresh empty matrix, @samp{[]}, before recording +the new declaration.) Unrecognized type symbols are ignored. + +The following type symbols describe what sorts of numbers will be +stored in a variable: + +@table @code +@item int +Integers. +@item numint +Numerical integers. (Integers or integer-valued floats.) +@item frac +Fractions. (Rational numbers which are not integers.) +@item rat +Rational numbers. (Either integers or fractions.) +@item float +Floating-point numbers. +@item real +Real numbers. (Integers, fractions, or floats. Actually, +intervals and error forms with real components also count as +reals here.) +@item pos +Positive real numbers. (Strictly greater than zero.) +@item nonneg +Nonnegative real numbers. (Greater than or equal to zero.) +@item number +Numbers. (Real or complex.) +@end table + +Calc uses this information to determine when certain simplifications +of formulas are safe. For example, @samp{(x^y)^z} cannot be +simplified to @samp{x^(y z)} in general; for example, +@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @i{-3}. +However, this simplification @emph{is} safe if @code{z} is known +to be an integer, or if @code{x} is known to be a nonnegative +real number. If you have given declarations that allow Calc to +deduce either of these facts, Calc will perform this simplification +of the formula. + +Calc can apply a certain amount of logic when using declarations. +For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n} +has been declared @code{int}; Calc knows that an integer times an +integer, plus an integer, must always be an integer. (In fact, +Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since +it is able to determine that @samp{2n+1} must be an odd integer.) + +Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)} +because Calc knows that the @code{abs} function always returns a +nonnegative real. If you had a @code{myabs} function that also had +this property, you could get Calc to recognize it by adding the row +@samp{[myabs(), nonneg]} to the @code{Decls} matrix. + +One instance of this simplification is @samp{sqrt(x^2)} (since the +@code{sqrt} function is effectively a one-half power). Normally +Calc leaves this formula alone. After the command +@kbd{s d x RET real RET}, however, it can simplify the formula to +@samp{abs(x)}. And after @kbd{s d x RET nonneg RET}, Calc can +simplify this formula all the way to @samp{x}. + +If there are any intervals or real numbers in the type specifier, +they comprise the set of possible values that the variable or +function being declared can have. In particular, the type symbol +@code{real} is effectively the same as the range @samp{[-inf .. inf]} +(note that infinity is included in the range of possible values); +@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is +the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is +redundant because the fact that the variable is real can be +deduced just from the interval, but @samp{[int, [-5 .. 5]]} and +@samp{[rat, [-5 .. 5]]} are useful combinations. + +Note that the vector of intervals or numbers is in the same format +used by Calc's set-manipulation commands. @xref{Set Operations}. + +The type specifier @samp{[1, 2, 3]} is equivalent to +@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}. +In other words, the range of possible values means only that +the variable's value must be numerically equal to a number in +that range, but not that it must be equal in type as well. +Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])} +and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.'' + +If you use a conflicting combination of type specifiers, the +results are unpredictable. An example is @samp{[pos, [0 .. 5]]}, +where the interval does not lie in the range described by the +type symbol. + +``Real'' declarations mostly affect simplifications involving powers +like the one described above. Another case where they are used +is in the @kbd{a P} command which returns a list of all roots of a +polynomial; if the variable has been declared real, only the real +roots (if any) will be included in the list. + +``Integer'' declarations are used for simplifications which are valid +only when certain values are integers (such as @samp{(x^y)^z} +shown above). + +Another command that makes use of declarations is @kbd{a s}, when +simplifying equations and inequalities. It will cancel @code{x} +from both sides of @samp{a x = b x} only if it is sure @code{x} +is non-zero, say, because it has a @code{pos} declaration. +To declare specifically that @code{x} is real and non-zero, +use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the +current notation to say that @code{x} is nonzero but not necessarily +real.) The @kbd{a e} command does ``unsafe'' simplifications, +including cancelling @samp{x} from the equation when @samp{x} is +not known to be nonzero. + +Another set of type symbols distinguish between scalars and vectors. + +@table @code +@item scalar +The value is not a vector. +@item vector +The value is a vector. +@item matrix +The value is a matrix (a rectangular vector of vectors). +@end table + +These type symbols can be combined with the other type symbols +described above; @samp{[int, matrix]} describes an object which +is a matrix of integers. + +Scalar/vector declarations are used to determine whether certain +algebraic operations are safe. For example, @samp{[a, b, c] + x} +is normally not simplified to @samp{[a + x, b + x, c + x]}, but +it will be if @code{x} has been declared @code{scalar}. On the +other hand, multiplication is usually assumed to be commutative, +but the terms in @samp{x y} will never be exchanged if both @code{x} +and @code{y} are known to be vectors or matrices. (Calc currently +never distinguishes between @code{vector} and @code{matrix} +declarations.) + +@xref{Matrix Mode}, for a discussion of ``matrix mode'' and +``scalar mode,'' which are similar to declaring @samp{[All, matrix]} +or @samp{[All, scalar]} but much more convenient. + +One more type symbol that is recognized is used with the @kbd{H a d} +command for taking total derivatives of a formula. @xref{Calculus}. + +@table @code +@item const +The value is a constant with respect to other variables. +@end table + +Calc does not check the declarations for a variable when you store +a value in it. However, storing @i{-3.5} in a variable that has +been declared @code{pos}, @code{int}, or @code{matrix} may have +unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @cite{3.5} +if it substitutes the value first, or to @cite{-3.5} if @code{x} +was declared @code{pos} and the formula @samp{sqrt(x^2)} is +simplified to @samp{x} before the value is substituted. Before +using a variable for a new purpose, it is best to use @kbd{s d} +or @kbd{s D} to check to make sure you don't still have an old +declaration for the variable that will conflict with its new meaning. + +@node Functions for Declarations, , Kinds of Declarations, Declarations +@subsection Functions for Declarations + +@noindent +Calc has a set of functions for accessing the current declarations +in a convenient manner. These functions return 1 if the argument +can be shown to have the specified property, or 0 if the argument +can be shown @emph{not} to have that property; otherwise they are +left unevaluated. These functions are suitable for use with rewrite +rules (@pxref{Conditional Rewrite Rules}) or programming constructs +(@pxref{Conditionals in Macros}). They can be entered only using +algebraic notation. @xref{Logical Operations}, for functions +that perform other tests not related to declarations. + +For example, @samp{dint(17)} returns 1 because 17 is an integer, as +do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared +@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0. +Calc consults knowledge of its own built-in functions as well as your +own declarations: @samp{dint(floor(x))} returns 1. + +@c @starindex +@tindex dint +@c @starindex +@tindex dnumint +@c @starindex +@tindex dnatnum +The @code{dint} function checks if its argument is an integer. +The @code{dnatnum} function checks if its argument is a natural +number, i.e., a nonnegative integer. The @code{dnumint} function +checks if its argument is numerically an integer, i.e., either an +integer or an integer-valued float. Note that these and the other +data type functions also accept vectors or matrices composed of +suitable elements, and that real infinities @samp{inf} and @samp{-inf} +are considered to be integers for the purposes of these functions. + +@c @starindex +@tindex drat +The @code{drat} function checks if its argument is rational, i.e., +an integer or fraction. Infinities count as rational, but intervals +and error forms do not. + +@c @starindex +@tindex dreal +The @code{dreal} function checks if its argument is real. This +includes integers, fractions, floats, real error forms, and intervals. + +@c @starindex +@tindex dimag +The @code{dimag} function checks if its argument is imaginary, +i.e., is mathematically equal to a real number times @cite{i}. + +@c @starindex +@tindex dpos +@c @starindex +@tindex dneg +@c @starindex +@tindex dnonneg +The @code{dpos} function checks for positive (but nonzero) reals. +The @code{dneg} function checks for negative reals. The @code{dnonneg} +function checks for nonnegative reals, i.e., reals greater than or +equal to zero. Note that the @kbd{a s} command can simplify an +expression like @cite{x > 0} to 1 or 0 using @code{dpos}, and that +@kbd{a s} is effectively applied to all conditions in rewrite rules, +so the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg} +are rarely necessary. + +@c @starindex +@tindex dnonzero +The @code{dnonzero} function checks that its argument is nonzero. +This includes all nonzero real or complex numbers, all intervals that +do not include zero, all nonzero modulo forms, vectors all of whose +elements are nonzero, and variables or formulas whose values can be +deduced to be nonzero. It does not include error forms, since they +represent values which could be anything including zero. (This is +also the set of objects considered ``true'' in conditional contexts.) + +@c @starindex +@tindex deven +@c @starindex +@tindex dodd +The @code{deven} function returns 1 if its argument is known to be +an even integer (or integer-valued float); it returns 0 if its argument +is known not to be even (because it is known to be odd or a non-integer). +The @kbd{a s} command uses this to simplify a test of the form +@samp{x % 2 = 0}. There is also an analogous @code{dodd} function. + +@c @starindex +@tindex drange +The @code{drange} function returns a set (an interval or a vector +of intervals and/or numbers; @pxref{Set Operations}) that describes +the set of possible values of its argument. If the argument is +a variable or a function with a declaration, the range is copied +from the declaration. Otherwise, the possible signs of the +expression are determined using a method similar to @code{dpos}, +etc., and a suitable set like @samp{[0 .. inf]} is returned. If +the expression is not provably real, the @code{drange} function +remains unevaluated. + +@c @starindex +@tindex dscalar +The @code{dscalar} function returns 1 if its argument is provably +scalar, or 0 if its argument is provably non-scalar. It is left +unevaluated if this cannot be determined. (If matrix mode or scalar +mode are in effect, this function returns 1 or 0, respectively, +if it has no other information.) When Calc interprets a condition +(say, in a rewrite rule) it considers an unevaluated formula to be +``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is +provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a} +is provably non-scalar; both are ``false'' if there is insufficient +information to tell. + +@node Display Modes, Language Modes, Declarations, Mode Settings +@section Display Modes + +@noindent +The commands in this section are two-key sequences beginning with the +@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b} +(@code{calc-line-breaking}) commands are described elsewhere; +@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively. +Display formats for vectors and matrices are also covered elsewhere; +@pxref{Vector and Matrix Formats}.@refill + +One thing all display modes have in common is their treatment of the +@kbd{H} prefix. This prefix causes any mode command that would normally +refresh the stack to leave the stack display alone. The word ``Dirty'' +will appear in the mode line when Calc thinks the stack display may not +reflect the latest mode settings. + +@kindex d RET +@pindex calc-refresh-top +The @kbd{d RET} (@code{calc-refresh-top}) command reformats the +top stack entry according to all the current modes. Positive prefix +arguments reformat the top @var{n} entries; negative prefix arguments +reformat the specified entry, and a prefix of zero is equivalent to +@kbd{d SPC} (@code{calc-refresh}), which reformats the entire stack. +For example, @kbd{H d s M-2 d RET} changes to scientific notation +but reformats only the top two stack entries in the new mode. + +The @kbd{I} prefix has another effect on the display modes. The mode +is set only temporarily; the top stack entry is reformatted according +to that mode, then the original mode setting is restored. In other +words, @kbd{I d s} is equivalent to @kbd{H d s d RET H d @var{(old mode)}}. + +@menu +* Radix Modes:: +* Grouping Digits:: +* Float Formats:: +* Complex Formats:: +* Fraction Formats:: +* HMS Formats:: +* Date Formats:: +* Truncating the Stack:: +* Justification:: +* Labels:: +@end menu + +@node Radix Modes, Grouping Digits, Display Modes, Display Modes +@subsection Radix Modes + +@noindent +@cindex Radix display +@cindex Non-decimal numbers +@cindex Decimal and non-decimal numbers +Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10}) +notation. Calc can actually display in any radix from two (binary) to 36. +When the radix is above 10, the letters @code{A} to @code{Z} are used as +digits. When entering such a number, letter keys are interpreted as +potential digits rather than terminating numeric entry mode. + +@kindex d 2 +@kindex d 8 +@kindex d 6 +@kindex d 0 +@cindex Hexadecimal integers +@cindex Octal integers +The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select +binary, octal, hexadecimal, and decimal as the current display radix, +respectively. Numbers can always be entered in any radix, though the +current radix is used as a default if you press @kbd{#} without any initial +digits. A number entered without a @kbd{#} is @emph{always} interpreted +as decimal.@refill + +@kindex d r +@pindex calc-radix +To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter +an integer from 2 to 36. You can specify the radix as a numeric prefix +argument; otherwise you will be prompted for it. + +@kindex d z +@pindex calc-leading-zeros +@cindex Leading zeros +Integers normally are displayed with however many digits are necessary to +represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros}) +command causes integers to be padded out with leading zeros according to the +current binary word size. (@xref{Binary Functions}, for a discussion of +word size.) If the absolute value of the word size is @cite{w}, all integers +are displayed with at least enough digits to represent @c{$2^w-1$} +@cite{(2^w)-1} in the +current radix. (Larger integers will still be displayed in their entirety.) + +@node Grouping Digits, Float Formats, Radix Modes, Display Modes +@subsection Grouping Digits + +@noindent +@kindex d g +@pindex calc-group-digits +@cindex Grouping digits +@cindex Digit grouping +Long numbers can be hard to read if they have too many digits. For +example, the factorial of 30 is 33 digits long! Press @kbd{d g} +(@code{calc-group-digits}) to enable @dfn{grouping} mode, in which digits +are displayed in clumps of 3 or 4 (depending on the current radix) +separated by commas. + +The @kbd{d g} command toggles grouping on and off. +With a numerix prefix of 0, this command displays the current state of +the grouping flag; with an argument of minus one it disables grouping; +with a positive argument @cite{N} it enables grouping on every @cite{N} +digits. For floating-point numbers, grouping normally occurs only +before the decimal point. A negative prefix argument @cite{-N} enables +grouping every @cite{N} digits both before and after the decimal point.@refill + +@kindex d , +@pindex calc-group-char +The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any +character as the grouping separator. The default is the comma character. +If you find it difficult to read vectors of large integers grouped with +commas, you may wish to use spaces or some other character instead. +This command takes the next character you type, whatever it is, and +uses it as the digit separator. As a special case, @kbd{d , \} selects +@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator. + +Please note that grouped numbers will not generally be parsed correctly +if re-read in textual form, say by the use of @kbd{M-# y} and @kbd{M-# g}. +(@xref{Kill and Yank}, for details on these commands.) One exception is +the @samp{\,} separator, which doesn't interfere with parsing because it +is ignored by @TeX{} language mode. + +@node Float Formats, Complex Formats, Grouping Digits, Display Modes +@subsection Float Formats + +@noindent +Floating-point quantities are normally displayed in standard decimal +form, with scientific notation used if the exponent is especially high +or low. All significant digits are normally displayed. The commands +in this section allow you to choose among several alternative display +formats for floats. + +@kindex d n +@pindex calc-normal-notation +The @kbd{d n} (@code{calc-normal-notation}) command selects the normal +display format. All significant figures in a number are displayed. +With a positive numeric prefix, numbers are rounded if necessary to +that number of significant digits. With a negative numerix prefix, +the specified number of significant digits less than the current +precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the +current precision is 12.) + +@kindex d f +@pindex calc-fix-notation +The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point +notation. The numeric argument is the number of digits after the +decimal point, zero or more. This format will relax into scientific +notation if a nonzero number would otherwise have been rounded all the +way to zero. Specifying a negative number of digits is the same as +for a positive number, except that small nonzero numbers will be rounded +to zero rather than switching to scientific notation. + +@kindex d s +@pindex calc-sci-notation +@cindex Scientific notation, display of +The @kbd{d s} (@code{calc-sci-notation}) command selects scientific +notation. A positive argument sets the number of significant figures +displayed, of which one will be before and the rest after the decimal +point. A negative argument works the same as for @kbd{d n} format. +The default is to display all significant digits. + +@kindex d e +@pindex calc-eng-notation +@cindex Engineering notation, display of +The @kbd{d e} (@code{calc-eng-notation}) command selects engineering +notation. This is similar to scientific notation except that the +exponent is rounded down to a multiple of three, with from one to three +digits before the decimal point. An optional numeric prefix sets the +number of significant digits to display, as for @kbd{d s}. + +It is important to distinguish between the current @emph{precision} and +the current @emph{display format}. After the commands @kbd{C-u 10 p} +and @kbd{C-u 6 d n} the Calculator computes all results to ten +significant figures but displays only six. (In fact, intermediate +calculations are often carried to one or two more significant figures, +but values placed on the stack will be rounded down to ten figures.) +Numbers are never actually rounded to the display precision for storage, +except by commands like @kbd{C-k} and @kbd{M-# y} which operate on the +actual displayed text in the Calculator buffer. + +@kindex d . +@pindex calc-point-char +The @kbd{d .} (@code{calc-point-char}) command selects the character used +as a decimal point. Normally this is a period; users in some countries +may wish to change this to a comma. Note that this is only a display +style; on entry, periods must always be used to denote floating-point +numbers, and commas to separate elements in a list. + +@node Complex Formats, Fraction Formats, Float Formats, Display Modes +@subsection Complex Formats + +@noindent +@kindex d c +@pindex calc-complex-notation +There are three supported notations for complex numbers in rectangular +form. The default is as a pair of real numbers enclosed in parentheses +and separated by a comma: @samp{(a,b)}. The @kbd{d c} +(@code{calc-complex-notation}) command selects this style.@refill + +@kindex d i +@pindex calc-i-notation +@kindex d j +@pindex calc-j-notation +The other notations are @kbd{d i} (@code{calc-i-notation}), in which +numbers are displayed in @samp{a+bi} form, and @kbd{d j} +(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred +in some disciplines.@refill + +@cindex @code{i} variable +@vindex i +Complex numbers are normally entered in @samp{(a,b)} format. +If you enter @samp{2+3i} as an algebraic formula, it will be stored as +the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate +this formula and you have not changed the variable @samp{i}, the @samp{i} +will be interpreted as @samp{(0,1)} and the formula will be simplified +to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not} +interpret the formula @samp{2 + 3 * i} as a complex number. +@xref{Variables}, under ``special constants.''@refill + +@node Fraction Formats, HMS Formats, Complex Formats, Display Modes +@subsection Fraction Formats + +@noindent +@kindex d o +@pindex calc-over-notation +Display of fractional numbers is controlled by the @kbd{d o} +(@code{calc-over-notation}) command. By default, a number like +eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command +prompts for a one- or two-character format. If you give one character, +that character is used as the fraction separator. Common separators are +@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be +used regardless of the display format; in particular, the @kbd{/} is used +for RPN-style division, @emph{not} for entering fractions.) + +If you give two characters, fractions use ``integer-plus-fractional-part'' +notation. For example, the format @samp{+/} would display eight thirds +as @samp{2+2/3}. If two colons are present in a number being entered, +the number is interpreted in this form (so that the entries @kbd{2:2:3} +and @kbd{8:3} are equivalent). + +It is also possible to follow the one- or two-character format with +a number. For example: @samp{:10} or @samp{+/3}. In this case, +Calc adjusts all fractions that are displayed to have the specified +denominator, if possible. Otherwise it adjusts the denominator to +be a multiple of the specified value. For example, in @samp{:6} mode +the fraction @cite{1:6} will be unaffected, but @cite{2:3} will be +displayed as @cite{4:6}, @cite{1:2} will be displayed as @cite{3:6}, +and @cite{1:8} will be displayed as @cite{3:24}. Integers are also +affected by this mode: 3 is displayed as @cite{18:6}. Note that the +format @samp{:1} writes fractions the same as @samp{:}, but it writes +integers as @cite{n:1}. + +The fraction format does not affect the way fractions or integers are +stored, only the way they appear on the screen. The fraction format +never affects floats. + +@node HMS Formats, Date Formats, Fraction Formats, Display Modes +@subsection HMS Formats + +@noindent +@kindex d h +@pindex calc-hms-notation +The @kbd{d h} (@code{calc-hms-notation}) command controls the display of +HMS (hours-minutes-seconds) forms. It prompts for a string which +consists basically of an ``hours'' marker, optional punctuation, a +``minutes'' marker, more optional punctuation, and a ``seconds'' marker. +Punctuation is zero or more spaces, commas, or semicolons. The hours +marker is one or more non-punctuation characters. The minutes and +seconds markers must be single non-punctuation characters. + +The default HMS format is @samp{@@ ' "}, producing HMS values of the form +@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same +value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o} +keys are recognized as synonyms for @kbd{@@} regardless of display format. +The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and +@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has +already been typed; otherwise, they have their usual meanings +(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and +@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.'' +The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or +@kbd{o}) has already been pressed; otherwise it means to switch to algebraic +entry. + +@node Date Formats, Truncating the Stack, HMS Formats, Display Modes +@subsection Date Formats + +@noindent +@kindex d d +@pindex calc-date-notation +The @kbd{d d} (@code{calc-date-notation}) command controls the display +of date forms (@pxref{Date Forms}). It prompts for a string which +contains letters that represent the various parts of a date and time. +To show which parts should be omitted when the form represents a pure +date with no time, parts of the string can be enclosed in @samp{< >} +marks. If you don't include @samp{< >} markers in the format, Calc +guesses at which parts, if any, should be omitted when formatting +pure dates. + +The default format is: @samp{<H:mm:SSpp >Www Mmm D, YYYY}. +An example string in this format is @samp{3:32pm Wed Jan 9, 1991}. +If you enter a blank format string, this default format is +reestablished. + +Calc uses @samp{< >} notation for nameless functions as well as for +dates. @xref{Specifying Operators}. To avoid confusion with nameless +functions, your date formats should avoid using the @samp{#} character. + +@menu +* Date Formatting Codes:: +* Free-Form Dates:: +* Standard Date Formats:: +@end menu + +@node Date Formatting Codes, Free-Form Dates, Date Formats, Date Formats +@subsubsection Date Formatting Codes + +@noindent +When displaying a date, the current date format is used. All +characters except for letters and @samp{<} and @samp{>} are +copied literally when dates are formatted. The portion between +@samp{< >} markers is omitted for pure dates, or included for +date/time forms. Letters are interpreted according to the table +below. + +When dates are read in during algebraic entry, Calc first tries to +match the input string to the current format either with or without +the time part. The punctuation characters (including spaces) must +match exactly; letter fields must correspond to suitable text in +the input. If this doesn't work, Calc checks if the input is a +simple number; if so, the number is interpreted as a number of days +since Jan 1, 1 AD. Otherwise, Calc tries a much more relaxed and +flexible algorithm which is described in the next section. + +Weekday names are ignored during reading. + +Two-digit year numbers are interpreted as lying in the range +from 1941 to 2039. Years outside that range are always +entered and displayed in full. Year numbers with a leading +@samp{+} sign are always interpreted exactly, allowing the +entry and display of the years 1 through 99 AD. + +Here is a complete list of the formatting codes for dates: + +@table @asis +@item Y +Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD. +@item YY +Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD. +@item BY +Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD. +@item YYY +Year: ``1991'' for 1991, ``23'' for 23 AD. +@item YYYY +Year: ``1991'' for 1991, ``+23'' for 23 AD. +@item aa +Year: ``ad'' or blank. +@item AA +Year: ``AD'' or blank. +@item aaa +Year: ``ad '' or blank. (Note trailing space.) +@item AAA +Year: ``AD '' or blank. +@item aaaa +Year: ``a.d.'' or blank. +@item AAAA +Year: ``A.D.'' or blank. +@item bb +Year: ``bc'' or blank. +@item BB +Year: ``BC'' or blank. +@item bbb +Year: `` bc'' or blank. (Note leading space.) +@item BBB +Year: `` BC'' or blank. +@item bbbb +Year: ``b.c.'' or blank. +@item BBBB +Year: ``B.C.'' or blank. +@item M +Month: ``8'' for August. +@item MM +Month: ``08'' for August. +@item BM +Month: `` 8'' for August. +@item MMM +Month: ``AUG'' for August. +@item Mmm +Month: ``Aug'' for August. +@item mmm +Month: ``aug'' for August. +@item MMMM +Month: ``AUGUST'' for August. +@item Mmmm +Month: ``August'' for August. +@item D +Day: ``7'' for 7th day of month. +@item DD +Day: ``07'' for 7th day of month. +@item BD +Day: `` 7'' for 7th day of month. +@item W +Weekday: ``0'' for Sunday, ``6'' for Saturday. +@item WWW +Weekday: ``SUN'' for Sunday. +@item Www +Weekday: ``Sun'' for Sunday. +@item www +Weekday: ``sun'' for Sunday. +@item WWWW +Weekday: ``SUNDAY'' for Sunday. +@item Wwww +Weekday: ``Sunday'' for Sunday. +@item d +Day of year: ``34'' for Feb. 3. +@item ddd +Day of year: ``034'' for Feb. 3. +@item bdd +Day of year: `` 34'' for Feb. 3. +@item h +Hour: ``5'' for 5 AM; ``17'' for 5 PM. +@item hh +Hour: ``05'' for 5 AM; ``17'' for 5 PM. +@item bh +Hour: `` 5'' for 5 AM; ``17'' for 5 PM. +@item H +Hour: ``5'' for 5 AM and 5 PM. +@item HH +Hour: ``05'' for 5 AM and 5 PM. +@item BH +Hour: `` 5'' for 5 AM and 5 PM. +@item p +AM/PM: ``a'' or ``p''. +@item P +AM/PM: ``A'' or ``P''. +@item pp +AM/PM: ``am'' or ``pm''. +@item PP +AM/PM: ``AM'' or ``PM''. +@item pppp +AM/PM: ``a.m.'' or ``p.m.''. +@item PPPP +AM/PM: ``A.M.'' or ``P.M.''. +@item m +Minutes: ``7'' for 7. +@item mm +Minutes: ``07'' for 7. +@item bm +Minutes: `` 7'' for 7. +@item s +Seconds: ``7'' for 7; ``7.23'' for 7.23. +@item ss +Seconds: ``07'' for 7; ``07.23'' for 7.23. +@item bs +Seconds: `` 7'' for 7; `` 7.23'' for 7.23. +@item SS +Optional seconds: ``07'' for 7; blank for 0. +@item BS +Optional seconds: `` 7'' for 7; blank for 0. +@item N +Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991. +@item n +Numeric date: ``726842'' for any time on Wed Jan 9, 1991. +@item J +Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991. +@item j +Julian date: ``2448266'' for any time on Wed Jan 9, 1991. +@item U +Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991. +@item X +Brackets suppression. An ``X'' at the front of the format +causes the surrounding @w{@samp{< >}} delimiters to be omitted +when formatting dates. Note that the brackets are still +required for algebraic entry. +@end table + +If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the +colon is also omitted if the seconds part is zero. + +If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents +appear in the format, then negative year numbers are displayed +without a minus sign. Note that ``aa'' and ``bb'' are mutually +exclusive. Some typical usages would be @samp{YYYY AABB}; +@samp{AAAYYYYBBB}; @samp{YYYYBBB}. + +The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,'' +``mm,'' ``ss,'' and ``SS'' actually match any number of digits during +reading unless several of these codes are strung together with no +punctuation in between, in which case the input must have exactly as +many digits as there are letters in the format. + +The ``j,'' ``J,'' and ``U'' formats do not make any time zone +adjustment. They effectively use @samp{julian(x,0)} and +@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}. + +@node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats +@subsubsection Free-Form Dates + +@noindent +When reading a date form during algebraic entry, Calc falls back +on the algorithm described here if the input does not exactly +match the current date format. This algorithm generally +``does the right thing'' and you don't have to worry about it, +but it is described here in full detail for the curious. + +Calc does not distinguish between upper- and lower-case letters +while interpreting dates. + +First, the time portion, if present, is located somewhere in the +text and then removed. The remaining text is then interpreted as +the date. + +A time is of the form @samp{hh:mm:ss}, possibly with the seconds +part omitted and possibly with an AM/PM indicator added to indicate +12-hour time. If the AM/PM is present, the minutes may also be +omitted. The AM/PM part may be any of the words @samp{am}, +@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be +abbreviated to one letter, and the alternate forms @samp{a.m.}, +@samp{p.m.}, and @samp{mid} are also understood. Obviously +@samp{noon} and @samp{midnight} are allowed only on 12:00:00. +The words @samp{noon}, @samp{mid}, and @samp{midnight} are also +recognized with no number attached. + +If there is no AM/PM indicator, the time is interpreted in 24-hour +format. + +To read the date portion, all words and numbers are isolated +from the string; other characters are ignored. All words must +be either month names or day-of-week names (the latter of which +are ignored). Names can be written in full or as three-letter +abbreviations. + +Large numbers, or numbers with @samp{+} or @samp{-} signs, +are interpreted as years. If one of the other numbers is +greater than 12, then that must be the day and the remaining +number in the input is therefore the month. Otherwise, Calc +assumes the month, day and year are in the same order that they +appear in the current date format. If the year is omitted, the +current year is taken from the system clock. + +If there are too many or too few numbers, or any unrecognizable +words, then the input is rejected. + +If there are any large numbers (of five digits or more) other than +the year, they are ignored on the assumption that they are something +like Julian dates that were included along with the traditional +date components when the date was formatted. + +One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.} +may optionally be used; the latter two are equivalent to a +minus sign on the year value. + +If you always enter a four-digit year, and use a name instead +of a number for the month, there is no danger of ambiguity. + +@node Standard Date Formats, , Free-Form Dates, Date Formats +@subsubsection Standard Date Formats + +@noindent +There are actually ten standard date formats, numbered 0 through 9. +Entering a blank line at the @kbd{d d} command's prompt gives +you format number 1, Calc's usual format. You can enter any digit +to select the other formats. + +To create your own standard date formats, give a numeric prefix +argument from 0 to 9 to the @w{@kbd{d d}} command. The format you +enter will be recorded as the new standard format of that +number, as well as becoming the new current date format. +You can save your formats permanently with the @w{@kbd{m m}} +command (@pxref{Mode Settings}). + +@table @asis +@item 0 +@samp{N} (Numerical format) +@item 1 +@samp{<H:mm:SSpp >Www Mmm D, YYYY} (American format) +@item 2 +@samp{D Mmm YYYY<, h:mm:SS>} (European format) +@item 3 +@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format) +@item 4 +@samp{M/D/Y< H:mm:SSpp>} (American slashed format) +@item 5 +@samp{D.M.Y< h:mm:SS>} (European dotted format) +@item 6 +@samp{M-D-Y< H:mm:SSpp>} (American dashed format) +@item 7 +@samp{D-M-Y< h:mm:SS>} (European dashed format) +@item 8 +@samp{j<, h:mm:ss>} (Julian day plus time) +@item 9 +@samp{YYddd< hh:mm:ss>} (Year-day format) +@end table + +@node Truncating the Stack, Justification, Date Formats, Display Modes +@subsection Truncating the Stack + +@noindent +@kindex d t +@pindex calc-truncate-stack +@cindex Truncating the stack +@cindex Narrowing the stack +The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@: +line that marks the top-of-stack up or down in the Calculator buffer. +The number right above that line is considered to the be at the top of +the stack. Any numbers below that line are ``hidden'' from all stack +operations. This is similar to the Emacs ``narrowing'' feature, except +that the values below the @samp{.} are @emph{visible}, just temporarily +frozen. This feature allows you to keep several independent calculations +running at once in different parts of the stack, or to apply a certain +command to an element buried deep in the stack.@refill + +Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor +is on. Thus, this line and all those below it become hidden. To un-hide +these lines, move down to the end of the buffer and press @w{@kbd{d t}}. +With a positive numeric prefix argument @cite{n}, @kbd{d t} hides the +bottom @cite{n} values in the buffer. With a negative argument, it hides +all but the top @cite{n} values. With an argument of zero, it hides zero +values, i.e., moves the @samp{.} all the way down to the bottom.@refill + +@kindex d [ +@pindex calc-truncate-up +@kindex d ] +@pindex calc-truncate-down +The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]} +(@code{calc-truncate-down}) commands move the @samp{.} up or down one +line at a time (or several lines with a prefix argument).@refill + +@node Justification, Labels, Truncating the Stack, Display Modes +@subsection Justification + +@noindent +@kindex d < +@pindex calc-left-justify +@kindex d = +@pindex calc-center-justify +@kindex d > +@pindex calc-right-justify +Values on the stack are normally left-justified in the window. You can +control this arrangement by typing @kbd{d <} (@code{calc-left-justify}), +@kbd{d >} (@code{calc-right-justify}), or @kbd{d =} +(@code{calc-center-justify}). For example, in right-justification mode, +stack entries are displayed flush-right against the right edge of the +window.@refill + +If you change the width of the Calculator window you may have to type +@kbd{d SPC} (@code{calc-refresh}) to re-align right-justified or centered +text. + +Right-justification is especially useful together with fixed-point +notation (see @code{d f}; @code{calc-fix-notation}). With these modes +together, the decimal points on numbers will always line up. + +With a numeric prefix argument, the justification commands give you +a little extra control over the display. The argument specifies the +horizontal ``origin'' of a display line. It is also possible to +specify a maximum line width using the @kbd{d b} command (@pxref{Normal +Language Modes}). For reference, the precise rules for formatting and +breaking lines are given below. Notice that the interaction between +origin and line width is slightly different in each justification +mode. + +In left-justified mode, the line is indented by a number of spaces +given by the origin (default zero). If the result is longer than the +maximum line width, if given, or too wide to fit in the Calc window +otherwise, then it is broken into lines which will fit; each broken +line is indented to the origin. + +In right-justified mode, lines are shifted right so that the rightmost +character is just before the origin, or just before the current +window width if no origin was specified. If the line is too long +for this, then it is broken; the current line width is used, if +specified, or else the origin is used as a width if that is +specified, or else the line is broken to fit in the window. + +In centering mode, the origin is the column number of the center of +each stack entry. If a line width is specified, lines will not be +allowed to go past that width; Calc will either indent less or +break the lines if necessary. If no origin is specified, half the +line width or Calc window width is used. + +Note that, in each case, if line numbering is enabled the display +is indented an additional four spaces to make room for the line +number. The width of the line number is taken into account when +positioning according to the current Calc window width, but not +when positioning by explicit origins and widths. In the latter +case, the display is formatted as specified, and then uniformly +shifted over four spaces to fit the line numbers. + +@node Labels, , Justification, Display Modes +@subsection Labels + +@noindent +@kindex d @{ +@pindex calc-left-label +The @kbd{d @{} (@code{calc-left-label}) command prompts for a string, +then displays that string to the left of every stack entry. If the +entries are left-justified (@pxref{Justification}), then they will +appear immediately after the label (unless you specified an origin +greater than the length of the label). If the entries are centered +or right-justified, the label appears on the far left and does not +affect the horizontal position of the stack entry. + +Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off. + +@kindex d @} +@pindex calc-right-label +The @kbd{d @}} (@code{calc-right-label}) command similarly adds a +label on the righthand side. It does not affect positioning of +the stack entries unless they are right-justified. Also, if both +a line width and an origin are given in right-justified mode, the +stack entry is justified to the origin and the righthand label is +justified to the line width. + +One application of labels would be to add equation numbers to +formulas you are manipulating in Calc and then copying into a +document (possibly using Embedded Mode). The equations would +typically be centered, and the equation numbers would be on the +left or right as you prefer. + +@node Language Modes, Modes Variable, Display Modes, Mode Settings +@section Language Modes + +@noindent +The commands in this section change Calc to use a different notation for +entry and display of formulas, corresponding to the conventions of some +other common language such as Pascal or @TeX{}. Objects displayed on the +stack or yanked from the Calculator to an editing buffer will be formatted +in the current language; objects entered in algebraic entry or yanked from +another buffer will be interpreted according to the current language. + +The current language has no effect on things written to or read from the +trail buffer, nor does it affect numeric entry. Only algebraic entry is +affected. You can make even algebraic entry ignore the current language +and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}. + +For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C +program; elsewhere in the program you need the derivatives of this formula +with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C} +to switch to C notation. Now use @code{C-u M-# g} to grab the formula +into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect +to the first variable, and @kbd{M-# y} to yank the formula for the derivative +back into your C program. Press @kbd{U} to undo the differentiation and +repeat with @kbd{a d a[2] @key{RET}} for the other derivative. + +Without being switched into C mode first, Calc would have misinterpreted +the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that +@code{atan} was equivalent to Calc's built-in @code{arctan} function, +and would have written the formula back with notations (like implicit +multiplication) which would not have been legal for a C program. + +As another example, suppose you are maintaining a C program and a @TeX{} +document, each of which needs a copy of the same formula. You can grab the +formula from the program in C mode, switch to @TeX{} mode, and yank the +formula into the document in @TeX{} math-mode format. + +Language modes are selected by typing the letter @kbd{d} followed by a +shifted letter key. + +@menu +* Normal Language Modes:: +* C FORTRAN Pascal:: +* TeX Language Mode:: +* Eqn Language Mode:: +* Mathematica Language Mode:: +* Maple Language Mode:: +* Compositions:: +* Syntax Tables:: +@end menu + +@node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes +@subsection Normal Language Modes + +@noindent +@kindex d N +@pindex calc-normal-language +The @kbd{d N} (@code{calc-normal-language}) command selects the usual +notation for Calc formulas, as described in the rest of this manual. +Matrices are displayed in a multi-line tabular format, but all other +objects are written in linear form, as they would be typed from the +keyboard. + +@kindex d O +@pindex calc-flat-language +@cindex Matrix display +The @kbd{d O} (@code{calc-flat-language}) command selects a language +identical with the normal one, except that matrices are written in +one-line form along with everything else. In some applications this +form may be more suitable for yanking data into other buffers. + +@kindex d b +@pindex calc-line-breaking +@cindex Line breaking +@cindex Breaking up long lines +Even in one-line mode, long formulas or vectors will still be split +across multiple lines if they exceed the width of the Calculator window. +The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking +feature on and off. (It works independently of the current language.) +If you give a numeric prefix argument of five or greater to the @kbd{d b} +command, that argument will specify the line width used when breaking +long lines. + +@kindex d B +@pindex calc-big-language +The @kbd{d B} (@code{calc-big-language}) command selects a language +which uses textual approximations to various mathematical notations, +such as powers, quotients, and square roots: + +@example + ____________ + | a + 1 2 + | ----- + c +\| b +@end example + +@noindent +in place of @samp{sqrt((a+1)/b + c^2)}. + +Subscripts like @samp{a_i} are displayed as actual subscripts in ``big'' +mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)}) +are displayed as @samp{a} with subscripts separated by commas: +@samp{i, j}. They must still be entered in the usual underscore +notation. + +One slight ambiguity of Big notation is that + +@example + 3 +- - + 4 +@end example + +@noindent +can represent either the negative rational number @cite{-3:4}, or the +actual expression @samp{-(3/4)}; but the latter formula would normally +never be displayed because it would immediately be evaluated to +@cite{-3:4} or @cite{-0.75}, so this ambiguity is not a problem in +typical use. + +Non-decimal numbers are displayed with subscripts. Thus there is no +way to tell the difference between @samp{16#C2} and @samp{C2_16}, +though generally you will know which interpretation is correct. +Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts +in Big mode. + +In Big mode, stack entries often take up several lines. To aid +readability, stack entries are separated by a blank line in this mode. +You may find it useful to expand the Calc window's height using +@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only +one on the screen with @kbd{C-x 1} (@code{delete-other-windows}). + +Long lines are currently not rearranged to fit the window width in +Big mode, so you may need to use the @kbd{<} and @kbd{>} keys +to scroll across a wide formula. For really big formulas, you may +even need to use @kbd{@{} and @kbd{@}} to scroll up and down. + +@kindex d U +@pindex calc-unformatted-language +The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables +the use of operator notation in formulas. In this mode, the formula +shown above would be displayed: + +@example +sqrt(add(div(add(a, 1), b), pow(c, 2))) +@end example + +These four modes differ only in display format, not in the format +expected for algebraic entry. The standard Calc operators work in +all four modes, and unformatted notation works in any language mode +(except that Mathematica mode expects square brackets instead of +parentheses). + +@node C FORTRAN Pascal, TeX Language Mode, Normal Language Modes, Language Modes +@subsection C, FORTRAN, and Pascal Modes + +@noindent +@kindex d C +@pindex calc-c-language +@cindex C language +The @kbd{d C} (@code{calc-c-language}) command selects the conventions +of the C language for display and entry of formulas. This differs from +the normal language mode in a variety of (mostly minor) ways. In +particular, C language operators and operator precedences are used in +place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)} +in C mode; a value raised to a power is written as a function call, +@samp{pow(a,b)}. + +In C mode, vectors and matrices use curly braces instead of brackets. +Octal and hexadecimal values are written with leading @samp{0} or @samp{0x} +rather than using the @samp{#} symbol. Array subscripting is +translated into @code{subscr} calls, so that @samp{a[i]} in C +mode is the same as @samp{a_i} in normal mode. Assignments +turn into the @code{assign} function, which Calc normally displays +using the @samp{:=} symbol. + +The variables @code{var-pi} and @code{var-e} would be displayed @samp{pi} +and @samp{e} in normal mode, but in C mode they are displayed as +@samp{M_PI} and @samp{M_E}, corresponding to the names of constants +typically provided in the @file{<math.h>} header. Functions whose +names are different in C are translated automatically for entry and +display purposes. For example, entering @samp{asin(x)} will push the +formula @samp{arcsin(x)} onto the stack; this formula will be displayed +as @samp{asin(x)} as long as C mode is in effect. + +@kindex d P +@pindex calc-pascal-language +@cindex Pascal language +The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal +conventions. Like C mode, Pascal mode interprets array brackets and uses +a different table of operators. Hexadecimal numbers are entered and +displayed with a preceding dollar sign. (Thus the regular meaning of +@kbd{$2} during algebraic entry does not work in Pascal mode, though +@kbd{$} (and @kbd{$$}, etc.) not followed by digits works the same as +always.) No special provisions are made for other non-decimal numbers, +vectors, and so on, since there is no universally accepted standard way +of handling these in Pascal. + +@kindex d F +@pindex calc-fortran-language +@cindex FORTRAN language +The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN +conventions. Various function names are transformed into FORTRAN +equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be +entered this way or using square brackets. Since FORTRAN uses round +parentheses for both function calls and array subscripts, Calc displays +both in the same way; @samp{a(i)} is interpreted as a function call +upon reading, and subscripts must be entered as @samp{subscr(a, i)}. +Also, if the variable @code{a} has been declared to have type +@code{vector} or @code{matrix} then @samp{a(i)} will be parsed as a +subscript. (@xref{Declarations}.) Usually it doesn't matter, though; +if you enter the subscript expression @samp{a(i)} and Calc interprets +it as a function call, you'll never know the difference unless you +switch to another language mode or replace @code{a} with an actual +vector (or unless @code{a} happens to be the name of a built-in +function!). + +Underscores are allowed in variable and function names in all of these +language modes. The underscore here is equivalent to the @samp{#} in +normal mode, or to hyphens in the underlying Emacs Lisp variable names. + +FORTRAN and Pascal modes normally do not adjust the case of letters in +formulas. Most built-in Calc names use lower-case letters. If you use a +positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these +modes will use upper-case letters exclusively for display, and will +convert to lower-case on input. With a negative prefix, these modes +convert to lower-case for display and input. + +@node TeX Language Mode, Eqn Language Mode, C FORTRAN Pascal, Language Modes +@subsection @TeX{} Language Mode + +@noindent +@kindex d T +@pindex calc-tex-language +@cindex TeX language +The @kbd{d T} (@code{calc-tex-language}) command selects the conventions +of ``math mode'' in the @TeX{} typesetting language, by Donald Knuth. +Formulas are entered +and displayed in @TeX{} notation, as in @samp{\sin\left( a \over b \right)}. +Math formulas are usually enclosed by @samp{$ $} signs in @TeX{}; these +should be omitted when interfacing with Calc. To Calc, the @samp{$} sign +has the same meaning it always does in algebraic formulas (a reference to +an existing entry on the stack).@refill + +Complex numbers are displayed as in @samp{3 + 4i}. Fractions and +quotients are written using @code{\over}; +binomial coefficients are written with @code{\choose}. +Interval forms are written with @code{\ldots}, and +error forms are written with @code{\pm}. +Absolute values are written as in @samp{|x + 1|}, and the floor and +ceiling functions are written with @code{\lfloor}, @code{\rfloor}, etc. +The words @code{\left} and @code{\right} are ignored when reading +formulas in @TeX{} mode. Both @code{inf} and @code{uinf} are written +as @code{\infty}; when read, @code{\infty} always translates to +@code{inf}.@refill + +Function calls are written the usual way, with the function name followed +by the arguments in parentheses. However, functions for which @TeX{} has +special names (like @code{\sin}) will use curly braces instead of +parentheses for very simple arguments. During input, curly braces and +parentheses work equally well for grouping, but when the document is +formatted the curly braces will be invisible. Thus the printed result is +@c{$\sin{2 x}$} +@cite{sin 2x} but @c{$\sin(2 + x)$} +@cite{sin(2 + x)}. + +Function and variable names not treated specially by @TeX{} are simply +written out as-is, which will cause them to come out in italic letters +in the printed document. If you invoke @kbd{d T} with a positive numeric +prefix argument, names of more than one character will instead be written +@samp{\hbox@{@var{name}@}}. The @samp{\hbox@{ @}} notation is ignored +during reading. If you use a negative prefix argument, such function +names are written @samp{\@var{name}}, and function names that begin +with @code{\} during reading have the @code{\} removed. (Note that +in this mode, long variable names are still written with @code{\hbox}. +However, you can always make an actual variable name like @code{\bar} +in any @TeX{} mode.) + +During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced +by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and +@code{\bmatrix}. The symbol @samp{&} is interpreted as a comma, +and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons. +During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}} +format; you may need to edit this afterwards to change @code{\matrix} +to @code{\pmatrix} or @code{\\} to @code{\cr}. + +Accents like @code{\tilde} and @code{\bar} translate into function +calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline} +sequence is treated as an accent. The @code{\vec} accent corresponds +to the function name @code{Vec}, because @code{vec} is the name of +a built-in Calc function. The following table shows the accents +in Calc, @TeX{}, and @dfn{eqn} (described in the next section): + +@iftex +@begingroup +@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes +@let@calcindexersh=@calcindexernoshow +@end iftex +@c @starindex +@tindex acute +@c @starindex +@tindex bar +@c @starindex +@tindex breve +@c @starindex +@tindex check +@c @starindex +@tindex dot +@c @starindex +@tindex dotdot +@c @starindex +@tindex dyad +@c @starindex +@tindex grave +@c @starindex +@tindex hat +@c @starindex +@tindex Prime +@c @starindex +@tindex tilde +@c @starindex +@tindex under +@c @starindex +@tindex Vec +@iftex +@endgroup +@end iftex +@example +Calc TeX eqn +---- --- --- +acute \acute +bar \bar bar +breve \breve +check \check +dot \dot dot +dotdot \ddot dotdot +dyad dyad +grave \grave +hat \hat hat +Prime prime +tilde \tilde tilde +under \underline under +Vec \vec vec +@end example + +The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol: +@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an +alias for @code{\rightarrow}. However, if the @samp{=>} is the +top-level expression being formatted, a slightly different notation +is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto} +word is ignored by Calc's input routines, and is undefined in @TeX{}. +You will typically want to include one of the following definitions +at the top of a @TeX{} file that uses @code{\evalto}: + +@example +\def\evalto@{@} +\def\evalto#1\to@{@} +@end example + +The first definition formats evaluates-to operators in the usual +way. The second causes only the @var{b} part to appear in the +printed document; the @var{a} part and the arrow are hidden. +Another definition you may wish to use is @samp{\let\to=\Rightarrow} +which causes @code{\to} to appear more like Calc's @samp{=>} symbol. +@xref{Evaluates-To Operator}, for a discussion of @code{evalto}. + +The complete set of @TeX{} control sequences that are ignored during +reading is: + +@example +\hbox \mbox \text \left \right +\, \> \: \; \! \quad \qquad \hfil \hfill +\displaystyle \textstyle \dsize \tsize +\scriptstyle \scriptscriptstyle \ssize \ssize +\rm \bf \it \sl \roman \bold \italic \slanted +\cal \mit \Cal \Bbb \frak \goth +\evalto +@end example + +Note that, because these symbols are ignored, reading a @TeX{} formula +into Calc and writing it back out may lose spacing and font information. + +Also, the ``discretionary multiplication sign'' @samp{\*} is read +the same as @samp{*}. + +@ifinfo +The @TeX{} version of this manual includes some printed examples at the +end of this section. +@end ifinfo +@iftex +Here are some examples of how various Calc formulas are formatted in @TeX{}: + +@group +@example +sin(a^2 / b_i) +\sin\left( {a^2 \over b_i} \right) +@end example +@tex +\let\rm\goodrm +$$ \sin\left( a^2 \over b_i \right) $$ +@end tex +@sp 1 +@end group + +@group +@example +[(3, 4), 3:4, 3 +/- 4, [3 .. inf)] +[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)] +@end example +@tex +\turnoffactive +$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$ +@end tex +@sp 1 +@end group + +@group +@example +[abs(a), abs(a / b), floor(a), ceil(a / b)] +[|a|, \left| a \over b \right|, + \lfloor a \rfloor, \left\lceil a \over b \right\rceil] +@end example +@tex +$$ [|a|, \left| a \over b \right|, + \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$ +@end tex +@sp 1 +@end group + +@group +@example +[sin(a), sin(2 a), sin(2 + a), sin(a / b)] +[\sin@{a@}, \sin@{2 a@}, \sin(2 + a), + \sin\left( @{a \over b@} \right)] +@end example +@tex +\turnoffactive\let\rm\goodrm +$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$ +@end tex +@sp 2 +@end group + +@group +First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with +@kbd{C-u - d T} (using the example definition +@samp{\def\foo#1@{\tilde F(#1)@}}: + +@example + +[f(a), foo(bar), sin(pi)] +[f(a), foo(bar), \sin{\pi}] +[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}] +[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}] +@end example +@tex +\let\rm\goodrm +$$ [f(a), foo(bar), \sin{\pi}] $$ +$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$ +$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$ +@end tex +@sp 2 +@end group + +@group +First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}: + +@example + +2 + 3 => 5 +\evalto 2 + 3 \to 5 +@end example +@tex +\turnoffactive +$$ 2 + 3 \to 5 $$ +$$ 5 $$ +@end tex +@sp 2 +@end group + +@group +First with standard @code{\to}, then with @samp{\let\to\Rightarrow}: + +@example + +[2 + 3 => 5, a / 2 => (b + c) / 2] +[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}] +@end example +@tex +\turnoffactive +$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$ +{\let\to\Rightarrow +$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$} +@end tex +@sp 2 +@end group + +@group +Matrices normally, then changing @code{\matrix} to @code{\pmatrix}: + +@example + +[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ] +\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} +\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} +@end example +@tex +\turnoffactive +$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ +$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ +@end tex +@sp 2 +@end group +@end iftex + +@node Eqn Language Mode, Mathematica Language Mode, TeX Language Mode, Language Modes +@subsection Eqn Language Mode + +@noindent +@kindex d E +@pindex calc-eqn-language +@dfn{Eqn} is another popular formatter for math formulas. It is +designed for use with the TROFF text formatter, and comes standard +with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language}) +command selects @dfn{eqn} notation. + +The @dfn{eqn} language's main idiosyncrasy is that whitespace plays +a significant part in the parsing of the language. For example, +@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the +@code{sqrt} operator. @dfn{Eqn} also understands more conventional +grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are +required only when the argument contains spaces. + +In Calc's @dfn{eqn} mode, however, curly braces are required to +delimit arguments of operators like @code{sqrt}. The first of the +above examples would treat only the @samp{x} as the argument of +@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as +@samp{sin * x + 1}, because @code{sin} is not a special operator +in the @dfn{eqn} language. If you always surround the argument +with curly braces, Calc will never misunderstand. + +Calc also understands parentheses as grouping characters. Another +peculiarity of @dfn{eqn}'s syntax makes it advisable to separate +words with spaces from any surrounding characters that aren't curly +braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode. +(The spaces around @code{sin} are important to make @dfn{eqn} +recognize that @code{sin} should be typeset in a roman font, and +the spaces around @code{x} and @code{y} are a good idea just in +case the @dfn{eqn} document has defined special meanings for these +names, too.) + +Powers and subscripts are written with the @code{sub} and @code{sup} +operators, respectively. Note that the caret symbol @samp{^} is +treated the same as a space in @dfn{eqn} mode, as is the @samp{~} +symbol (these are used to introduce spaces of various widths into +the typeset output of @dfn{eqn}). + +As in @TeX{} mode, Calc's formatter omits parentheses around the +arguments of functions like @code{ln} and @code{sin} if they are +``simple-looking''; in this case Calc surrounds the argument with +braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}. + +Font change codes (like @samp{roman @var{x}}) and positioning codes +(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the +@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right}, +@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input +are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to +@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning +of quotes in @dfn{eqn}, but it is good enough for most uses. + +Accent codes (@samp{@var{x} dot}) are handled by treating them as +function calls (@samp{dot(@var{x})}) internally. @xref{TeX Language +Mode} for a table of these accent functions. The @code{prime} accent +is treated specially if it occurs on a variable or function name: +@samp{f prime prime @w{( x prime )}} is stored internally as +@samp{f'@w{'}(x')}. For example, taking the derivative of @samp{f(2 x)} +with @kbd{a d x} will produce @samp{2 f'(2 x)}, which @dfn{eqn} mode +will display as @samp{2 f prime ( 2 x )}. + +Assignments are written with the @samp{<-} (left-arrow) symbol, +and @code{evalto} operators are written with @samp{->} or +@samp{evalto ... ->} (@pxref{TeX Language Mode}, for a discussion +of this). The regular Calc symbols @samp{:=} and @samp{=>} are also +recognized for these operators during reading. + +Vectors in @dfn{eqn} mode use regular Calc square brackets, but +matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}. +The words @code{lcol} and @code{rcol} are recognized as synonyms +for @code{ccol} during input, and are generated instead of @code{ccol} +if the matrix justification mode so specifies. + +@node Mathematica Language Mode, Maple Language Mode, Eqn Language Mode, Language Modes +@subsection Mathematica Language Mode + +@noindent +@kindex d M +@pindex calc-mathematica-language +@cindex Mathematica language +The @kbd{d M} (@code{calc-mathematica-language}) command selects the +conventions of Mathematica, a powerful and popular mathematical tool +from Wolfram Research, Inc. Notable differences in Mathematica mode +are that the names of built-in functions are capitalized, and function +calls use square brackets instead of parentheses. Thus the Calc +formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in +Mathematica mode. + +Vectors and matrices use curly braces in Mathematica. Complex numbers +are written @samp{3 + 4 I}. The standard special constants in Calc are +written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma}, +@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in +Mathematica mode. +Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point +numbers in scientific notation are written @samp{1.23*10.^3}. +Subscripts use double square brackets: @samp{a[[i]]}.@refill + +@node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes +@subsection Maple Language Mode + +@noindent +@kindex d W +@pindex calc-maple-language +@cindex Maple language +The @kbd{d W} (@code{calc-maple-language}) command selects the +conventions of Maple, another mathematical tool from the University +of Waterloo. + +Maple's language is much like C. Underscores are allowed in symbol +names; square brackets are used for subscripts; explicit @samp{*}s for +multiplications are required. Use either @samp{^} or @samp{**} to +denote powers. + +Maple uses square brackets for lists and curly braces for sets. Calc +interprets both notations as vectors, and displays vectors with square +brackets. This means Maple sets will be converted to lists when they +pass through Calc. As a special case, matrices are written as calls +to the function @code{matrix}, given a list of lists as the argument, +and can be read in this form or with all-capitals @code{MATRIX}. + +The Maple interval notation @samp{2 .. 3} has no surrounding brackets; +Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]}, and +writes any kind of interval as @samp{2 .. 3}. This means you cannot +see the difference between an open and a closed interval while in +Maple display mode. + +Maple writes complex numbers as @samp{3 + 4*I}. Its special constants +are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of +@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}). +Floating-point numbers are written @samp{1.23*10.^3}. + +Among things not currently handled by Calc's Maple mode are the +various quote symbols, procedures and functional operators, and +inert (@samp{&}) operators. + +@node Compositions, Syntax Tables, Maple Language Mode, Language Modes +@subsection Compositions + +@noindent +@cindex Compositions +There are several @dfn{composition functions} which allow you to get +displays in a variety of formats similar to those in Big language +mode. Most of these functions do not evaluate to anything; they are +placeholders which are left in symbolic form by Calc's evaluator but +are recognized by Calc's display formatting routines. + +Two of these, @code{string} and @code{bstring}, are described elsewhere. +@xref{Strings}. For example, @samp{string("ABC")} is displayed as +@samp{ABC}. When viewed on the stack it will be indistinguishable from +the variable @code{ABC}, but internally it will be stored as +@samp{string([65, 66, 67])} and can still be manipulated this way; for +example, the selection and vector commands @kbd{j 1 v v j u} would +select the vector portion of this object and reverse the elements, then +deselect to reveal a string whose characters had been reversed. + +The composition functions do the same thing in all language modes +(although their components will of course be formatted in the current +language mode). The one exception is Unformatted mode (@kbd{d U}), +which does not give the composition functions any special treatment. +The functions are discussed here because of their relationship to +the language modes. + +@menu +* Composition Basics:: +* Horizontal Compositions:: +* Vertical Compositions:: +* Other Compositions:: +* Information about Compositions:: +* User-Defined Compositions:: +@end menu + +@node Composition Basics, Horizontal Compositions, Compositions, Compositions +@subsubsection Composition Basics + +@noindent +Compositions are generally formed by stacking formulas together +horizontally or vertically in various ways. Those formulas are +themselves compositions. @TeX{} users will find this analogous +to @TeX{}'s ``boxes.'' Each multi-line composition has a +@dfn{baseline}; horizontal compositions use the baselines to +decide how formulas should be positioned relative to one another. +For example, in the Big mode formula + +@group +@example + 2 + a + b +17 + ------ + c +@end example +@end group + +@noindent +the second term of the sum is four lines tall and has line three as +its baseline. Thus when the term is combined with 17, line three +is placed on the same level as the baseline of 17. + +@tex +\bigskip +@end tex + +Another important composition concept is @dfn{precedence}. This is +an integer that represents the binding strength of various operators. +For example, @samp{*} has higher precedence (195) than @samp{+} (180), +which means that @samp{(a * b) + c} will be formatted without the +parentheses, but @samp{a * (b + c)} will keep the parentheses. + +The operator table used by normal and Big language modes has the +following precedences: + +@example +_ 1200 @r{(subscripts)} +% 1100 @r{(as in n}%@r{)} +- 1000 @r{(as in }-@r{n)} +! 1000 @r{(as in }!@r{n)} +mod 400 ++/- 300 +!! 210 @r{(as in n}!!@r{)} +! 210 @r{(as in n}!@r{)} +^ 200 +* 195 @r{(or implicit multiplication)} +/ % \ 190 ++ - 180 @r{(as in a}+@r{b)} +| 170 +< = 160 @r{(and other relations)} +&& 110 +|| 100 +? : 90 +!!! 85 +&&& 80 +||| 75 +:= 50 +:: 45 +=> 40 +@end example + +The general rule is that if an operator with precedence @cite{n} +occurs as an argument to an operator with precedence @cite{m}, then +the argument is enclosed in parentheses if @cite{n < m}. Top-level +expressions and expressions which are function arguments, vector +components, etc., are formatted with precedence zero (so that they +normally never get additional parentheses). + +For binary left-associative operators like @samp{+}, the righthand +argument is actually formatted with one-higher precedence than shown +in the table. This makes sure @samp{(a + b) + c} omits the parentheses, +but the unnatural form @samp{a + (b + c)} keeps its parentheses. +Right-associative operators like @samp{^} format the lefthand argument +with one-higher precedence. + +@c @starindex +@tindex cprec +The @code{cprec} function formats an expression with an arbitrary +precedence. For example, @samp{cprec(abc, 185)} will combine into +sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because +this @code{cprec} form has higher precedence than addition, but lower +precedence than multiplication). + +@tex +\bigskip +@end tex + +A final composition issue is @dfn{line breaking}. Calc uses two +different strategies for ``flat'' and ``non-flat'' compositions. +A non-flat composition is anything that appears on multiple lines +(not counting line breaking). Examples would be matrices and Big +mode powers and quotients. Non-flat compositions are displayed +exactly as specified. If they come out wider than the current +window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to +view them. + +Flat compositions, on the other hand, will be broken across several +lines if they are too wide to fit the window. Certain points in a +composition are noted internally as @dfn{break points}. Calc's +general strategy is to fill each line as much as possible, then to +move down to the next line starting at the first break point that +didn't fit. However, the line breaker understands the hierarchical +structure of formulas. It will not break an ``inner'' formula if +it can use an earlier break point from an ``outer'' formula instead. +For example, a vector of sums might be formatted as: + +@group +@example +[ a + b + c, d + e + f, + g + h + i, j + k + l, m ] +@end example +@end group + +@noindent +If the @samp{m} can fit, then so, it seems, could the @samp{g}. +But Calc prefers to break at the comma since the comma is part +of a ``more outer'' formula. Calc would break at a plus sign +only if it had to, say, if the very first sum in the vector had +itself been too large to fit. + +Of the composition functions described below, only @code{choriz} +generates break points. The @code{bstring} function (@pxref{Strings}) +also generates breakable items: A break point is added after every +space (or group of spaces) except for spaces at the very beginning or +end of the string. + +Composition functions themselves count as levels in the formula +hierarchy, so a @code{choriz} that is a component of a larger +@code{choriz} will be less likely to be broken. As a special case, +if a @code{bstring} occurs as a component of a @code{choriz} or +@code{choriz}-like object (such as a vector or a list of arguments +in a function call), then the break points in that @code{bstring} +will be on the same level as the break points of the surrounding +object. + +@node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions +@subsubsection Horizontal Compositions + +@noindent +@c @starindex +@tindex choriz +The @code{choriz} function takes a vector of objects and composes +them horizontally. For example, @samp{choriz([17, a b/c, d])} formats +as @w{@samp{17a b / cd}} in normal language mode, or as + +@group +@example + a b +17---d + c +@end example +@end group + +@noindent +in Big language mode. This is actually one case of the general +function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where +either or both of @var{sep} and @var{prec} may be omitted. +@var{Prec} gives the @dfn{precedence} to use when formatting +each of the components of @var{vec}. The default precedence is +the precedence from the surrounding environment. + +@var{Sep} is a string (i.e., a vector of character codes as might +be entered with @code{" "} notation) which should separate components +of the composition. Also, if @var{sep} is given, the line breaker +will allow lines to be broken after each occurrence of @var{sep}. +If @var{sep} is omitted, the composition will not be breakable +(unless any of its component compositions are breakable). + +For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is +formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz} +to have precedence 180 ``outwards'' as well as ``inwards,'' +enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)} +formats as @samp{2 (a + b c + (d = e))}. + +The baseline of a horizontal composition is the same as the +baselines of the component compositions, which are all aligned. + +@node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions +@subsubsection Vertical Compositions + +@noindent +@c @starindex +@tindex cvert +The @code{cvert} function makes a vertical composition. Each +component of the vector is centered in a column. The baseline of +the result is by default the top line of the resulting composition. +For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))} +formats in Big mode as + +@group +@example +f( a , 2 ) + bb a + 1 + ccc 2 + b +@end example +@end group + +@c @starindex +@tindex cbase +There are several special composition functions that work only as +components of a vertical composition. The @code{cbase} function +controls the baseline of the vertical composition; the baseline +will be the same as the baseline of whatever component is enclosed +in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]), +cvert([a^2 + 1, cbase(b^2)]))} displays as + +@group +@example + 2 + a + 1 + a 2 +f(bb , b ) + ccc +@end example +@end group + +@c @starindex +@tindex ctbase +@c @starindex +@tindex cbbase +There are also @code{ctbase} and @code{cbbase} functions which +make the baseline of the vertical composition equal to the top +or bottom line (rather than the baseline) of that component. +Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) + +cvert([cbbase(a / b)])} gives + +@group +@example + a +a - +- + a + b +b - + b +@end example +@end group + +There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase} +function in a given vertical composition. These functions can also +be written with no arguments: @samp{ctbase()} is a zero-height object +which means the baseline is the top line of the following item, and +@samp{cbbase()} means the baseline is the bottom line of the preceding +item. + +@c @starindex +@tindex crule +The @code{crule} function builds a ``rule,'' or horizontal line, +across a vertical composition. By itself @samp{crule()} uses @samp{-} +characters to build the rule. You can specify any other character, +e.g., @samp{crule("=")}. The argument must be a character code or +vector of exactly one character code. It is repeated to match the +width of the widest item in the stack. For example, a quotient +with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}: + +@group +@example +a + 1 +===== + 2 + b +@end example +@end group + +@c @starindex +@tindex clvert +@c @starindex +@tindex crvert +Finally, the functions @code{clvert} and @code{crvert} act exactly +like @code{cvert} except that the items are left- or right-justified +in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])} +gives: + +@group +@example +a + a +bb bb +ccc ccc +@end example +@end group + +Like @code{choriz}, the vertical compositions accept a second argument +which gives the precedence to use when formatting the components. +Vertical compositions do not support separator strings. + +@node Other Compositions, Information about Compositions, Vertical Compositions, Compositions +@subsubsection Other Compositions + +@noindent +@c @starindex +@tindex csup +The @code{csup} function builds a superscripted expression. For +example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big +language mode. This is essentially a horizontal composition of +@samp{a} and @samp{b}, where @samp{b} is shifted up so that its +bottom line is one above the baseline. + +@c @starindex +@tindex csub +Likewise, the @code{csub} function builds a subscripted expression. +This shifts @samp{b} down so that its top line is one below the +bottom line of @samp{a} (note that this is not quite analogous to +@code{csup}). Other arrangements can be obtained by using +@code{choriz} and @code{cvert} directly. + +@c @starindex +@tindex cflat +The @code{cflat} function formats its argument in ``flat'' mode, +as obtained by @samp{d O}, if the current language mode is normal +or Big. It has no effect in other language modes. For example, +@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))} +to improve its readability. + +@c @starindex +@tindex cspace +The @code{cspace} function creates horizontal space. For example, +@samp{cspace(4)} is effectively the same as @samp{string(" ")}. +A second string (i.e., vector of characters) argument is repeated +instead of the space character. For example, @samp{cspace(4, "ab")} +looks like @samp{abababab}. If the second argument is not a string, +it is formatted in the normal way and then several copies of that +are composed together: @samp{cspace(4, a^2)} yields + +@group +@example + 2 2 2 2 +a a a a +@end example +@end group + +@noindent +If the number argument is zero, this is a zero-width object. + +@c @starindex +@tindex cvspace +The @code{cvspace} function creates vertical space, or a vertical +stack of copies of a certain string or formatted object. The +baseline is the center line of the resulting stack. A numerical +argument of zero will produce an object which contributes zero +height if used in a vertical composition. + +@c @starindex +@tindex ctspace +@c @starindex +@tindex cbspace +There are also @code{ctspace} and @code{cbspace} functions which +create vertical space with the baseline the same as the baseline +of the top or bottom copy, respectively, of the second argument. +Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)} +displays as: + +@group +@example + a + - +a b +- a a +b + - + - +a b b +- a +b - + b +@end example +@end group + +@node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions +@subsubsection Information about Compositions + +@noindent +The functions in this section are actual functions; they compose their +arguments according to the current language and other display modes, +then return a certain measurement of the composition as an integer. + +@c @starindex +@tindex cwidth +The @code{cwidth} function measures the width, in characters, of a +composition. For example, @samp{cwidth(a + b)} is 5, and +@samp{cwidth(a / b)} is 5 in normal mode, 1 in Big mode, and 11 in +@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve +the composition functions described in this section. + +@c @starindex +@tindex cheight +The @code{cheight} function measures the height of a composition. +This is the total number of lines in the argument's printed form. + +@c @starindex +@tindex cascent +@c @starindex +@tindex cdescent +The functions @code{cascent} and @code{cdescent} measure the amount +of the height that is above (and including) the baseline, or below +the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})} +always equals @samp{cheight(@var{x})}. For a one-line formula like +@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0. +For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent} +returns 1. The only formula for which @code{cascent} will return zero +is @samp{cvspace(0)} or equivalents. + +@node User-Defined Compositions, , Information about Compositions, Compositions +@subsubsection User-Defined Compositions + +@noindent +@kindex Z C +@pindex calc-user-define-composition +The @kbd{Z C} (@code{calc-user-define-composition}) command lets you +define the display format for any algebraic function. You provide a +formula containing a certain number of argument variables on the stack. +Any time Calc formats a call to the specified function in the current +language mode and with that number of arguments, Calc effectively +replaces the function call with that formula with the arguments +replaced. + +Calc builds the default argument list by sorting all the variable names +that appear in the formula into alphabetical order. You can edit this +argument list before pressing @key{RET} if you wish. Any variables in +the formula that do not appear in the argument list will be displayed +literally; any arguments that do not appear in the formula will not +affect the display at all. + +You can define formats for built-in functions, for functions you have +defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions +which have no definitions but are being used as purely syntactic objects. +You can define different formats for each language mode, and for each +number of arguments, using a succession of @kbd{Z C} commands. When +Calc formats a function call, it first searches for a format defined +for the current language mode (and number of arguments); if there is +none, it uses the format defined for the Normal language mode. If +neither format exists, Calc uses its built-in standard format for that +function (usually just @samp{@var{func}(@var{args})}). + +If you execute @kbd{Z C} with the number 0 on the stack instead of a +formula, any defined formats for the function in the current language +mode will be removed. The function will revert to its standard format. + +For example, the default format for the binomial coefficient function +@samp{choose(n, m)} in the Big language mode is + +@group +@example + n +( ) + m +@end example +@end group + +@noindent +You might prefer the notation, + +@group +@example + C +n m +@end example +@end group + +@noindent +To define this notation, first make sure you are in Big mode, +then put the formula + +@smallexample +choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])]) +@end smallexample + +@noindent +on the stack and type @kbd{Z C}. Answer the first prompt with +@code{choose}. The second prompt will be the default argument list +of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press +@key{RET}. Now, try it out: For example, turn simplification +off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)} +as an algebraic entry. + +@group +@example + C + C +a b 7 3 +@end example +@end group + +As another example, let's define the usual notation for Stirling +numbers of the first kind, @samp{stir1(n, m)}. This is just like +the regular format for binomial coefficients but with square brackets +instead of parentheses. + +@smallexample +choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")]) +@end smallexample + +Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to +@samp{(n m)}, and type @key{RET}. + +The formula provided to @kbd{Z C} usually will involve composition +functions, but it doesn't have to. Putting the formula @samp{a + b + c} +onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define +the function @samp{foo(x,y,z)} to display like @samp{x + y + z}. +This ``sum'' will act exactly like a real sum for all formatting +purposes (it will be parenthesized the same, and so on). However +it will be computationally unrelated to a sum. For example, the +formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}. +Operator precedences have caused the ``sum'' to be written in +parentheses, but the arguments have not actually been summed. +(Generally a display format like this would be undesirable, since +it can easily be confused with a real sum.) + +The special function @code{eval} can be used inside a @kbd{Z C} +composition formula to cause all or part of the formula to be +evaluated at display time. For example, if the formula is +@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed +as @samp{1 + 5}. Evaluation will use the default simplifications, +regardless of the current simplification mode. There are also +@code{evalsimp} and @code{evalextsimp} which simplify as if by +@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions'' +operate only in the context of composition formulas (and also in +rewrite rules, where they serve a similar purpose; @pxref{Rewrite +Rules}). On the stack, a call to @code{eval} will be left in +symbolic form. + +It is not a good idea to use @code{eval} except as a last resort. +It can cause the display of formulas to be extremely slow. For +example, while @samp{eval(a + b)} might seem quite fast and simple, +there are several situations where it could be slow. For example, +@samp{a} and/or @samp{b} could be polar complex numbers, in which +case doing the sum requires trigonometry. Or, @samp{a} could be +the factorial @samp{fact(100)} which is unevaluated because you +have typed @kbd{m O}; @code{eval} will evaluate it anyway to +produce a large, unwieldy integer. + +You can save your display formats permanently using the @kbd{Z P} +command (@pxref{Creating User Keys}). + +@node Syntax Tables, , Compositions, Language Modes +@subsection Syntax Tables + +@noindent +@cindex Syntax tables +@cindex Parsing formulas, customized +Syntax tables do for input what compositions do for output: They +allow you to teach custom notations to Calc's formula parser. +Calc keeps a separate syntax table for each language mode. + +(Note that the Calc ``syntax tables'' discussed here are completely +unrelated to the syntax tables described in the Emacs manual.) + +@kindex Z S +@pindex calc-edit-user-syntax +The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the +syntax table for the current language mode. If you want your +syntax to work in any language, define it in the normal language +mode. Type @kbd{M-# M-#} to finish editing the syntax table, or +@kbd{M-# x} to cancel the edit. The @kbd{m m} command saves all +the syntax tables along with the other mode settings; +@pxref{General Mode Commands}. + +@menu +* Syntax Table Basics:: +* Precedence in Syntax Tables:: +* Advanced Syntax Patterns:: +* Conditional Syntax Rules:: +@end menu + +@node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables +@subsubsection Syntax Table Basics + +@noindent +@dfn{Parsing} is the process of converting a raw string of characters, +such as you would type in during algebraic entry, into a Calc formula. +Calc's parser works in two stages. First, the input is broken down +into @dfn{tokens}, such as words, numbers, and punctuation symbols +like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is +ignored (except when it serves to separate adjacent words). Next, +the parser matches this string of tokens against various built-in +syntactic patterns, such as ``an expression followed by @samp{+} +followed by another expression'' or ``a name followed by @samp{(}, +zero or more expressions separated by commas, and @samp{)}.'' + +A @dfn{syntax table} is a list of user-defined @dfn{syntax rules}, +which allow you to specify new patterns to define your own +favorite input notations. Calc's parser always checks the syntax +table for the current language mode, then the table for the normal +language mode, before it uses its built-in rules to parse an +algebraic formula you have entered. Each syntax rule should go on +its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol, +and a Calc formula with an optional @dfn{condition}. (Syntax rules +resemble algebraic rewrite rules, but the notation for patterns is +completely different.) + +A syntax pattern is a list of tokens, separated by spaces. +Except for a few special symbols, tokens in syntax patterns are +matched literally, from left to right. For example, the rule, + +@example +foo ( ) := 2+3 +@end example + +@noindent +would cause Calc to parse the formula @samp{4+foo()*5} as if it +were @samp{4+(2+3)*5}. Notice that the parentheses were written +as two separate tokens in the rule. As a result, the rule works +for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written +the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()} +as a single, indivisible token, so that @w{@samp{foo( )}} would +not be recognized by the rule. (It would be parsed as a regular +zero-argument function call instead.) In fact, this rule would +also make trouble for the rest of Calc's parser: An unrelated +formula like @samp{bar()} would now be tokenized into @samp{bar ()} +instead of @samp{bar ( )}, so that the standard parser for function +calls would no longer recognize it! + +While it is possible to make a token with a mixture of letters +and punctuation symbols, this is not recommended. It is better to +break it into several tokens, as we did with @samp{foo()} above. + +The symbol @samp{#} in a syntax pattern matches any Calc expression. +On the righthand side, the things that matched the @samp{#}s can +be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1} +matches the leftmost @samp{#} in the pattern). For example, these +rules match a user-defined function, prefix operator, infix operator, +and postfix operator, respectively: + +@example +foo ( # ) := myfunc(#1) +foo # := myprefix(#1) +# foo # := myinfix(#1,#2) +# foo := mypostfix(#1) +@end example + +Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo} +will parse as @samp{mypostfix(2+3)}. + +It is important to write the first two rules in the order shown, +because Calc tries rules in order from first to last. If the +pattern @samp{foo #} came first, it would match anything that could +match the @samp{foo ( # )} rule, since an expression in parentheses +is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would +never get to match anything. Likewise, the last two rules must be +written in the order shown or else @samp{3 foo 4} will be parsed as +@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these +ambiguities is not to use the same symbol in more than one way at +the same time! In case you're not convinced, try the following +exercise: How will the above rules parse the input @samp{foo(3,4)}, +if at all? Work it out for yourself, then try it in Calc and see.) + +Calc is quite flexible about what sorts of patterns are allowed. +The only rule is that every pattern must begin with a literal +token (like @samp{foo} in the first two patterns above), or with +a @samp{#} followed by a literal token (as in the last two +patterns). After that, any mixture is allowed, although putting +two @samp{#}s in a row will not be very useful since two +expressions with nothing between them will be parsed as one +expression that uses implicit multiplication. + +As a more practical example, Maple uses the notation +@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't +recognize at present. To handle this syntax, we simply add the +rule, + +@example +sum ( # , # = # .. # ) := sum(#1,#2,#3,#4) +@end example + +@noindent +to the Maple mode syntax table. As another example, C mode can't +read assignment operators like @samp{++} and @samp{*=}. We can +define these operators quite easily: + +@example +# *= # := muleq(#1,#2) +# ++ := postinc(#1) +++ # := preinc(#1) +@end example + +@noindent +To complete the job, we would use corresponding composition functions +and @kbd{Z C} to cause these functions to display in their respective +Maple and C notations. (Note that the C example ignores issues of +operator precedence, which are discussed in the next section.) + +You can enclose any token in quotes to prevent its usual +interpretation in syntax patterns: + +@example +# ":=" # := becomes(#1,#2) +@end example + +Quotes also allow you to include spaces in a token, although once +again it is generally better to use two tokens than one token with +an embedded space. To include an actual quotation mark in a quoted +token, precede it with a backslash. (This also works to include +backslashes in tokens.) + +@example +# "bad token" # "/\"\\" # := silly(#1,#2,#3) +@end example + +@noindent +This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}. + +The token @kbd{#} has a predefined meaning in Calc's formula parser; +it is not legal to use @samp{"#"} in a syntax rule. However, longer +tokens that include the @samp{#} character are allowed. Also, while +@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in +the syntax table will prevent those characters from working in their +usual ways (referring to stack entries and quoting strings, +respectively). + +Finally, the notation @samp{%%} anywhere in a syntax table causes +the rest of the line to be ignored as a comment. + +@node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables +@subsubsection Precedence + +@noindent +Different operators are generally assigned different @dfn{precedences}. +By default, an operator defined by a rule like + +@example +# foo # := foo(#1,#2) +@end example + +@noindent +will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6} +will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the +precedence of an operator, use the notation @samp{#/@var{p}} in +place of @samp{#}, where @var{p} is an integer precedence level. +For example, 185 lies between the precedences for @samp{+} and +@samp{*}, so if we change this rule to + +@example +#/185 foo #/186 := foo(#1,#2) +@end example + +@noindent +then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}. +Also, because we've given the righthand expression slightly higher +precedence, our new operator will be left-associative: +@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}. +By raising the precedence of the lefthand expression instead, we +can create a right-associative operator. + +@xref{Composition Basics}, for a table of precedences of the +standard Calc operators. For the precedences of operators in other +language modes, look in the Calc source file @file{calc-lang.el}. + +@node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables +@subsubsection Advanced Syntax Patterns + +@noindent +To match a function with a variable number of arguments, you could +write + +@example +foo ( # ) := myfunc(#1) +foo ( # , # ) := myfunc(#1,#2) +foo ( # , # , # ) := myfunc(#1,#2,#3) +@end example + +@noindent +but this isn't very elegant. To match variable numbers of items, +Calc uses some notations inspired regular expressions and the +``extended BNF'' style used by some language designers. + +@example +foo ( @{ # @}*, ) := apply(myfunc,#1) +@end example + +The token @samp{@{} introduces a repeated or optional portion. +One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?} +ends the portion. These will match zero or more, one or more, +or zero or one copies of the enclosed pattern, respectively. +In addition, @samp{@}*} and @samp{@}+} can be followed by a +separator token (with no space in between, as shown above). +Thus @samp{@{ # @}*,} matches nothing, or one expression, or +several expressions separated by commas. + +A complete @samp{@{ ... @}} item matches as a vector of the +items that matched inside it. For example, the above rule will +match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}. +The Calc @code{apply} function takes a function name and a vector +of arguments and builds a call to the function with those +arguments, so the net result is the formula @samp{myfunc(1,2,3)}. + +If the body of a @samp{@{ ... @}} contains several @samp{#}s +(or nested @samp{@{ ... @}} constructs), then the items will be +strung together into the resulting vector. If the body +does not contain anything but literal tokens, the result will +always be an empty vector. + +@example +foo ( @{ # , # @}+, ) := bar(#1) +foo ( @{ @{ # @}*, @}*; ) := matrix(#1) +@end example + +@noindent +will parse @samp{foo(1,2,3,4)} as @samp{bar([1,2,3,4])}, and +@samp{foo(1,2;3,4)} as @samp{matrix([[1,2],[3,4]])}. Also, after +some thought it's easy to see how this pair of rules will parse +@samp{foo(1,2,3)} as @samp{matrix([[1,2,3]])}, since the first +rule will only match an even number of arguments. The rule + +@example +foo ( # @{ , # , # @}? ) := bar(#1,#2) +@end example + +@noindent +will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and +@samp{foo(2)} as @samp{bar(2,[])}. + +The notation @samp{@{ ... @}?.} (note the trailing period) works +just the same as regular @samp{@{ ... @}?}, except that it does not +count as an argument; the following two rules are equivalent: + +@example +foo ( # , @{ also @}? # ) := bar(#1,#3) +foo ( # , @{ also @}?. # ) := bar(#1,#2) +@end example + +@noindent +Note that in the first case the optional text counts as @samp{#2}, +which will always be an empty vector, but in the second case no +empty vector is produced. + +Another variant is @samp{@{ ... @}?$}, which means the body is +optional only at the end of the input formula. All built-in syntax +rules in Calc use this for closing delimiters, so that during +algebraic entry you can type @kbd{[sqrt(2), sqrt(3 RET}, omitting +the closing parenthesis and bracket. Calc does this automatically +for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax +rules, but you can use @samp{@{ ... @}?$} explicitly to get +this effect with any token (such as @samp{"@}"} or @samp{end}). +Like @samp{@{ ... @}?.}, this notation does not count as an +argument. Conversely, you can use quotes, as in @samp{")"}, to +prevent a closing-delimiter token from being automatically treated +as optional. + +Calc's parser does not have full backtracking, which means some +patterns will not work as you might expect: + +@example +foo ( @{ # , @}? # , # ) := bar(#1,#2,#3) +@end example + +@noindent +Here we are trying to make the first argument optional, so that +@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc +first tries to match @samp{2,} against the optional part of the +pattern, finds a match, and so goes ahead to match the rest of the +pattern. Later on it will fail to match the second comma, but it +doesn't know how to go back and try the other alternative at that +point. One way to get around this would be to use two rules: + +@example +foo ( # , # , # ) := bar([#1],#2,#3) +foo ( # , # ) := bar([],#1,#2) +@end example + +More precisely, when Calc wants to match an optional or repeated +part of a pattern, it scans forward attempting to match that part. +If it reaches the end of the optional part without failing, it +``finalizes'' its choice and proceeds. If it fails, though, it +backs up and tries the other alternative. Thus Calc has ``partial'' +backtracking. A fully backtracking parser would go on to make sure +the rest of the pattern matched before finalizing the choice. + +@node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables +@subsubsection Conditional Syntax Rules + +@noindent +It is possible to attach a @dfn{condition} to a syntax rule. For +example, the rules + +@example +foo ( # ) := ifoo(#1) :: integer(#1) +foo ( # ) := gfoo(#1) +@end example + +@noindent +will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse +@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any +number of conditions may be attached; all must be true for the +rule to succeed. A condition is ``true'' if it evaluates to a +nonzero number. @xref{Logical Operations}, for a list of Calc +functions like @code{integer} that perform logical tests. + +The exact sequence of events is as follows: When Calc tries a +rule, it first matches the pattern as usual. It then substitutes +@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the +conditions are simplified and evaluated in order from left to right, +as if by the @w{@kbd{a s}} algebra command (@pxref{Simplifying Formulas}). +Each result is true if it is a nonzero number, or an expression +that can be proven to be nonzero (@pxref{Declarations}). If the +results of all conditions are true, the expression (such as +@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the +result of the parse. If the result of any condition is false, Calc +goes on to try the next rule in the syntax table. + +Syntax rules also support @code{let} conditions, which operate in +exactly the same way as they do in algebraic rewrite rules. +@xref{Other Features of Rewrite Rules}, for details. A @code{let} +condition is always true, but as a side effect it defines a +variable which can be used in later conditions, and also in the +expression after the @samp{:=} sign: + +@example +foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x) +@end example + +@noindent +The @code{dnumint} function tests if a value is numerically an +integer, i.e., either a true integer or an integer-valued float. +This rule will parse @code{foo} with a half-integer argument, +like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}. + +The lefthand side of a syntax rule @code{let} must be a simple +variable, not the arbitrary pattern that is allowed in rewrite +rules. + +The @code{matches} function is also treated specially in syntax +rule conditions (again, in the same way as in rewrite rules). +@xref{Matching Commands}. If the matching pattern contains +meta-variables, then those meta-variables may be used in later +conditions and in the result expression. The arguments to +@code{matches} are not evaluated in this situation. + +@example +sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c]) +@end example + +@noindent +This is another way to implement the Maple mode @code{sum} notation. +In this approach, we allow @samp{#2} to equal the whole expression +@samp{i=1..10}. Then, we use @code{matches} to break it apart into +its components. If the expression turns out not to match the pattern, +the syntax rule will fail. Note that @kbd{Z S} always uses Calc's +normal language mode for editing expressions in syntax rules, so we +must use regular Calc notation for the interval @samp{[b..c]} that +will correspond to the Maple mode interval @samp{1..10}. + +@node Modes Variable, Calc Mode Line, Language Modes, Mode Settings +@section The @code{Modes} Variable + +@noindent +@kindex m g +@pindex calc-get-modes +The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack +a vector of numbers that describes the various mode settings that +are in effect. With a numeric prefix argument, it pushes only the +@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard +macros can use the @kbd{m g} command to modify their behavior based +on the current mode settings. + +@cindex @code{Modes} variable +@vindex Modes +The modes vector is also available in the special variable +@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes RET}. +It will not work to store into this variable; in fact, if you do, +@code{Modes} will cease to track the current modes. (The @kbd{m g} +command will continue to work, however.) + +In general, each number in this vector is suitable as a numeric +prefix argument to the associated mode-setting command. (Recall +that the @kbd{~} key takes a number from the stack and gives it as +a numeric prefix to the next command.) + +The elements of the modes vector are as follows: + +@enumerate +@item +Current precision. Default is 12; associated command is @kbd{p}. + +@item +Binary word size. Default is 32; associated command is @kbd{b w}. + +@item +Stack size (not counting the value about to be pushed by @kbd{m g}). +This is zero if @kbd{m g} is executed with an empty stack. + +@item +Number radix. Default is 10; command is @kbd{d r}. + +@item +Floating-point format. This is the number of digits, plus the +constant 0 for normal notation, 10000 for scientific notation, +20000 for engineering notation, or 30000 for fixed-point notation. +These codes are acceptable as prefix arguments to the @kbd{d n} +command, but note that this may lose information: For example, +@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite +identical) effects if the current precision is 12, but they both +produce a code of 10012, which will be treated by @kbd{d n} as +@kbd{C-u 12 d s}. If the precision then changes, the float format +will still be frozen at 12 significant figures. + +@item +Angular mode. Default is 1 (degrees). Other values are 2 (radians) +and 3 (HMS). The @kbd{m d} command accepts these prefixes. + +@item +Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}. + +@item +Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}. + +@item +Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0. +Command is @kbd{m p}. + +@item +Matrix/scalar mode. Default value is @i{-1}. Value is 0 for scalar +mode, @i{-2} for matrix mode, or @i{N} for @c{$N\times N$} +@i{NxN} matrix mode. Command is @kbd{m v}. + +@item +Simplification mode. Default is 1. Value is @i{-1} for off (@kbd{m O}), +0 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E}, +or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes. + +@item +Infinite mode. Default is @i{-1} (off). Value is 1 if the mode is on, +or 0 if the mode is on with positive zeros. Command is @kbd{m i}. +@end enumerate + +For example, the sequence @kbd{M-1 m g RET 2 + ~ p} increases the +precision by two, leaving a copy of the old precision on the stack. +Later, @kbd{~ p} will restore the original precision using that +stack value. (This sequence might be especially useful inside a +keyboard macro.) + +As another example, @kbd{M-3 m g 1 - ~ DEL} deletes all but the +oldest (bottommost) stack entry. + +Yet another example: The HP-48 ``round'' command rounds a number +to the current displayed precision. You could roughly emulate this +in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This +would not work for fixed-point mode, but it wouldn't be hard to +do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]} +programming commands. @xref{Conditionals in Macros}.) + +@node Calc Mode Line, , Modes Variable, Mode Settings +@section The Calc Mode Line + +@noindent +@cindex Mode line indicators +This section is a summary of all symbols that can appear on the +Calc mode line, the highlighted bar that appears under the Calc +stack window (or under an editing window in Embedded Mode). + +The basic mode line format is: + +@example +--%%-Calc: 12 Deg @var{other modes} (Calculator) +@end example + +The @samp{%%} is the Emacs symbol for ``read-only''; it shows that +regular Emacs commands are not allowed to edit the stack buffer +as if it were text. + +The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded Mode +is enabled. The words after this describe the various Calc modes +that are in effect. + +The first mode is always the current precision, an integer. +The second mode is always the angular mode, either @code{Deg}, +@code{Rad}, or @code{Hms}. + +Here is a complete list of the remaining symbols that can appear +on the mode line: + +@table @code +@item Alg +Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}). + +@item Alg[( +Incomplete algebraic mode (@kbd{C-u m a}). + +@item Alg* +Total algebraic mode (@kbd{m t}). + +@item Symb +Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}). + +@item Matrix +Matrix mode (@kbd{m v}; @pxref{Matrix Mode}). + +@item Matrix@var{n} +Dimensioned matrix mode (@kbd{C-u @var{n} m v}). + +@item Scalar +Scalar mode (@kbd{m v}; @pxref{Matrix Mode}). + +@item Polar +Polar complex mode (@kbd{m p}; @pxref{Polar Mode}). + +@item Frac +Fraction mode (@kbd{m f}; @pxref{Fraction Mode}). + +@item Inf +Infinite mode (@kbd{m i}; @pxref{Infinite Mode}). + +@item +Inf +Positive infinite mode (@kbd{C-u 0 m i}). + +@item NoSimp +Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}). + +@item NumSimp +Default simplifications for numeric arguments only (@kbd{m N}). + +@item BinSimp@var{w} +Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}). + +@item AlgSimp +Algebraic simplification mode (@kbd{m A}). + +@item ExtSimp +Extended algebraic simplification mode (@kbd{m E}). + +@item UnitSimp +Units simplification mode (@kbd{m U}). + +@item Bin +Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}). + +@item Oct +Current radix is 8 (@kbd{d 8}). + +@item Hex +Current radix is 16 (@kbd{d 6}). + +@item Radix@var{n} +Current radix is @var{n} (@kbd{d r}). + +@item Zero +Leading zeros (@kbd{d z}; @pxref{Radix Modes}). + +@item Big +Big language mode (@kbd{d B}; @pxref{Normal Language Modes}). + +@item Flat +One-line normal language mode (@kbd{d O}). + +@item Unform +Unformatted language mode (@kbd{d U}). + +@item C +C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}). + +@item Pascal +Pascal language mode (@kbd{d P}). + +@item Fortran +FORTRAN language mode (@kbd{d F}). + +@item TeX +@TeX{} language mode (@kbd{d T}; @pxref{TeX Language Mode}). + +@item Eqn +@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}). + +@item Math +Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}). + +@item Maple +Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}). + +@item Norm@var{n} +Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}). + +@item Fix@var{n} +Fixed point mode with @var{n} digits after the point (@kbd{d f}). + +@item Sci +Scientific notation mode (@kbd{d s}). + +@item Sci@var{n} +Scientific notation with @var{n} digits (@kbd{d s}). + +@item Eng +Engineering notation mode (@kbd{d e}). + +@item Eng@var{n} +Engineering notation with @var{n} digits (@kbd{d e}). + +@item Left@var{n} +Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}). + +@item Right +Right-justified display (@kbd{d >}). + +@item Right@var{n} +Right-justified display with width @var{n} (@kbd{d >}). + +@item Center +Centered display (@kbd{d =}). + +@item Center@var{n} +Centered display with center column @var{n} (@kbd{d =}). + +@item Wid@var{n} +Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}). + +@item Wide +No line breaking (@kbd{d b}). + +@item Break +Selections show deep structure (@kbd{j b}; @pxref{Making Selections}). + +@item Save +Record modes in @file{~/.emacs} (@kbd{m R}; @pxref{General Mode Commands}). + +@item Local +Record modes in Embedded buffer (@kbd{m R}). + +@item LocEdit +Record modes as editing-only in Embedded buffer (@kbd{m R}). + +@item LocPerm +Record modes as permanent-only in Embedded buffer (@kbd{m R}). + +@item Global +Record modes as global in Embedded buffer (@kbd{m R}). + +@item Manual +Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic +Recomputation}). + +@item Graph +GNUPLOT process is alive in background (@pxref{Graphics}). + +@item Sel +Top-of-stack has a selection (Embedded only; @pxref{Making Selections}). + +@item Dirty +The stack display may not be up-to-date (@pxref{Display Modes}). + +@item Inv +``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}). + +@item Hyp +``Hyperbolic'' prefix was pressed (@kbd{H}). + +@item Keep +``Keep-arguments'' prefix was pressed (@kbd{K}). + +@item Narrow +Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}). +@end table + +In addition, the symbols @code{Active} and @code{~Active} can appear +as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}. + +@node Arithmetic, Scientific Functions, Mode Settings, Top +@chapter Arithmetic Functions + +@noindent +This chapter describes the Calc commands for doing simple calculations +on numbers, such as addition, absolute value, and square roots. These +commands work by removing the top one or two values from the stack, +performing the desired operation, and pushing the result back onto the +stack. If the operation cannot be performed, the result pushed is a +formula instead of a number, such as @samp{2/0} (because division by zero +is illegal) or @samp{sqrt(x)} (because the argument @samp{x} is a formula). + +Most of the commands described here can be invoked by a single keystroke. +Some of the more obscure ones are two-letter sequences beginning with +the @kbd{f} (``functions'') prefix key. + +@xref{Prefix Arguments}, for a discussion of the effect of numeric +prefix arguments on commands in this chapter which do not otherwise +interpret a prefix argument. + +@menu +* Basic Arithmetic:: +* Integer Truncation:: +* Complex Number Functions:: +* Conversions:: +* Date Arithmetic:: +* Financial Functions:: +* Binary Functions:: +@end menu + +@node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic +@section Basic Arithmetic + +@noindent +@kindex + +@pindex calc-plus +@c @mindex @null +@tindex + +The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may +be any of the standard Calc data types. The resulting sum is pushed back +onto the stack. + +If both arguments of @kbd{+} are vectors or matrices (of matching dimensions), +the result is a vector or matrix sum. If one argument is a vector and the +other a scalar (i.e., a non-vector), the scalar is added to each of the +elements of the vector to form a new vector. If the scalar is not a +number, the operation is left in symbolic form: Suppose you added @samp{x} +to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or +you may plan to substitute a 2-vector for @samp{x} in the future. Since +the Calculator can't tell which interpretation you want, it makes the +safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x} +to every element of a vector. + +If either argument of @kbd{+} is a complex number, the result will in general +be complex. If one argument is in rectangular form and the other polar, +the current Polar Mode determines the form of the result. If Symbolic +Mode is enabled, the sum may be left as a formula if the necessary +conversions for polar addition are non-trivial. + +If both arguments of @kbd{+} are HMS forms, the forms are added according to +the usual conventions of hours-minutes-seconds notation. If one argument +is an HMS form and the other is a number, that number is converted from +degrees or radians (depending on the current Angular Mode) to HMS format +and then the two HMS forms are added. + +If one argument of @kbd{+} is a date form, the other can be either a +real number, which advances the date by a certain number of days, or +an HMS form, which advances the date by a certain amount of time. +Subtracting two date forms yields the number of days between them. +Adding two date forms is meaningless, but Calc interprets it as the +subtraction of one date form and the negative of the other. (The +negative of a date form can be understood by remembering that dates +are stored as the number of days before or after Jan 1, 1 AD.) + +If both arguments of @kbd{+} are error forms, the result is an error form +with an appropriately computed standard deviation. If one argument is an +error form and the other is a number, the number is taken to have zero error. +Error forms may have symbolic formulas as their mean and/or error parts; +adding these will produce a symbolic error form result. However, adding an +error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not +work, for the same reasons just mentioned for vectors. Instead you must +write @samp{(a +/- b) + (c +/- 0)}. + +If both arguments of @kbd{+} are modulo forms with equal values of @cite{M}, +or if one argument is a modulo form and the other a plain number, the +result is a modulo form which represents the sum, modulo @cite{M}, of +the two values. + +If both arguments of @kbd{+} are intervals, the result is an interval +which describes all possible sums of the possible input values. If +one argument is a plain number, it is treated as the interval +@w{@samp{[x ..@: x]}}. + +If one argument of @kbd{+} is an infinity and the other is not, the +result is that same infinity. If both arguments are infinite and in +the same direction, the result is the same infinity, but if they are +infinite in different directions the result is @code{nan}. + +@kindex - +@pindex calc-minus +@c @mindex @null +@tindex - +The @kbd{-} (@code{calc-minus}) command subtracts two values. The top +number on the stack is subtracted from the one behind it, so that the +computation @kbd{5 @key{RET} 2 -} produces 3, not @i{-3}. All options +available for @kbd{+} are available for @kbd{-} as well. + +@kindex * +@pindex calc-times +@c @mindex @null +@tindex * +The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one +argument is a vector and the other a scalar, the scalar is multiplied by +the elements of the vector to produce a new vector. If both arguments +are vectors, the interpretation depends on the dimensions of the +vectors: If both arguments are matrices, a matrix multiplication is +done. If one argument is a matrix and the other a plain vector, the +vector is interpreted as a row vector or column vector, whichever is +dimensionally correct. If both arguments are plain vectors, the result +is a single scalar number which is the dot product of the two vectors. + +If one argument of @kbd{*} is an HMS form and the other a number, the +HMS form is multiplied by that amount. It is an error to multiply two +HMS forms together, or to attempt any multiplication involving date +forms. Error forms, modulo forms, and intervals can be multiplied; +see the comments for addition of those forms. When two error forms +or intervals are multiplied they are considered to be statistically +independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]}, +whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}. + +@kindex / +@pindex calc-divide +@c @mindex @null +@tindex / +The @kbd{/} (@code{calc-divide}) command divides two numbers. When +dividing a scalar @cite{B} by a square matrix @cite{A}, the computation +performed is @cite{B} times the inverse of @cite{A}. This also occurs +if @cite{B} is itself a vector or matrix, in which case the effect is +to solve the set of linear equations represented by @cite{B}. If @cite{B} +is a matrix with the same number of rows as @cite{A}, or a plain vector +(which is interpreted here as a column vector), then the equation +@cite{A X = B} is solved for the vector or matrix @cite{X}. Otherwise, +if @cite{B} is a non-square matrix with the same number of @emph{columns} +as @cite{A}, the equation @cite{X A = B} is solved. If you wish a vector +@cite{B} to be interpreted as a row vector to be solved as @cite{X A = B}, +make it into a one-row matrix with @kbd{C-u 1 v p} first. To force a +left-handed solution with a square matrix @cite{B}, transpose @cite{A} and +@cite{B} before dividing, then transpose the result. + +HMS forms can be divided by real numbers or by other HMS forms. Error +forms can be divided in any combination of ways. Modulo forms where both +values and the modulo are integers can be divided to get an integer modulo +form result. Intervals can be divided; dividing by an interval that +encompasses zero or has zero as a limit will result in an infinite +interval. + +@kindex ^ +@pindex calc-power +@c @mindex @null +@tindex ^ +The @kbd{^} (@code{calc-power}) command raises a number to a power. If +the power is an integer, an exact result is computed using repeated +multiplications. For non-integer powers, Calc uses Newton's method or +logarithms and exponentials. Square matrices can be raised to integer +powers. If either argument is an error (or interval or modulo) form, +the result is also an error (or interval or modulo) form. + +@kindex I ^ +@tindex nroot +If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command +computes an Nth root: @kbd{125 RET 3 I ^} computes the number 5. +(This is entirely equivalent to @kbd{125 RET 1:3 ^}.) + +@kindex \ +@pindex calc-idiv +@tindex idiv +@c @mindex @null +@tindex \ +The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack +to produce an integer result. It is equivalent to dividing with +@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit +more convenient and efficient. Also, since it is an all-integer +operation when the arguments are integers, it avoids problems that +@kbd{/ F} would have with floating-point roundoff. + +@kindex % +@pindex calc-mod +@c @mindex @null +@tindex % +The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'') +operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined +for all real numbers @cite{a} and @cite{b} (except @cite{b=0}). For +positive @cite{b}, the result will always be between 0 (inclusive) and +@cite{b} (exclusive). Modulo does not work for HMS forms and error forms. +If @cite{a} is a modulo form, its modulo is changed to @cite{b}, which +must be positive real number. + +@kindex : +@pindex calc-fdiv +@tindex fdiv +The @kbd{:} (@code{calc-fdiv}) command [@code{fdiv} function in a formula] +divides the two integers on the top of the stack to produce a fractional +result. This is a convenient shorthand for enabling Fraction Mode (with +@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry +the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6 +you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in +this case, it would be much easier simply to enter the fraction directly +as @kbd{8:6 @key{RET}}!) + +@kindex n +@pindex calc-change-sign +The @kbd{n} (@code{calc-change-sign}) command negates the number on the top +of the stack. It works on numbers, vectors and matrices, HMS forms, date +forms, error forms, intervals, and modulo forms. + +@kindex A +@pindex calc-abs +@tindex abs +The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute +value of a number. The result of @code{abs} is always a nonnegative +real number: With a complex argument, it computes the complex magnitude. +With a vector or matrix argument, it computes the Frobenius norm, i.e., +the square root of the sum of the squares of the absolute values of the +elements. The absolute value of an error form is defined by replacing +the mean part with its absolute value and leaving the error part the same. +The absolute value of a modulo form is undefined. The absolute value of +an interval is defined in the obvious way. + +@kindex f A +@pindex calc-abssqr +@tindex abssqr +The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the +absolute value squared of a number, vector or matrix, or error form. + +@kindex f s +@pindex calc-sign +@tindex sign +The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its +argument is positive, @i{-1} if its argument is negative, or 0 if its +argument is zero. In algebraic form, you can also write @samp{sign(a,x)} +which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or +zero depending on the sign of @samp{a}. + +@kindex & +@pindex calc-inv +@tindex inv +@cindex Reciprocal +The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the +reciprocal of a number, i.e., @cite{1 / x}. Operating on a square +matrix, it computes the inverse of that matrix. + +@kindex Q +@pindex calc-sqrt +@tindex sqrt +The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square +root of a number. For a negative real argument, the result will be a +complex number whose form is determined by the current Polar Mode. + +@kindex f h +@pindex calc-hypot +@tindex hypot +The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square +root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)} +is the length of the hypotenuse of a right triangle with sides @cite{a} +and @cite{b}. If the arguments are complex numbers, their squared +magnitudes are used. + +@kindex f Q +@pindex calc-isqrt +@tindex isqrt +The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the +integer square root of an integer. This is the true square root of the +number, rounded down to an integer. For example, @samp{isqrt(10)} +produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact +integer arithmetic throughout to avoid roundoff problems. If the input +is a floating-point number or other non-integer value, this is exactly +the same as @samp{floor(sqrt(x))}. + +@kindex f n +@kindex f x +@pindex calc-min +@tindex min +@pindex calc-max +@tindex max +The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max}) +[@code{max}] commands take the minimum or maximum of two real numbers, +respectively. These commands also work on HMS forms, date forms, +intervals, and infinities. (In algebraic expressions, these functions +take any number of arguments and return the maximum or minimum among +all the arguments.)@refill + +@kindex f M +@kindex f X +@pindex calc-mant-part +@tindex mant +@pindex calc-xpon-part +@tindex xpon +The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts +the ``mantissa'' part @cite{m} of its floating-point argument; @kbd{f X} +(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part +@cite{e}. The original number is equal to @c{$m \times 10^e$} +@cite{m * 10^e}, +where @cite{m} is in the interval @samp{[1.0 ..@: 10.0)} except that +@cite{m=e=0} if the original number is zero. For integers +and fractions, @code{mant} returns the number unchanged and @code{xpon} +returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be +used to ``unpack'' a floating-point number; this produces an integer +mantissa and exponent, with the constraint that the mantissa is not +a multiple of ten (again except for the @cite{m=e=0} case).@refill + +@kindex f S +@pindex calc-scale-float +@tindex scf +The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number +by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any +real @samp{x}. The second argument must be an integer, but the first +may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05} +or @samp{1:20} depending on the current Fraction Mode.@refill + +@kindex f [ +@kindex f ] +@pindex calc-decrement +@pindex calc-increment +@tindex decr +@tindex incr +The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]} +(@code{calc-increment}) [@code{incr}] functions decrease or increase +a number by one unit. For integers, the effect is obvious. For +floating-point numbers, the change is by one unit in the last place. +For example, incrementing @samp{12.3456} when the current precision +is 6 digits yields @samp{12.3457}. If the current precision had been +8 digits, the result would have been @samp{12.345601}. Incrementing +@samp{0.0} produces @c{$10^{-p}$} +@cite{10^-p}, where @cite{p} is the current +precision. These operations are defined only on integers and floats. +With numeric prefix arguments, they change the number by @cite{n} units. + +Note that incrementing followed by decrementing, or vice-versa, will +almost but not quite always cancel out. Suppose the precision is +6 digits and the number @samp{9.99999} is on the stack. Incrementing +will produce @samp{10.0000}; decrementing will produce @samp{9.9999}. +One digit has been dropped. This is an unavoidable consequence of the +way floating-point numbers work. + +Incrementing a date/time form adjusts it by a certain number of seconds. +Incrementing a pure date form adjusts it by a certain number of days. + +@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic +@section Integer Truncation + +@noindent +There are four commands for truncating a real number to an integer, +differing mainly in their treatment of negative numbers. All of these +commands have the property that if the argument is an integer, the result +is the same integer. An integer-valued floating-point argument is converted +to integer form. + +If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be +expressed as an integer-valued floating-point number. + +@cindex Integer part of a number +@kindex F +@pindex calc-floor +@tindex floor +@tindex ffloor +@c @mindex @null +@kindex H F +The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command +truncates a real number to the next lower integer, i.e., toward minus +infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces +@i{-4}.@refill + +@kindex I F +@pindex calc-ceiling +@tindex ceil +@tindex fceil +@c @mindex @null +@kindex H I F +The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}] +command truncates toward positive infinity. Thus @kbd{3.6 I F} produces +4, and @kbd{_3.6 I F} produces @i{-3}.@refill + +@kindex R +@pindex calc-round +@tindex round +@tindex fround +@c @mindex @null +@kindex H R +The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command +rounds to the nearest integer. When the fractional part is .5 exactly, +this command rounds away from zero. (All other rounding in the +Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4 +but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @i{-4}.@refill + +@kindex I R +@pindex calc-trunc +@tindex trunc +@tindex ftrunc +@c @mindex @null +@kindex H I R +The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}] +command truncates toward zero. In other words, it ``chops off'' +everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and +@kbd{_3.6 I R} produces @i{-3}.@refill + +These functions may not be applied meaningfully to error forms, but they +do work for intervals. As a convenience, applying @code{floor} to a +modulo form floors the value part of the form. Applied to a vector, +these functions operate on all elements of the vector one by one. +Applied to a date form, they operate on the internal numerical +representation of dates, converting a date/time form into a pure date. + +@c @starindex +@tindex rounde +@c @starindex +@tindex roundu +@c @starindex +@tindex frounde +@c @starindex +@tindex froundu +There are two more rounding functions which can only be entered in +algebraic notation. The @code{roundu} function is like @code{round} +except that it rounds up, toward plus infinity, when the fractional +part is .5. This distinction matters only for negative arguments. +Also, @code{rounde} rounds to an even number in the case of a tie, +rounding up or down as necessary. For example, @samp{rounde(3.5)} and +@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6. +The advantage of round-to-even is that the net error due to rounding +after a long calculation tends to cancel out to zero. An important +subtle point here is that the number being fed to @code{rounde} will +already have been rounded to the current precision before @code{rounde} +begins. For example, @samp{rounde(2.500001)} with a current precision +of 6 will incorrectly, or at least surprisingly, yield 2 because the +argument will first have been rounded down to @cite{2.5} (which +@code{rounde} sees as an exact tie between 2 and 3). + +Each of these functions, when written in algebraic formulas, allows +a second argument which specifies the number of digits after the +decimal point to keep. For example, @samp{round(123.4567, 2)} will +produce the answer 123.46, and @samp{round(123.4567, -1)} will +produce 120 (i.e., the cutoff is one digit to the @emph{left} of +the decimal point). A second argument of zero is equivalent to +no second argument at all. + +@cindex Fractional part of a number +To compute the fractional part of a number (i.e., the amount which, when +added to `@t{floor(}@i{N}@t{)}', will produce @cite{N}) just take @cite{N} +modulo 1 using the @code{%} command.@refill + +Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm), +and @kbd{f Q} (integer square root) commands, which are analogous to +@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer +arguments and return the result rounded down to an integer. + +@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic +@section Complex Number Functions + +@noindent +@kindex J +@pindex calc-conj +@tindex conj +The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the +complex conjugate of a number. For complex number @cite{a+bi}, the +complex conjugate is @cite{a-bi}. If the argument is a real number, +this command leaves it the same. If the argument is a vector or matrix, +this command replaces each element by its complex conjugate. + +@kindex G +@pindex calc-argument +@tindex arg +The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the +``argument'' or polar angle of a complex number. For a number in polar +notation, this is simply the second component of the pair +`@t{(}@i{r}@t{;}@c{$\theta$} +@i{theta}@t{)}'. +The result is expressed according to the current angular mode and will +be in the range @i{-180} degrees (exclusive) to @i{+180} degrees +(inclusive), or the equivalent range in radians.@refill + +@pindex calc-imaginary +The @code{calc-imaginary} command multiplies the number on the +top of the stack by the imaginary number @cite{i = (0,1)}. This +command is not normally bound to a key in Calc, but it is available +on the @key{IMAG} button in Keypad Mode. + +@kindex f r +@pindex calc-re +@tindex re +The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number +by its real part. This command has no effect on real numbers. (As an +added convenience, @code{re} applied to a modulo form extracts +the value part.)@refill + +@kindex f i +@pindex calc-im +@tindex im +The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number +by its imaginary part; real numbers are converted to zero. With a vector +or matrix argument, these functions operate element-wise.@refill + +@c @mindex v p +@kindex v p (complex) +@pindex calc-pack +The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on +the the stack into a composite object such as a complex number. With +a prefix argument of @i{-1}, it produces a rectangular complex number; +with an argument of @i{-2}, it produces a polar complex number. +(Also, @pxref{Building Vectors}.) + +@c @mindex v u +@kindex v u (complex) +@pindex calc-unpack +The @kbd{v u} (@code{calc-unpack}) command takes the complex number +(or other composite object) on the top of the stack and unpacks it +into its separate components. + +@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic +@section Conversions + +@noindent +The commands described in this section convert numbers from one form +to another; they are two-key sequences beginning with the letter @kbd{c}. + +@kindex c f +@pindex calc-float +@tindex pfloat +The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the +number on the top of the stack to floating-point form. For example, +@cite{23} is converted to @cite{23.0}, @cite{3:2} is converted to +@cite{1.5}, and @cite{2.3} is left the same. If the value is a composite +object such as a complex number or vector, each of the components is +converted to floating-point. If the value is a formula, all numbers +in the formula are converted to floating-point. Note that depending +on the current floating-point precision, conversion to floating-point +format may lose information.@refill + +As a special exception, integers which appear as powers or subscripts +are not floated by @kbd{c f}. If you really want to float a power, +you can use a @kbd{j s} command to select the power followed by @kbd{c f}. +Because @kbd{c f} cannot examine the formula outside of the selection, +it does not notice that the thing being floated is a power. +@xref{Selecting Subformulas}. + +The normal @kbd{c f} command is ``pervasive'' in the sense that it +applies to all numbers throughout the formula. The @code{pfloat} +algebraic function never stays around in a formula; @samp{pfloat(a + 1)} +changes to @samp{a + 1.0} as soon as it is evaluated. + +@kindex H c f +@tindex float +With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates +only on the number or vector of numbers at the top level of its +argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)} +is left unevaluated because its argument is not a number. + +You should use @kbd{H c f} if you wish to guarantee that the final +value, once all the variables have been assigned, is a float; you +would use @kbd{c f} if you wish to do the conversion on the numbers +that appear right now. + +@kindex c F +@pindex calc-fraction +@tindex pfrac +The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a +floating-point number into a fractional approximation. By default, it +produces a fraction whose decimal representation is the same as the +input number, to within the current precision. You can also give a +numeric prefix argument to specify a tolerance, either directly, or, +if the prefix argument is zero, by using the number on top of the stack +as the tolerance. If the tolerance is a positive integer, the fraction +is correct to within that many significant figures. If the tolerance is +a non-positive integer, it specifies how many digits fewer than the current +precision to use. If the tolerance is a floating-point number, the +fraction is correct to within that absolute amount. + +@kindex H c F +@tindex frac +The @code{pfrac} function is pervasive, like @code{pfloat}. +There is also a non-pervasive version, @kbd{H c F} [@code{frac}], +which is analogous to @kbd{H c f} discussed above. + +@kindex c d +@pindex calc-to-degrees +@tindex deg +The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a +number into degrees form. The value on the top of the stack may be an +HMS form (interpreted as degrees-minutes-seconds), or a real number which +will be interpreted in radians regardless of the current angular mode.@refill + +@kindex c r +@pindex calc-to-radians +@tindex rad +The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an +HMS form or angle in degrees into an angle in radians. + +@kindex c h +@pindex calc-to-hms +@tindex hms +The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real +number, interpreted according to the current angular mode, to an HMS +form describing the same angle. In algebraic notation, the @code{hms} +function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}. +(The three-argument version is independent of the current angular mode.) + +@pindex calc-from-hms +The @code{calc-from-hms} command converts the HMS form on the top of the +stack into a real number according to the current angular mode. + +@kindex c p +@kindex I c p +@pindex calc-polar +@tindex polar +@tindex rect +The @kbd{c p} (@code{calc-polar}) command converts the complex number on +the top of the stack from polar to rectangular form, or from rectangular +to polar form, whichever is appropriate. Real numbers are left the same. +This command is equivalent to the @code{rect} or @code{polar} +functions in algebraic formulas, depending on the direction of +conversion. (It uses @code{polar}, except that if the argument is +already a polar complex number, it uses @code{rect} instead. The +@kbd{I c p} command always uses @code{rect}.)@refill + +@kindex c c +@pindex calc-clean +@tindex pclean +The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the +number on the top of the stack. Floating point numbers are re-rounded +according to the current precision. Polar numbers whose angular +components have strayed from the @i{-180} to @i{+180} degree range +are normalized. (Note that results will be undesirable if the current +angular mode is different from the one under which the number was +produced!) Integers and fractions are generally unaffected by this +operation. Vectors and formulas are cleaned by cleaning each component +number (i.e., pervasively).@refill + +If the simplification mode is set below the default level, it is raised +to the default level for the purposes of this command. Thus, @kbd{c c} +applies the default simplifications even if their automatic application +is disabled. @xref{Simplification Modes}. + +@cindex Roundoff errors, correcting +A numeric prefix argument to @kbd{c c} sets the floating-point precision +to that value for the duration of the command. A positive prefix (of at +least 3) sets the precision to the specified value; a negative or zero +prefix decreases the precision by the specified amount. + +@kindex c 0-9 +@pindex calc-clean-num +The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent +to @kbd{c c} with the corresponding negative prefix argument. If roundoff +errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one +decimal place often conveniently does the trick. + +The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0} +through @kbd{c 9} commands, also ``clip'' very small floating-point +numbers to zero. If the exponent is less than or equal to the negative +of the specified precision, the number is changed to 0.0. For example, +if the current precision is 12, then @kbd{c 2} changes the vector +@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}. +Numbers this small generally arise from roundoff noise. + +If the numbers you are using really are legitimately this small, +you should avoid using the @kbd{c 0} through @kbd{c 9} commands. +(The plain @kbd{c c} command rounds to the current precision but +does not clip small numbers.) + +One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with +a prefix argument, is that integer-valued floats are converted to +plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]} +produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge +numbers (@samp{1e100} is technically an integer-valued float, but +you wouldn't want it automatically converted to a 100-digit integer). + +@kindex H c 0-9 +@kindex H c c +@tindex clean +With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9} +operate non-pervasively [@code{clean}]. + +@node Date Arithmetic, Financial Functions, Conversions, Arithmetic +@section Date Arithmetic + +@noindent +@cindex Date arithmetic, additional functions +The commands described in this section perform various conversions +and calculations involving date forms (@pxref{Date Forms}). They +use the @kbd{t} (for time/date) prefix key followed by shifted +letters. + +The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-} +commands. In particular, adding a number to a date form advances the +date form by a certain number of days; adding an HMS form to a date +form advances the date by a certain amount of time; and subtracting two +date forms produces a difference measured in days. The commands +described here provide additional, more specialized operations on dates. + +Many of these commands accept a numeric prefix argument; if you give +plain @kbd{C-u} as the prefix, these commands will instead take the +additional argument from the top of the stack. + +@menu +* Date Conversions:: +* Date Functions:: +* Time Zones:: +* Business Days:: +@end menu + +@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic +@subsection Date Conversions + +@noindent +@kindex t D +@pindex calc-date +@tindex date +The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a +date form into a number, measured in days since Jan 1, 1 AD. The +result will be an integer if @var{date} is a pure date form, or a +fraction or float if @var{date} is a date/time form. Or, if its +argument is a number, it converts this number into a date form. + +With a numeric prefix argument, @kbd{t D} takes that many objects +(up to six) from the top of the stack and interprets them in one +of the following ways: + +The @samp{date(@var{year}, @var{month}, @var{day})} function +builds a pure date form out of the specified year, month, and +day, which must all be integers. @var{Year} is a year number, +such as 1991 (@emph{not} the same as 91!). @var{Month} must be +an integer in the range 1 to 12; @var{day} must be in the range +1 to 31. If the specified month has fewer than 31 days and +@var{day} is too large, the equivalent day in the following +month will be used. + +The @samp{date(@var{month}, @var{day})} function builds a +pure date form using the current year, as determined by the +real-time clock. + +The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})} +function builds a date/time form using an @var{hms} form. + +The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour}, +@var{minute}, @var{second})} function builds a date/time form. +@var{hour} should be an integer in the range 0 to 23; +@var{minute} should be an integer in the range 0 to 59; +@var{second} should be any real number in the range @samp{[0 .. 60)}. +The last two arguments default to zero if omitted. + +@kindex t J +@pindex calc-julian +@tindex julian +@cindex Julian day counts, conversions +The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts +a date form into a Julian day count, which is the number of days +since noon on Jan 1, 4713 BC. A pure date is converted to an integer +Julian count representing noon of that day. A date/time form is +converted to an exact floating-point Julian count, adjusted to +interpret the date form in the current time zone but the Julian +day count in Greenwich Mean Time. A numeric prefix argument allows +you to specify the time zone; @pxref{Time Zones}. Use a prefix of +zero to suppress the time zone adjustment. Note that pure date forms +are never time-zone adjusted. + +This command can also do the opposite conversion, from a Julian day +count (either an integer day, or a floating-point day and time in +the GMT zone), into a pure date form or a date/time form in the +current or specified time zone. + +@kindex t U +@pindex calc-unix-time +@tindex unixtime +@cindex Unix time format, conversions +The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command +converts a date form into a Unix time value, which is the number of +seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result +will be an integer if the current precision is 12 or less; for higher +precisions, the result may be a float with (@var{precision}@i{-}12) +digits after the decimal. Just as for @kbd{t J}, the numeric time +is interpreted in the GMT time zone and the date form is interpreted +in the current or specified zone. Some systems use Unix-like +numbering but with the local time zone; give a prefix of zero to +suppress the adjustment if so. + +@kindex t C +@pindex calc-convert-time-zones +@tindex tzconv +@cindex Time Zones, converting between +The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}] +command converts a date form from one time zone to another. You +are prompted for each time zone name in turn; you can answer with +any suitable Calc time zone expression (@pxref{Time Zones}). +If you answer either prompt with a blank line, the local time +zone is used for that prompt. You can also answer the first +prompt with @kbd{$} to take the two time zone names from the +stack (and the date to be converted from the third stack level). + +@node Date Functions, Business Days, Date Conversions, Date Arithmetic +@subsection Date Functions + +@noindent +@kindex t N +@pindex calc-now +@tindex now +The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the +current date and time on the stack as a date form. The time is +reported in terms of the specified time zone; with no numeric prefix +argument, @kbd{t N} reports for the current time zone. + +@kindex t P +@pindex calc-date-part +The @kbd{t P} (@code{calc-date-part}) command extracts one part +of a date form. The prefix argument specifies the part; with no +argument, this command prompts for a part code from 1 to 9. +The various part codes are described in the following paragraphs. + +@tindex year +The @kbd{M-1 t P} [@code{year}] function extracts the year number +from a date form as an integer, e.g., 1991. This and the +following functions will also accept a real number for an +argument, which is interpreted as a standard Calc day number. +Note that this function will never return zero, since the year +1 BC immediately precedes the year 1 AD. + +@tindex month +The @kbd{M-2 t P} [@code{month}] function extracts the month number +from a date form as an integer in the range 1 to 12. + +@tindex day +The @kbd{M-3 t P} [@code{day}] function extracts the day number +from a date form as an integer in the range 1 to 31. + +@tindex hour +The @kbd{M-4 t P} [@code{hour}] function extracts the hour from +a date form as an integer in the range 0 (midnight) to 23. Note +that 24-hour time is always used. This returns zero for a pure +date form. This function (and the following two) also accept +HMS forms as input. + +@tindex minute +The @kbd{M-5 t P} [@code{minute}] function extracts the minute +from a date form as an integer in the range 0 to 59. + +@tindex second +The @kbd{M-6 t P} [@code{second}] function extracts the second +from a date form. If the current precision is 12 or less, +the result is an integer in the range 0 to 59. For higher +precisions, the result may instead be a floating-point number. + +@tindex weekday +The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday +number from a date form as an integer in the range 0 (Sunday) +to 6 (Saturday). + +@tindex yearday +The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year +number from a date form as an integer in the range 1 (January 1) +to 366 (December 31 of a leap year). + +@tindex time +The @kbd{M-9 t P} [@code{time}] function extracts the time portion +of a date form as an HMS form. This returns @samp{0@@ 0' 0"} +for a pure date form. + +@kindex t M +@pindex calc-new-month +@tindex newmonth +The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command +computes a new date form that represents the first day of the month +specified by the input date. The result is always a pure date +form; only the year and month numbers of the input are retained. +With a numeric prefix argument @var{n} in the range from 1 to 31, +@kbd{t M} computes the @var{n}th day of the month. (If @var{n} +is greater than the actual number of days in the month, or if +@var{n} is zero, the last day of the month is used.) + +@kindex t Y +@pindex calc-new-year +@tindex newyear +The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command +computes a new pure date form that represents the first day of +the year specified by the input. The month, day, and time +of the input date form are lost. With a numeric prefix argument +@var{n} in the range from 1 to 366, @kbd{t Y} computes the +@var{n}th day of the year (366 is treated as 365 in non-leap +years). A prefix argument of 0 computes the last day of the +year (December 31). A negative prefix argument from @i{-1} to +@i{-12} computes the first day of the @var{n}th month of the year. + +@kindex t W +@pindex calc-new-week +@tindex newweek +The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command +computes a new pure date form that represents the Sunday on or before +the input date. With a numeric prefix argument, it can be made to +use any day of the week as the starting day; the argument must be in +the range from 0 (Sunday) to 6 (Saturday). This function always +subtracts between 0 and 6 days from the input date. + +Here's an example use of @code{newweek}: Find the date of the next +Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)} +will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)} +will give you the following Wednesday. A further look at the definition +of @code{newweek} shows that if the input date is itself a Wednesday, +this formula will return the Wednesday one week in the future. An +exercise for the reader is to modify this formula to yield the same day +if the input is already a Wednesday. Another interesting exercise is +to preserve the time-of-day portion of the input (@code{newweek} resets +the time to midnight; hint:@: how can @code{newweek} be defined in terms +of the @code{weekday} function?). + +@c @starindex +@tindex pwday +The @samp{pwday(@var{date})} function (not on any key) computes the +day-of-month number of the Sunday on or before @var{date}. With +two arguments, @samp{pwday(@var{date}, @var{day})} computes the day +number of the Sunday on or before day number @var{day} of the month +specified by @var{date}. The @var{day} must be in the range from +7 to 31; if the day number is greater than the actual number of days +in the month, the true number of days is used instead. Thus +@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and +@samp{pwday(@var{date}, 31)} finds the last Sunday of the month. +With a third @var{weekday} argument, @code{pwday} can be made to look +for any day of the week instead of Sunday. + +@kindex t I +@pindex calc-inc-month +@tindex incmonth +The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command +increases a date form by one month, or by an arbitrary number of +months specified by a numeric prefix argument. The time portion, +if any, of the date form stays the same. The day also stays the +same, except that if the new month has fewer days the day +number may be reduced to lie in the valid range. For example, +@samp{incmonth(<Jan 31, 1991>)} produces @samp{<Feb 28, 1991>}. +Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give +the same results (@samp{<Mar 28, 1991>} versus @samp{<Mar 31, 1991>} +in this case). + +@c @starindex +@tindex incyear +The @samp{incyear(@var{date}, @var{step})} function increases +a date form by the specified number of years, which may be +any positive or negative integer. Note that @samp{incyear(d, n)} +is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have +simple equivalents in terms of day arithmetic because +months and years have varying lengths. If the @var{step} +argument is omitted, 1 year is assumed. There is no keyboard +command for this function; use @kbd{C-u 12 t I} instead. + +There is no @code{newday} function at all because @kbd{F} [@code{floor}] +serves this purpose. Similarly, instead of @code{incday} and +@code{incweek} simply use @cite{d + n} or @cite{d + 7 n}. + +@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command +which can adjust a date/time form by a certain number of seconds. + +@node Business Days, Time Zones, Date Functions, Date Arithmetic +@subsection Business Days + +@noindent +Often time is measured in ``business days'' or ``working days,'' +where weekends and holidays are skipped. Calc's normal date +arithmetic functions use calendar days, so that subtracting two +consecutive Mondays will yield a difference of 7 days. By contrast, +subtracting two consecutive Mondays would yield 5 business days +(assuming two-day weekends and the absence of holidays). + +@kindex t + +@kindex t - +@tindex badd +@tindex bsub +@pindex calc-business-days-plus +@pindex calc-business-days-minus +The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}] +and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}] +commands perform arithmetic using business days. For @kbd{t +}, +one argument must be a date form and the other must be a real +number (positive or negative). If the number is not an integer, +then a certain amount of time is added as well as a number of +days; for example, adding 0.5 business days to a time in Friday +evening will produce a time in Monday morning. It is also +possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds +half a business day. For @kbd{t -}, the arguments are either a +date form and a number or HMS form, or two date forms, in which +case the result is the number of business days between the two +dates. + +@cindex @code{Holidays} variable +@vindex Holidays +By default, Calc considers any day that is not a Saturday or +Sunday to be a business day. You can define any number of +additional holidays by editing the variable @code{Holidays}. +(There is an @w{@kbd{s H}} convenience command for editing this +variable.) Initially, @code{Holidays} contains the vector +@samp{[sat, sun]}. Entries in the @code{Holidays} vector may +be any of the following kinds of objects: + +@itemize @bullet +@item +Date forms (pure dates, not date/time forms). These specify +particular days which are to be treated as holidays. + +@item +Intervals of date forms. These specify a range of days, all of +which are holidays (e.g., Christmas week). @xref{Interval Forms}. + +@item +Nested vectors of date forms. Each date form in the vector is +considered to be a holiday. + +@item +Any Calc formula which evaluates to one of the above three things. +If the formula involves the variable @cite{y}, it stands for a +yearly repeating holiday; @cite{y} will take on various year +numbers like 1992. For example, @samp{date(y, 12, 25)} specifies +Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies +Thanksgiving (which is held on the fourth Thursday of November). +If the formula involves the variable @cite{m}, that variable +takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is +a holiday that takes place on the 15th of every month. + +@item +A weekday name, such as @code{sat} or @code{sun}. This is really +a variable whose name is a three-letter, lower-case day name. + +@item +An interval of year numbers (integers). This specifies the span of +years over which this holiday list is to be considered valid. Any +business-day arithmetic that goes outside this range will result +in an error message. Use this if you are including an explicit +list of holidays, rather than a formula to generate them, and you +want to make sure you don't accidentally go beyond the last point +where the holidays you entered are complete. If there is no +limiting interval in the @code{Holidays} vector, the default +@samp{[1 .. 2737]} is used. (This is the absolute range of years +for which Calc's business-day algorithms will operate.) + +@item +An interval of HMS forms. This specifies the span of hours that +are to be considered one business day. For example, if this +range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then +the business day is only eight hours long, so that @kbd{1.5 t +} +on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and +four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}. +Likewise, @kbd{t -} will now express differences in time as +fractions of an eight-hour day. Times before 9am will be treated +as 9am by business date arithmetic, and times at or after 5pm will +be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays}, +the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed. +(Regardless of the type of bounds you specify, the interval is +treated as inclusive on the low end and exclusive on the high end, +so that the work day goes from 9am up to, but not including, 5pm.) +@end itemize + +If the @code{Holidays} vector is empty, then @kbd{t +} and +@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will +then be no difference between business days and calendar days. + +Calc expands the intervals and formulas you give into a complete +list of holidays for internal use. This is done mainly to make +sure it can detect multiple holidays. (For example, +@samp{<Jan 1, 1989>} is both New Year's Day and a Sunday, but +Calc's algorithms take care to count it only once when figuring +the number of holidays between two dates.) + +Since the complete list of holidays for all the years from 1 to +2737 would be huge, Calc actually computes only the part of the +list between the smallest and largest years that have been involved +in business-day calculations so far. Normally, you won't have to +worry about this. Keep in mind, however, that if you do one +calculation for 1992, and another for 1792, even if both involve +only a small range of years, Calc will still work out all the +holidays that fall in that 200-year span. + +If you add a (positive) number of days to a date form that falls on a +weekend or holiday, the date form is treated as if it were the most +recent business day. (Thus adding one business day to a Friday, +Saturday, or Sunday will all yield the following Monday.) If you +subtract a number of days from a weekend or holiday, the date is +effectively on the following business day. (So subtracting one business +day from Saturday, Sunday, or Monday yields the preceding Friday.) The +difference between two dates one or both of which fall on holidays +equals the number of actual business days between them. These +conventions are consistent in the sense that, if you add @var{n} +business days to any date, the difference between the result and the +original date will come out to @var{n} business days. (It can't be +completely consistent though; a subtraction followed by an addition +might come out a bit differently, since @kbd{t +} is incapable of +producing a date that falls on a weekend or holiday.) + +@c @starindex +@tindex holiday +There is a @code{holiday} function, not on any keys, that takes +any date form and returns 1 if that date falls on a weekend or +holiday, as defined in @code{Holidays}, or 0 if the date is a +business day. + +@node Time Zones, , Business Days, Date Arithmetic +@subsection Time Zones + +@noindent +@cindex Time zones +@cindex Daylight savings time +Time zones and daylight savings time are a complicated business. +The conversions to and from Julian and Unix-style dates automatically +compute the correct time zone and daylight savings adjustment to use, +provided they can figure out this information. This section describes +Calc's time zone adjustment algorithm in detail, in case you want to +do conversions in different time zones or in case Calc's algorithms +can't determine the right correction to use. + +Adjustments for time zones and daylight savings time are done by +@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other +commands. In particular, @samp{<may 1 1991> - <apr 1 1991>} evaluates +to exactly 30 days even though there is a daylight-savings +transition in between. This is also true for Julian pure dates: +@samp{julian(<may 1 1991>) - julian(<apr 1 1991>)}. But Julian +and Unix date/times will adjust for daylight savings time: +@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)} +evaluates to @samp{29.95834} (that's 29 days and 23 hours) +because one hour was lost when daylight savings commenced on +April 7, 1991. + +In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})} +computes the actual number of 24-hour periods between two dates, whereas +@samp{@var{date1} - @var{date2}} computes the number of calendar +days between two dates without taking daylight savings into account. + +@pindex calc-time-zone +@c @starindex +@tindex tzone +The @code{calc-time-zone} [@code{tzone}] command converts the time +zone specified by its numeric prefix argument into a number of +seconds difference from Greenwich mean time (GMT). If the argument +is a number, the result is simply that value multiplied by 3600. +Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If +Daylight Savings time is in effect, one hour should be subtracted from +the normal difference. + +If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other +date arithmetic commands that include a time zone argument) takes the +zone argument from the top of the stack. (In the case of @kbd{t J} +and @kbd{t U}, the normal argument is then taken from the second-to-top +stack position.) This allows you to give a non-integer time zone +adjustment. The time-zone argument can also be an HMS form, or +it can be a variable which is a time zone name in upper- or lower-case. +For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)} +(for Pacific standard and daylight savings times, respectively). + +North American and European time zone names are defined as follows; +note that for each time zone there is one name for standard time, +another for daylight savings time, and a third for ``generalized'' time +in which the daylight savings adjustment is computed from context. + +@group +@smallexample +YST PST MST CST EST AST NST GMT WET MET MEZ + 9 8 7 6 5 4 3.5 0 -1 -2 -2 + +YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ + 8 7 6 5 4 3 2.5 -1 -2 -3 -3 + +YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ +9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3 +@end smallexample +@end group + +@vindex math-tzone-names +To define time zone names that do not appear in the above table, +you must modify the Lisp variable @code{math-tzone-names}. This +is a list of lists describing the different time zone names; its +structure is best explained by an example. The three entries for +Pacific Time look like this: + +@group +@smallexample +( ( "PST" 8 0 ) ; Name as an upper-case string, then standard + ( "PDT" 8 -1 ) ; adjustment, then daylight savings adjustment. + ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. +@end smallexample +@end group + +@cindex @code{TimeZone} variable +@vindex TimeZone +With no arguments, @code{calc-time-zone} or @samp{tzone()} obtains an +argument from the Calc variable @code{TimeZone} if a value has been +stored for that variable. If not, Calc runs the Unix @samp{date} +command and looks for one of the above time zone names in the output; +if this does not succeed, @samp{tzone()} leaves itself unevaluated. +The time zone name in the @samp{date} output may be followed by a signed +adjustment, e.g., @samp{GMT+5} or @samp{GMT+0500} which specifies a +number of hours and minutes to be added to the base time zone. +Calc stores the time zone it finds into @code{TimeZone} to speed +later calls to @samp{tzone()}. + +The special time zone name @code{local} is equivalent to no argument, +i.e., it uses the local time zone as obtained from the @code{date} +command. + +If the time zone name found is one of the standard or daylight +savings zone names from the above table, and Calc's internal +daylight savings algorithm says that time and zone are consistent +(e.g., @code{PDT} accompanies a date that Calc's algorithm would also +consider to be daylight savings, or @code{PST} accompanies a date +that Calc would consider to be standard time), then Calc substitutes +the corresponding generalized time zone (like @code{PGT}). + +If your system does not have a suitable @samp{date} command, you +may wish to put a @samp{(setq var-TimeZone ...)} in your Emacs +initialization file to set the time zone. The easiest way to do +this is to edit the @code{TimeZone} variable using Calc's @kbd{s T} +command, then use the @kbd{s p} (@code{calc-permanent-variable}) +command to save the value of @code{TimeZone} permanently. + +The @kbd{t J} and @code{t U} commands with no numeric prefix +arguments do the same thing as @samp{tzone()}. If the current +time zone is a generalized time zone, e.g., @code{EGT}, Calc +examines the date being converted to tell whether to use standard +or daylight savings time. But if the current time zone is explicit, +e.g., @code{EST} or @code{EDT}, then that adjustment is used exactly +and Calc's daylight savings algorithm is not consulted. + +Some places don't follow the usual rules for daylight savings time. +The state of Arizona, for example, does not observe daylight savings +time. If you run Calc during the winter season in Arizona, the +Unix @code{date} command will report @code{MST} time zone, which +Calc will change to @code{MGT}. If you then convert a time that +lies in the summer months, Calc will apply an incorrect daylight +savings time adjustment. To avoid this, set your @code{TimeZone} +variable explicitly to @code{MST} to force the use of standard, +non-daylight-savings time. + +@vindex math-daylight-savings-hook +@findex math-std-daylight-savings +By default Calc always considers daylight savings time to begin at +2 a.m.@: on the first Sunday of April, and to end at 2 a.m.@: on the +last Sunday of October. This is the rule that has been in effect +in North America since 1987. If you are in a country that uses +different rules for computing daylight savings time, you have two +choices: Write your own daylight savings hook, or control time +zones explicitly by setting the @code{TimeZone} variable and/or +always giving a time-zone argument for the conversion functions. + +The Lisp variable @code{math-daylight-savings-hook} holds the +name of a function that is used to compute the daylight savings +adjustment for a given date. The default is +@code{math-std-daylight-savings}, which computes an adjustment +(either 0 or @i{-1}) using the North American rules given above. + +The daylight savings hook function is called with four arguments: +The date, as a floating-point number in standard Calc format; +a six-element list of the date decomposed into year, month, day, +hour, minute, and second, respectively; a string which contains +the generalized time zone name in upper-case, e.g., @code{"WEGT"}; +and a special adjustment to be applied to the hour value when +converting into a generalized time zone (see below). + +@findex math-prev-weekday-in-month +The Lisp function @code{math-prev-weekday-in-month} is useful for +daylight savings computations. This is an internal version of +the user-level @code{pwday} function described in the previous +section. It takes four arguments: The floating-point date value, +the corresponding six-element date list, the day-of-month number, +and the weekday number (0-6). + +The default daylight savings hook ignores the time zone name, but a +more sophisticated hook could use different algorithms for different +time zones. It would also be possible to use different algorithms +depending on the year number, but the default hook always uses the +algorithm for 1987 and later. Here is a listing of the default +daylight savings hook: + +@smallexample +(defun math-std-daylight-savings (date dt zone bump) + (cond ((< (nth 1 dt) 4) 0) + ((= (nth 1 dt) 4) + (let ((sunday (math-prev-weekday-in-month date dt 7 0))) + (cond ((< (nth 2 dt) sunday) 0) + ((= (nth 2 dt) sunday) + (if (>= (nth 3 dt) (+ 3 bump)) -1 0)) + (t -1)))) + ((< (nth 1 dt) 10) -1) + ((= (nth 1 dt) 10) + (let ((sunday (math-prev-weekday-in-month date dt 31 0))) + (cond ((< (nth 2 dt) sunday) -1) + ((= (nth 2 dt) sunday) + (if (>= (nth 3 dt) (+ 2 bump)) 0 -1)) + (t 0)))) + (t 0)) +) +@end smallexample + +@noindent +The @code{bump} parameter is equal to zero when Calc is converting +from a date form in a generalized time zone into a GMT date value. +It is @i{-1} when Calc is converting in the other direction. The +adjustments shown above ensure that the conversion behaves correctly +and reasonably around the 2 a.m.@: transition in each direction. + +There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the +beginning of daylight savings time; converting a date/time form that +falls in this hour results in a time value for the following hour, +from 3 a.m.@: to 4 a.m. At the end of daylight savings time, the +hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time +form that falls in in this hour results in a time value for the first +manifestion of that time (@emph{not} the one that occurs one hour later). + +If @code{math-daylight-savings-hook} is @code{nil}, then the +daylight savings adjustment is always taken to be zero. + +In algebraic formulas, @samp{tzone(@var{zone}, @var{date})} +computes the time zone adjustment for a given zone name at a +given date. The @var{date} is ignored unless @var{zone} is a +generalized time zone. If @var{date} is a date form, the +daylight savings computation is applied to it as it appears. +If @var{date} is a numeric date value, it is adjusted for the +daylight-savings version of @var{zone} before being given to +the daylight savings hook. This odd-sounding rule ensures +that the daylight-savings computation is always done in +local time, not in the GMT time that a numeric @var{date} +is typically represented in. + +@c @starindex +@tindex dsadj +The @samp{dsadj(@var{date}, @var{zone})} function computes the +daylight savings adjustment that is appropriate for @var{date} in +time zone @var{zone}. If @var{zone} is explicitly in or not in +daylight savings time (e.g., @code{PDT} or @code{PST}) the +@var{date} is ignored. If @var{zone} is a generalized time zone, +the algorithms described above are used. If @var{zone} is omitted, +the computation is done for the current time zone. + +@xref{Reporting Bugs}, for the address of Calc's author, if you +should wish to contribute your improved versions of +@code{math-tzone-names} and @code{math-daylight-savings-hook} +to the Calc distribution. + +@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic +@section Financial Functions + +@noindent +Calc's financial or business functions use the @kbd{b} prefix +key followed by a shifted letter. (The @kbd{b} prefix followed by +a lower-case letter is used for operations on binary numbers.) + +Note that the rate and the number of intervals given to these +functions must be on the same time scale, e.g., both months or +both years. Mixing an annual interest rate with a time expressed +in months will give you very wrong answers! + +It is wise to compute these functions to a higher precision than +you really need, just to make sure your answer is correct to the +last penny; also, you may wish to check the definitions at the end +of this section to make sure the functions have the meaning you expect. + +@menu +* Percentages:: +* Future Value:: +* Present Value:: +* Related Financial Functions:: +* Depreciation Functions:: +* Definitions of Financial Functions:: +@end menu + +@node Percentages, Future Value, Financial Functions, Financial Functions +@subsection Percentages + +@kindex M-% +@pindex calc-percent +@tindex % +@tindex percent +The @kbd{M-%} (@code{calc-percent}) command takes a percentage value, +say 5.4, and converts it to an equivalent actual number. For example, +@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or +@key{ESC} key combined with @kbd{%}.) + +Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}. +You can enter @samp{5.4%} yourself during algebraic entry. The +@samp{%} operator simply means, ``the preceding value divided by +100.'' The @samp{%} operator has very high precedence, so that +@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}. +(The @samp{%} operator is just a postfix notation for the +@code{percent} function, just like @samp{20!} is the notation for +@samp{fact(20)}, or twenty-factorial.) + +The formula @samp{5.4%} would normally evaluate immediately to +0.054, but the @kbd{M-%} command suppresses evaluation as it puts +the formula onto the stack. However, the next Calc command that +uses the formula @samp{5.4%} will evaluate it as its first step. +The net effect is that you get to look at @samp{5.4%} on the stack, +but Calc commands see it as @samp{0.054}, which is what they expect. + +In particular, @samp{5.4%} and @samp{0.054} are suitable values +for the @var{rate} arguments of the various financial functions, +but the number @samp{5.4} is probably @emph{not} suitable---it +represents a rate of 540 percent! + +The key sequence @kbd{M-% *} effectively means ``percent-of.'' +For example, @kbd{68 RET 25 M-% *} computes 17, which is 25% of +68 (and also 68% of 25, which comes out to the same thing). + +@kindex c % +@pindex calc-convert-percent +The @kbd{c %} (@code{calc-convert-percent}) command converts the +value on the top of the stack from numeric to percentage form. +For example, if 0.08 is on the stack, @kbd{c %} converts it to +@samp{8%}. The quantity is the same, it's just represented +differently. (Contrast this with @kbd{M-%}, which would convert +this number to @samp{0.08%}.) The @kbd{=} key is a convenient way +to convert a formula like @samp{8%} back to numeric form, 0.08. + +To compute what percentage one quantity is of another quantity, +use @kbd{/ c %}. For example, @w{@kbd{17 RET 68 / c %}} displays +@samp{25%}. + +@kindex b % +@pindex calc-percent-change +@tindex relch +The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command +calculates the percentage change from one number to another. +For example, @kbd{40 RET 50 b %} produces the answer @samp{25%}, +since 50 is 25% larger than 40. A negative result represents a +decrease: @kbd{50 RET 40 b %} produces @samp{-20%}, since 40 is +20% smaller than 50. (The answers are different in magnitude +because, in the first case, we're increasing by 25% of 40, but +in the second case, we're decreasing by 20% of 50.) The effect +of @kbd{40 RET 50 b %} is to compute @cite{(50-40)/40}, converting +the answer to percentage form as if by @kbd{c %}. + +@node Future Value, Present Value, Percentages, Financial Functions +@subsection Future Value + +@noindent +@kindex b F +@pindex calc-fin-fv +@tindex fv +The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes +the future value of an investment. It takes three arguments +from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}. +If you give payments of @var{payment} every year for @var{n} +years, and the money you have paid earns interest at @var{rate} per +year, then this function tells you what your investment would be +worth at the end of the period. (The actual interval doesn't +have to be years, as long as @var{n} and @var{rate} are expressed +in terms of the same intervals.) This function assumes payments +occur at the @emph{end} of each interval. + +@kindex I b F +@tindex fvb +The @kbd{I b F} [@code{fvb}] command does the same computation, +but assuming your payments are at the beginning of each interval. +Suppose you plan to deposit $1000 per year in a savings account +earning 5.4% interest, starting right now. How much will be +in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}. +Thus you will have earned $870 worth of interest over the years. +Using the stack, this calculation would have been +@kbd{5.4 M-% 5 RET 1000 I b F}. Note that the rate is expressed +as a number between 0 and 1, @emph{not} as a percentage. + +@kindex H b F +@tindex fvl +The @kbd{H b F} [@code{fvl}] command computes the future value +of an initial lump sum investment. Suppose you could deposit +those five thousand dollars in the bank right now; how much would +they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}. + +The algebraic functions @code{fv} and @code{fvb} accept an optional +fourth argument, which is used as an initial lump sum in the sense +of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n}, +@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment}) ++ fvl(@var{rate}, @var{n}, @var{initial})}.@refill + +To illustrate the relationships between these functions, we could +do the @code{fvb} calculation ``by hand'' using @code{fvl}. The +final balance will be the sum of the contributions of our five +deposits at various times. The first deposit earns interest for +five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second +deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) = +1234.13}. And so on down to the last deposit, which earns one +year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of +these five values is, sure enough, $5870.73, just as was computed +by @code{fvb} directly. + +What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments +are now at the ends of the periods. The end of one year is the same +as the beginning of the next, so what this really means is that we've +lost the payment at year zero (which contributed $1300.78), but we're +now counting the payment at year five (which, since it didn't have +a chance to earn interest, counts as $1000). Indeed, @cite{5569.96 = +5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error). + +@node Present Value, Related Financial Functions, Future Value, Financial Functions +@subsection Present Value + +@noindent +@kindex b P +@pindex calc-fin-pv +@tindex pv +The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes +the present value of an investment. Like @code{fv}, it takes +three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}. +It computes the present value of a series of regular payments. +Suppose you have the chance to make an investment that will +pay $2000 per year over the next four years; as you receive +these payments you can put them in the bank at 9% interest. +You want to know whether it is better to make the investment, or +to keep the money in the bank where it earns 9% interest right +from the start. The calculation @code{pv(9%, 4, 2000)} gives the +result 6479.44. If your initial investment must be less than this, +say, $6000, then the investment is worthwhile. But if you had to +put up $7000, then it would be better just to leave it in the bank. + +Here is the interpretation of the result of @code{pv}: You are +trying to compare the return from the investment you are +considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with +the return from leaving the money in the bank, which is +@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money +you would have to put up in advance. The @code{pv} function +finds the break-even point, @cite{x = 6479.44}, at which +@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is +the largest amount you should be willing to invest. + +@kindex I b P +@tindex pvb +The @kbd{I b P} [@code{pvb}] command solves the same problem, +but with payments occurring at the beginning of each interval. +It has the same relationship to @code{fvb} as @code{pv} has +to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59}, +a larger number than @code{pv} produced because we get to start +earning interest on the return from our investment sooner. + +@kindex H b P +@tindex pvl +The @kbd{H b P} [@code{pvl}] command computes the present value of +an investment that will pay off in one lump sum at the end of the +period. For example, if we get our $8000 all at the end of the +four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much +less than @code{pv} reported, because we don't earn any interest +on the return from this investment. Note that @code{pvl} and +@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}. + +You can give an optional fourth lump-sum argument to @code{pv} +and @code{pvb}; this is handled in exactly the same way as the +fourth argument for @code{fv} and @code{fvb}. + +@kindex b N +@pindex calc-fin-npv +@tindex npv +The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes +the net present value of a series of irregular investments. +The first argument is the interest rate. The second argument is +a vector which represents the expected return from the investment +at the end of each interval. For example, if the rate represents +a yearly interest rate, then the vector elements are the return +from the first year, second year, and so on. + +Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}. +Obviously this function is more interesting when the payments are +not all the same! + +The @code{npv} function can actually have two or more arguments. +Multiple arguments are interpreted in the same way as for the +vector statistical functions like @code{vsum}. +@xref{Single-Variable Statistics}. Basically, if there are several +payment arguments, each either a vector or a plain number, all these +values are collected left-to-right into the complete list of payments. +A numeric prefix argument on the @kbd{b N} command says how many +payment values or vectors to take from the stack.@refill + +@kindex I b N +@tindex npvb +The @kbd{I b N} [@code{npvb}] command computes the net present +value where payments occur at the beginning of each interval +rather than at the end. + +@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions +@subsection Related Financial Functions + +@noindent +The functions in this section are basically inverses of the +present value functions with respect to the various arguments. + +@kindex b M +@pindex calc-fin-pmt +@tindex pmt +The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes +the amount of periodic payment necessary to amortize a loan. +Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the +value of @var{payment} such that @code{pv(@var{rate}, @var{n}, +@var{payment}) = @var{amount}}.@refill + +@kindex I b M +@tindex pmtb +The @kbd{I b M} [@code{pmtb}] command does the same computation +but using @code{pvb} instead of @code{pv}. Like @code{pv} and +@code{pvb}, these functions can also take a fourth argument which +represents an initial lump-sum investment. + +@kindex H b M +The @kbd{H b M} key just invokes the @code{fvl} function, which is +the inverse of @code{pvl}. There is no explicit @code{pmtl} function. + +@kindex b # +@pindex calc-fin-nper +@tindex nper +The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes +the number of regular payments necessary to amortize a loan. +Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals +the value of @var{n} such that @code{pv(@var{rate}, @var{n}, +@var{payment}) = @var{amount}}. If @var{payment} is too small +ever to amortize a loan for @var{amount} at interest rate @var{rate}, +the @code{nper} function is left in symbolic form.@refill + +@kindex I b # +@tindex nperb +The @kbd{I b #} [@code{nperb}] command does the same computation +but using @code{pvb} instead of @code{pv}. You can give a fourth +lump-sum argument to these functions, but the computation will be +rather slow in the four-argument case.@refill + +@kindex H b # +@tindex nperl +The @kbd{H b #} [@code{nperl}] command does the same computation +using @code{pvl}. By exchanging @var{payment} and @var{amount} you +can also get the solution for @code{fvl}. For example, +@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a +bank account earning 8%, it will take nine years to grow to $2000.@refill + +@kindex b T +@pindex calc-fin-rate +@tindex rate +The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes +the rate of return on an investment. This is also an inverse of @code{pv}: +@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of +@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) = +@var{amount}}. The result is expressed as a formula like @samp{6.3%}.@refill + +@kindex I b T +@kindex H b T +@tindex rateb +@tindex ratel +The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}] +commands solve the analogous equations with @code{pvb} or @code{pvl} +in place of @code{pv}. Also, @code{rate} and @code{rateb} can +accept an optional fourth argument just like @code{pv} and @code{pvb}. +To redo the above example from a different perspective, +@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an +interest rate of 8% in order to double your account in nine years.@refill + +@kindex b I +@pindex calc-fin-irr +@tindex irr +The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the +analogous function to @code{rate} but for net present value. +Its argument is a vector of payments. Thus @code{irr(@var{payments})} +computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0}; +this rate is known as the @dfn{internal rate of return}. + +@kindex I b I +@tindex irrb +The @kbd{I b I} [@code{irrb}] command computes the internal rate of +return assuming payments occur at the beginning of each period. + +@node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions +@subsection Depreciation Functions + +@noindent +The functions in this section calculate @dfn{depreciation}, which is +the amount of value that a possession loses over time. These functions +are characterized by three parameters: @var{cost}, the original cost +of the asset; @var{salvage}, the value the asset will have at the end +of its expected ``useful life''; and @var{life}, the number of years +(or other periods) of the expected useful life. + +There are several methods for calculating depreciation that differ in +the way they spread the depreciation over the lifetime of the asset. + +@kindex b S +@pindex calc-fin-sln +@tindex sln +The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the +``straight-line'' depreciation. In this method, the asset depreciates +by the same amount every year (or period). For example, +@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000 +initially and will be worth $2000 after five years; it loses $2000 +per year. + +@kindex b Y +@pindex calc-fin-syd +@tindex syd +The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the +accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation +is higher during the early years of the asset's life. Since the +depreciation is different each year, @kbd{b Y} takes a fourth @var{period} +parameter which specifies which year is requested, from 1 to @var{life}. +If @var{period} is outside this range, the @code{syd} function will +return zero. + +@kindex b D +@pindex calc-fin-ddb +@tindex ddb +The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an +accelerated depreciation using the double-declining balance method. +It also takes a fourth @var{period} parameter. + +For symmetry, the @code{sln} function will accept a @var{period} +parameter as well, although it will ignore its value except that the +return value will as usual be zero if @var{period} is out of range. + +For example, pushing the vector @cite{[1,2,3,4,5]} (perhaps with @kbd{v x 5}) +and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$), +ddb(12000,2000,5,$)] RET} produces a matrix that allows us to compare +the three depreciation methods: + +@group +@example +[ [ 2000, 3333, 4800 ] + [ 2000, 2667, 2880 ] + [ 2000, 2000, 1728 ] + [ 2000, 1333, 592 ] + [ 2000, 667, 0 ] ] +@end example +@end group + +@noindent +(Values have been rounded to nearest integers in this figure.) +We see that @code{sln} depreciates by the same amount each year, +@kbd{syd} depreciates more at the beginning and less at the end, +and @kbd{ddb} weights the depreciation even more toward the beginning. + +Summing columns with @kbd{V R : +} yields @cite{[10000, 10000, 10000]}; +the total depreciation in any method is (by definition) the +difference between the cost and the salvage value. + +@node Definitions of Financial Functions, , Depreciation Functions, Financial Functions +@subsection Definitions + +@noindent +For your reference, here are the actual formulas used to compute +Calc's financial functions. + +Calc will not evaluate a financial function unless the @var{rate} or +@var{n} argument is known. However, @var{payment} or @var{amount} can +be a variable. Calc expands these functions according to the +formulas below for symbolic arguments only when you use the @kbd{a "} +(@code{calc-expand-formula}) command, or when taking derivatives or +integrals or solving equations involving the functions. + +@ifinfo +These formulas are shown using the conventions of ``Big'' display +mode (@kbd{d B}); for example, the formula for @code{fv} written +linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}. + +@example + n + (1 + rate) - 1 +fv(rate, n, pmt) = pmt * --------------- + rate + + n + ((1 + rate) - 1) (1 + rate) +fvb(rate, n, pmt) = pmt * ---------------------------- + rate + + n +fvl(rate, n, pmt) = pmt * (1 + rate) + + -n + 1 - (1 + rate) +pv(rate, n, pmt) = pmt * ---------------- + rate + + -n + (1 - (1 + rate) ) (1 + rate) +pvb(rate, n, pmt) = pmt * ----------------------------- + rate + + -n +pvl(rate, n, pmt) = pmt * (1 + rate) + + -1 -2 -3 +npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate) + + -1 -2 +npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate) + + -n + (amt - x * (1 + rate) ) * rate +pmt(rate, n, amt, x) = ------------------------------- + -n + 1 - (1 + rate) + + -n + (amt - x * (1 + rate) ) * rate +pmtb(rate, n, amt, x) = ------------------------------- + -n + (1 - (1 + rate) ) (1 + rate) + + amt * rate +nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate) + pmt + + amt * rate +nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate) + pmt * (1 + rate) + + amt +nperl(rate, pmt, amt) = - log(---, 1 + rate) + pmt + + 1/n + pmt +ratel(n, pmt, amt) = ------ - 1 + 1/n + amt + + cost - salv +sln(cost, salv, life) = ----------- + life + + (cost - salv) * (life - per + 1) +syd(cost, salv, life, per) = -------------------------------- + life * (life + 1) / 2 + + book * 2 +ddb(cost, salv, life, per) = --------, book = cost - depreciation so far + life +@end example +@end ifinfo +@tex +\turnoffactive +$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$ +$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$ +$$ \code{fvl}(r, n, p) = p (1 + r)^n $$ +$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$ +$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$ +$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$ +$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$ +$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$ +$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$ +$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over + (1 - (1 + r)^{-n}) (1 + r) } $$ +$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$ +$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$ +$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$ +$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$ +$$ \code{sln}(c, s, l) = { c - s \over l } $$ +$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$ +$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$ +@end tex + +@noindent +In @code{pmt} and @code{pmtb}, @cite{x=0} if omitted. + +These functions accept any numeric objects, including error forms, +intervals, and even (though not very usefully) complex numbers. The +above formulas specify exactly the behavior of these functions with +all sorts of inputs. + +Note that if the first argument to the @code{log} in @code{nper} is +negative, @code{nper} leaves itself in symbolic form rather than +returning a (financially meaningless) complex number. + +@samp{rate(num, pmt, amt)} solves the equation +@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R} +(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]} +for an initial guess. The @code{rateb} function is the same except +that it uses @code{pvb}. Note that @code{ratel} can be solved +directly; its formula is shown in the above list. + +Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0} +for @samp{rate}. + +If you give a fourth argument to @code{nper} or @code{nperb}, Calc +will also use @kbd{H a R} to solve the equation using an initial +guess interval of @samp{[0 .. 100]}. + +A fourth argument to @code{fv} simply sums the two components +calculated from the above formulas for @code{fv} and @code{fvl}. +The same is true of @code{fvb}, @code{pv}, and @code{pvb}. + +The @kbd{ddb} function is computed iteratively; the ``book'' value +starts out equal to @var{cost}, and decreases according to the above +formula for the specified number of periods. If the book value +would decrease below @var{salvage}, it only decreases to @var{salvage} +and the depreciation is zero for all subsequent periods. The @code{ddb} +function returns the amount the book value decreased in the specified +period. + +The Calc financial function names were borrowed mostly from Microsoft +Excel and Borland's Quattro. The @code{ratel} function corresponds to +@samp{@@CGR} in Borland's Reflex. The @code{nper} and @code{nperl} +functions correspond to @samp{@@TERM} and @samp{@@CTERM} in Quattro, +respectively. Beware that the Calc functions may take their arguments +in a different order than the corresponding functions in your favorite +spreadsheet. + +@node Binary Functions, , Financial Functions, Arithmetic +@section Binary Number Functions + +@noindent +The commands in this chapter all use two-letter sequences beginning with +the @kbd{b} prefix. + +@cindex Binary numbers +The ``binary'' operations actually work regardless of the currently +displayed radix, although their results make the most sense in a radix +like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}} +commands, respectively). You may also wish to enable display of leading +zeros with @kbd{d z}. @xref{Radix Modes}. + +@cindex Word size for binary operations +The Calculator maintains a current @dfn{word size} @cite{w}, an +arbitrary positive or negative integer. For a positive word size, all +of the binary operations described here operate modulo @cite{2^w}. In +particular, negative arguments are converted to positive integers modulo +@cite{2^w} by all binary functions.@refill + +If the word size is negative, binary operations produce 2's complement +integers from @c{$-2^{-w-1}$} +@cite{-(2^(-w-1))} to @c{$2^{-w-1}-1$} +@cite{2^(-w-1)-1} inclusive. Either +mode accepts inputs in any range; the sign of @cite{w} affects only +the results produced. + +@kindex b c +@pindex calc-clip +@tindex clip +The @kbd{b c} (@code{calc-clip}) +[@code{clip}] command can be used to clip a number by reducing it modulo +@cite{2^w}. The commands described in this chapter automatically clip +their results to the current word size. Note that other operations like +addition do not use the current word size, since integer addition +generally is not ``binary.'' (However, @pxref{Simplification Modes}, +@code{calc-bin-simplify-mode}.) For example, with a word size of 8 +bits @kbd{b c} converts a number to the range 0 to 255; with a word +size of @i{-8} @kbd{b c} converts to the range @i{-128} to 127.@refill + +@kindex b w +@pindex calc-word-size +The default word size is 32 bits. All operations except the shifts and +rotates allow you to specify a different word size for that one +operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the +top of stack to the range 0 to 255 regardless of the current word size. +To set the word size permanently, use @kbd{b w} (@code{calc-word-size}). +This command displays a prompt with the current word size; press @key{RET} +immediately to keep this word size, or type a new word size at the prompt. + +When the binary operations are written in symbolic form, they take an +optional second (or third) word-size parameter. When a formula like +@samp{and(a,b)} is finally evaluated, the word size current at that time +will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of +@i{-8} will always be used. A symbolic binary function will be left +in symbolic form unless the all of its argument(s) are integers or +integer-valued floats. + +If either or both arguments are modulo forms for which @cite{M} is a +power of two, that power of two is taken as the word size unless a +numeric prefix argument overrides it. The current word size is never +consulted when modulo-power-of-two forms are involved. + +@kindex b a +@pindex calc-and +@tindex and +The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise +AND of the two numbers on the top of the stack. In other words, for each +of the @cite{w} binary digits of the two numbers (pairwise), the corresponding +bit of the result is 1 if and only if both input bits are 1: +@samp{and(2#1100, 2#1010) = 2#1000}. + +@kindex b o +@pindex calc-or +@tindex or +The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise +inclusive OR of two numbers. A bit is 1 if either of the input bits, or +both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}. + +@kindex b x +@pindex calc-xor +@tindex xor +The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise +exclusive OR of two numbers. A bit is 1 if exactly one of the input bits +is 1: @samp{xor(2#1100, 2#1010) = 2#0110}. + +@kindex b d +@pindex calc-diff +@tindex diff +The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise +difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))}, +so that @samp{diff(2#1100, 2#1010) = 2#0100}. + +@kindex b n +@pindex calc-not +@tindex not +The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise +NOT of a number. A bit is 1 if the input bit is 0 and vice-versa. + +@kindex b l +@pindex calc-lshift-binary +@tindex lsh +The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a +number left by one bit, or by the number of bits specified in the numeric +prefix argument. A negative prefix argument performs a logical right shift, +in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)} +is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}. +Bits shifted ``off the end,'' according to the current word size, are lost. + +@kindex H b l +@kindex H b r +@c @mindex @idots +@kindex H b L +@c @mindex @null +@kindex H b R +@c @mindex @null +@kindex H b t +The @kbd{H b l} command also does a left shift, but it takes two arguments +from the stack (the value to shift, and, at top-of-stack, the number of +bits to shift). This version interprets the prefix argument just like +the regular binary operations, i.e., as a word size. The Hyperbolic flag +has a similar effect on the rest of the binary shift and rotate commands. + +@kindex b r +@pindex calc-rshift-binary +@tindex rsh +The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a +number right by one bit, or by the number of bits specified in the numeric +prefix argument: @samp{rsh(a,n) = lsh(a,-n)}. + +@kindex b L +@pindex calc-lshift-arith +@tindex ash +The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a +number left. It is analogous to @code{lsh}, except that if the shift +is rightward (the prefix argument is negative), an arithmetic shift +is performed as described below. + +@kindex b R +@pindex calc-rshift-arith +@tindex rash +The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs +an ``arithmetic'' shift to the right, in which the leftmost bit (according +to the current word size) is duplicated rather than shifting in zeros. +This corresponds to dividing by a power of two where the input is interpreted +as a signed, twos-complement number. (The distinction between the @samp{rsh} +and @samp{rash} operations is totally independent from whether the word +size is positive or negative.) With a negative prefix argument, this +performs a standard left shift. + +@kindex b t +@pindex calc-rotate-binary +@tindex rot +The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a +number one bit to the left. The leftmost bit (according to the current +word size) is dropped off the left and shifted in on the right. With a +numeric prefix argument, the number is rotated that many bits to the left +or right. + +@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that +pack and unpack binary integers into sets. (For example, @kbd{b u} +unpacks the number @samp{2#11001} to the set of bit-numbers +@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1'' +bits in a binary integer. + +Another interesting use of the set representation of binary integers +is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to +unpack; type @kbd{31 TAB -} to replace each bit-number in the set +with 31 minus that bit-number; type @kbd{b p} to pack the set back +into a binary integer. + +@node Scientific Functions, Matrix Functions, Arithmetic, Top +@chapter Scientific Functions + +@noindent +The functions described here perform trigonometric and other transcendental +calculations. They generally produce floating-point answers correct to the +full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse) +flag keys must be used to get some of these functions from the keyboard. + +@kindex P +@pindex calc-pi +@cindex @code{pi} variable +@vindex pi +@kindex H P +@cindex @code{e} variable +@vindex e +@kindex I P +@cindex @code{gamma} variable +@vindex gamma +@cindex Gamma constant, Euler's +@cindex Euler's gamma constant +@kindex H I P +@cindex @code{phi} variable +@cindex Phi, golden ratio +@cindex Golden ratio +One miscellanous command is shift-@kbd{P} (@code{calc-pi}), which pushes +the value of @c{$\pi$} +@cite{pi} (at the current precision) onto the stack. With the +Hyperbolic flag, it pushes the value @cite{e}, the base of natural logarithms. +With the Inverse flag, it pushes Euler's constant @c{$\gamma$} +@cite{gamma} (about 0.5772). With both Inverse and Hyperbolic, it +pushes the ``golden ratio'' @c{$\phi$} +@cite{phi} (about 1.618). (At present, Euler's constant is not available +to unlimited precision; Calc knows only the first 100 digits.) +In Symbolic mode, these commands push the +actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi}, +respectively, instead of their values; @pxref{Symbolic Mode}.@refill + +@c @mindex Q +@c @mindex I Q +@kindex I Q +@tindex sqr +The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere; +@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command +computes the square of the argument. + +@xref{Prefix Arguments}, for a discussion of the effect of numeric +prefix arguments on commands in this chapter which do not otherwise +interpret a prefix argument. + +@menu +* Logarithmic Functions:: +* Trigonometric and Hyperbolic Functions:: +* Advanced Math Functions:: +* Branch Cuts:: +* Random Numbers:: +* Combinatorial Functions:: +* Probability Distribution Functions:: +@end menu + +@node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions +@section Logarithmic Functions + +@noindent +@kindex L +@pindex calc-ln +@tindex ln +@c @mindex @null +@kindex I E +The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural +logarithm of the real or complex number on the top of the stack. With +the Inverse flag it computes the exponential function instead, although +this is redundant with the @kbd{E} command. + +@kindex E +@pindex calc-exp +@tindex exp +@c @mindex @null +@kindex I L +The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the +exponential, i.e., @cite{e} raised to the power of the number on the stack. +The meanings of the Inverse and Hyperbolic flags follow from those for +the @code{calc-ln} command. + +@kindex H L +@kindex H E +@pindex calc-log10 +@tindex log10 +@tindex exp10 +@c @mindex @null +@kindex H I L +@c @mindex @null +@kindex H I E +The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common +(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}], +it raises ten to a given power.) Note that the common logarithm of a +complex number is computed by taking the natural logarithm and dividing +by @c{$\ln10$} +@cite{ln(10)}. + +@kindex B +@kindex I B +@pindex calc-log +@tindex log +@tindex alog +The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm +to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since +@c{$2^{10} = 1024$} +@cite{2^10 = 1024}. In certain cases like @samp{log(3,9)}, the result +will be either @cite{1:2} or @cite{0.5} depending on the current Fraction +Mode setting. With the Inverse flag [@code{alog}], this command is +similar to @kbd{^} except that the order of the arguments is reversed. + +@kindex f I +@pindex calc-ilog +@tindex ilog +The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the +integer logarithm of a number to any base. The number and the base must +themselves be positive integers. This is the true logarithm, rounded +down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @cite{x} in the +range from 1000 to 9999. If both arguments are positive integers, exact +integer arithmetic is used; otherwise, this is equivalent to +@samp{floor(log(x,b))}. + +@kindex f E +@pindex calc-expm1 +@tindex expm1 +The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes +@c{$e^x - 1$} +@cite{exp(x)-1}, but using an algorithm that produces a more accurate +answer when the result is close to zero, i.e., when @c{$e^x$} +@cite{exp(x)} is close +to one. + +@kindex f L +@pindex calc-lnp1 +@tindex lnp1 +The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes +@c{$\ln(x+1)$} +@cite{ln(x+1)}, producing a more accurate answer when @cite{x} is close +to zero. + +@node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions +@section Trigonometric/Hyperbolic Functions + +@noindent +@kindex S +@pindex calc-sin +@tindex sin +The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine +of an angle or complex number. If the input is an HMS form, it is interpreted +as degrees-minutes-seconds; otherwise, the input is interpreted according +to the current angular mode. It is best to use Radians mode when operating +on complex numbers.@refill + +Calc's ``units'' mechanism includes angular units like @code{deg}, +@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated +all the time, the @kbd{u s} (@code{calc-simplify-units}) command will +simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless +of the current angular mode. @xref{Basic Operations on Units}. + +Also, the symbolic variable @code{pi} is not ordinarily recognized in +arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but +the @kbd{a s} (@code{calc-simplify}) command recognizes many such +formulas when the current angular mode is radians @emph{and} symbolic +mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}. +@xref{Symbolic Mode}. Beware, this simplification occurs even if you +have stored a different value in the variable @samp{pi}; this is one +reason why changing built-in variables is a bad idea. Arguments of +the form @cite{x} plus a multiple of @c{$\pi/2$} +@cite{pi/2} are also simplified. +Calc includes similar formulas for @code{cos} and @code{tan}.@refill + +The @kbd{a s} command knows all angles which are integer multiples of +@c{$\pi/12$} +@cite{pi/12}, @c{$\pi/10$} +@cite{pi/10}, or @c{$\pi/8$} +@cite{pi/8} radians. In degrees mode, +analogous simplifications occur for integer multiples of 15 or 18 +degrees, and for arguments plus multiples of 90 degrees. + +@kindex I S +@pindex calc-arcsin +@tindex arcsin +With the Inverse flag, @code{calc-sin} computes an arcsine. This is also +available as the @code{calc-arcsin} command or @code{arcsin} algebraic +function. The returned argument is converted to degrees, radians, or HMS +notation depending on the current angular mode. + +@kindex H S +@pindex calc-sinh +@tindex sinh +@kindex H I S +@pindex calc-arcsinh +@tindex arcsinh +With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic +sine, also available as @code{calc-sinh} [@code{sinh}]. With the +Hyperbolic and Inverse flags, it computes the hyperbolic arcsine +(@code{calc-arcsinh}) [@code{arcsinh}]. + +@kindex C +@pindex calc-cos +@tindex cos +@c @mindex @idots +@kindex I C +@pindex calc-arccos +@c @mindex @null +@tindex arccos +@c @mindex @null +@kindex H C +@pindex calc-cosh +@c @mindex @null +@tindex cosh +@c @mindex @null +@kindex H I C +@pindex calc-arccosh +@c @mindex @null +@tindex arccosh +@c @mindex @null +@kindex T +@pindex calc-tan +@c @mindex @null +@tindex tan +@c @mindex @null +@kindex I T +@pindex calc-arctan +@c @mindex @null +@tindex arctan +@c @mindex @null +@kindex H T +@pindex calc-tanh +@c @mindex @null +@tindex tanh +@c @mindex @null +@kindex H I T +@pindex calc-arctanh +@c @mindex @null +@tindex arctanh +The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine +of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}] +computes the tangent, along with all the various inverse and hyperbolic +variants of these functions. + +@kindex f T +@pindex calc-arctan2 +@tindex arctan2 +The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two +numbers from the stack and computes the arc tangent of their ratio. The +result is in the full range from @i{-180} (exclusive) to @i{+180} +(inclusive) degrees, or the analogous range in radians. A similar +result would be obtained with @kbd{/} followed by @kbd{I T}, but the +value would only be in the range from @i{-90} to @i{+90} degrees +since the division loses information about the signs of the two +components, and an error might result from an explicit division by zero +which @code{arctan2} would avoid. By (arbitrary) definition, +@samp{arctan2(0,0)=0}. + +@pindex calc-sincos +@c @starindex +@tindex sincos +@c @starindex +@c @mindex arc@idots +@tindex arcsincos +The @code{calc-sincos} [@code{sincos}] command computes the sine and +cosine of a number, returning them as a vector of the form +@samp{[@var{cos}, @var{sin}]}. +With the Inverse flag [@code{arcsincos}], this command takes a two-element +vector as an argument and computes @code{arctan2} of the elements. +(This command does not accept the Hyperbolic flag.)@refill + +@node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions +@section Advanced Mathematical Functions + +@noindent +Calc can compute a variety of less common functions that arise in +various branches of mathematics. All of the functions described in +this section allow arbitrary complex arguments and, except as noted, +will work to arbitrarily large precisions. They can not at present +handle error forms or intervals as arguments. + +NOTE: These functions are still experimental. In particular, their +accuracy is not guaranteed in all domains. It is advisable to set the +current precision comfortably higher than you actually need when +using these functions. Also, these functions may be impractically +slow for some values of the arguments. + +@kindex f g +@pindex calc-gamma +@tindex gamma +The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler +gamma function. For positive integer arguments, this is related to the +factorial function: @samp{gamma(n+1) = fact(n)}. For general complex +arguments the gamma function can be defined by the following definite +integral: @c{$\Gamma(a) = \int_0^\infty t^{a-1} e^t dt$} +@cite{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. +(The actual implementation uses far more efficient computational methods.) + +@kindex f G +@tindex gammaP +@c @mindex @idots +@kindex I f G +@c @mindex @null +@kindex H f G +@c @mindex @null +@kindex H I f G +@pindex calc-inc-gamma +@c @mindex @null +@tindex gammaQ +@c @mindex @null +@tindex gammag +@c @mindex @null +@tindex gammaG +The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes +the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by +the integral, @c{$P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)$} +@cite{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}. +This implies that @samp{gammaP(a,inf) = 1} for any @cite{a} (see the +definition of the normal gamma function). + +Several other varieties of incomplete gamma function are defined. +The complement of @cite{P(a,x)}, called @cite{Q(a,x) = 1-P(a,x)} by +some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command. +You can think of this as taking the other half of the integral, from +@cite{x} to infinity. + +@ifinfo +The functions corresponding to the integrals that define @cite{P(a,x)} +and @cite{Q(a,x)} but without the normalizing @cite{1/gamma(a)} +factor are called @cite{g(a,x)} and @cite{G(a,x)}, respectively +(where @cite{g} and @cite{G} represent the lower- and upper-case Greek +letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}] +and @kbd{H I f G} [@code{gammaG}] commands. +@end ifinfo +@tex +\turnoffactive +The functions corresponding to the integrals that define $P(a,x)$ +and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$ +factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively. +You can obtain these using the \kbd{H f G} [\code{gammag}] and +\kbd{I H f G} [\code{gammaG}] commands. +@end tex + +@kindex f b +@pindex calc-beta +@tindex beta +The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the +Euler beta function, which is defined in terms of the gamma function as +@c{$B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)$} +@cite{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, or by +@c{$B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt$} +@cite{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}. + +@kindex f B +@kindex H f B +@pindex calc-inc-beta +@tindex betaI +@tindex betaB +The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes +the incomplete beta function @cite{I(x,a,b)}. It is defined by +@c{$I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)$} +@cite{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}. +Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding +un-normalized version [@code{betaB}]. + +@kindex f e +@kindex I f e +@pindex calc-erf +@tindex erf +@tindex erfc +The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the +error function @c{$\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt$} +@cite{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}. +The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}] +is the corresponding integral from @samp{x} to infinity; the sum +@c{$\hbox{erf}(x) + \hbox{erfc}(x) = 1$} +@cite{erf(x) + erfc(x) = 1}. + +@kindex f j +@kindex f y +@pindex calc-bessel-J +@pindex calc-bessel-Y +@tindex besJ +@tindex besY +The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y} +(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel +functions of the first and second kinds, respectively. +In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter +@cite{n} is often an integer, but is not required to be one. +Calc's implementation of the Bessel functions currently limits the +precision to 8 digits, and may not be exact even to that precision. +Use with care!@refill + +@node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions +@section Branch Cuts and Principal Values + +@noindent +@cindex Branch cuts +@cindex Principal values +All of the logarithmic, trigonometric, and other scientific functions are +defined for complex numbers as well as for reals. +This section describes the values +returned in cases where the general result is a family of possible values. +Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language}, +second edition, in these matters. This section will describe each +function briefly; for a more detailed discussion (including some nifty +diagrams), consult Steele's book. + +Note that the branch cuts for @code{arctan} and @code{arctanh} were +changed between the first and second editions of Steele. Versions of +Calc starting with 2.00 follow the second edition. + +The new branch cuts exactly match those of the HP-28/48 calculators. +They also match those of Mathematica 1.2, except that Mathematica's +@code{arctan} cut is always in the right half of the complex plane, +and its @code{arctanh} cut is always in the top half of the plane. +Calc's cuts are continuous with quadrants I and III for @code{arctan}, +or II and IV for @code{arctanh}. + +Note: The current implementations of these functions with complex arguments +are designed with proper behavior around the branch cuts in mind, @emph{not} +efficiency or accuracy. You may need to increase the floating precision +and wait a while to get suitable answers from them. + +For @samp{sqrt(a+bi)}: When @cite{a<0} and @cite{b} is small but positive +or zero, the result is close to the @cite{+i} axis. For @cite{b} small and +negative, the result is close to the @cite{-i} axis. The result always lies +in the right half of the complex plane. + +For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}. +The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}. +Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the +negative real axis. + +The following table describes these branch cuts in another way. +If the real and imaginary parts of @cite{z} are as shown, then +the real and imaginary parts of @cite{f(z)} will be as shown. +Here @code{eps} stands for a small positive value; each +occurrence of @code{eps} may stand for a different small value. + +@smallexample + z sqrt(z) ln(z) +---------------------------------------- + +, 0 +, 0 any, 0 + -, 0 0, + any, pi + -, +eps +eps, + +eps, + + -, -eps +eps, - +eps, - +@end smallexample + +For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}. +One interesting consequence of this is that @samp{(-8)^1:3} does +not evaluate to @i{-2} as you might expect, but to the complex +number @cite{(1., 1.732)}. Both of these are valid cube roots +of @i{-8} (as is @cite{(1., -1.732)}); Calc chooses a perhaps +less-obvious root for the sake of mathematical consistency. + +For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}. +The branch cuts are on the real axis, less than @i{-1} and greater than 1. + +For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))}, +or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on +the real axis, less than @i{-1} and greater than 1. + +For @samp{arctan(z)}: This is defined by +@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the +imaginary axis, below @cite{-i} and above @cite{i}. + +For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}. +The branch cuts are on the imaginary axis, below @cite{-i} and +above @cite{i}. + +For @samp{arccosh(z)}: This is defined by +@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the +real axis less than 1. + +For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}. +The branch cuts are on the real axis, less than @i{-1} and greater than 1. + +The following tables for @code{arcsin}, @code{arccos}, and +@code{arctan} assume the current angular mode is radians. The +hyperbolic functions operate independently of the angular mode. + +@smallexample + z arcsin(z) arccos(z) +------------------------------------------------------- + (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0 + (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps + (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps + <-1, 0 -pi/2, + pi, - + <-1, +eps -pi/2 + eps, + pi - eps, - + <-1, -eps -pi/2 + eps, - pi - eps, + + >1, 0 pi/2, - 0, + + >1, +eps pi/2 - eps, + +eps, - + >1, -eps pi/2 - eps, - +eps, + +@end smallexample + +@smallexample + z arccosh(z) arctanh(z) +----------------------------------------------------- + (-1..1), 0 0, (0..pi) any, 0 + (-1..1), +eps +eps, (0..pi) any, +eps + (-1..1), -eps +eps, (-pi..0) any, -eps + <-1, 0 +, pi -, pi/2 + <-1, +eps +, pi - eps -, pi/2 - eps + <-1, -eps +, -pi + eps -, -pi/2 + eps + >1, 0 +, 0 +, -pi/2 + >1, +eps +, +eps +, pi/2 - eps + >1, -eps +, -eps +, -pi/2 + eps +@end smallexample + +@smallexample + z arcsinh(z) arctan(z) +----------------------------------------------------- + 0, (-1..1) 0, (-pi/2..pi/2) 0, any + 0, <-1 -, -pi/2 -pi/2, - + +eps, <-1 +, -pi/2 + eps pi/2 - eps, - + -eps, <-1 -, -pi/2 + eps -pi/2 + eps, - + 0, >1 +, pi/2 pi/2, + + +eps, >1 +, pi/2 - eps pi/2 - eps, + + -eps, >1 -, pi/2 - eps -pi/2 + eps, + +@end smallexample + +Finally, the following identities help to illustrate the relationship +between the complex trigonometric and hyperbolic functions. They +are valid everywhere, including on the branch cuts. + +@smallexample +sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z) +cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z) +tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z) +sinh(i*z) = i*sin(z) cosh(i*z) = cos(z) +@end smallexample + +The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined +for general complex arguments, but their branch cuts and principal values +are not rigorously specified at present. + +@node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions +@section Random Numbers + +@noindent +@kindex k r +@pindex calc-random +@tindex random +The @kbd{k r} (@code{calc-random}) [@code{random}] command produces +random numbers of various sorts. + +Given a positive numeric prefix argument @cite{M}, it produces a random +integer @cite{N} in the range @c{$0 \le N < M$} +@cite{0 <= N < M}. Each of the @cite{M} +values appears with equal probability.@refill + +With no numeric prefix argument, the @kbd{k r} command takes its argument +from the stack instead. Once again, if this is a positive integer @cite{M} +the result is a random integer less than @cite{M}. However, note that +while numeric prefix arguments are limited to six digits or so, an @cite{M} +taken from the stack can be arbitrarily large. If @cite{M} is negative, +the result is a random integer in the range @c{$M < N \le 0$} +@cite{M < N <= 0}. + +If the value on the stack is a floating-point number @cite{M}, the result +is a random floating-point number @cite{N} in the range @c{$0 \le N < M$} +@cite{0 <= N < M} +or @c{$M < N \le 0$} +@cite{M < N <= 0}, according to the sign of @cite{M}. + +If @cite{M} is zero, the result is a Gaussian-distributed random real +number; the distribution has a mean of zero and a standard deviation +of one. The algorithm used generates random numbers in pairs; thus, +every other call to this function will be especially fast. + +If @cite{M} is an error form @c{$m$ @code{+/-} $\sigma$} +@samp{m +/- s} where @i{m} +and @c{$\sigma$} +@i{s} are both real numbers, the result uses a Gaussian +distribution with mean @i{m} and standard deviation @c{$\sigma$} +@i{s}. + +If @cite{M} is an interval form, the lower and upper bounds specify the +acceptable limits of the random numbers. If both bounds are integers, +the result is a random integer in the specified range. If either bound +is floating-point, the result is a random real number in the specified +range. If the interval is open at either end, the result will be sure +not to equal that end value. (This makes a big difference for integer +intervals, but for floating-point intervals it's relatively minor: +with a precision of 6, @samp{random([1.0..2.0))} will return any of one +million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may +additionally return 2.00000, but the probability of this happening is +extremely small.) + +If @cite{M} is a vector, the result is one element taken at random from +the vector. All elements of the vector are given equal probabilities. + +@vindex RandSeed +The sequence of numbers produced by @kbd{k r} is completely random by +default, i.e., the sequence is seeded each time you start Calc using +the current time and other information. You can get a reproducible +sequence by storing a particular ``seed value'' in the Calc variable +@code{RandSeed}. Any integer will do for a seed; integers of from 1 +to 12 digits are good. If you later store a different integer into +@code{RandSeed}, Calc will switch to a different pseudo-random +sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself +from the current time. If you store the same integer that you used +before back into @code{RandSeed}, you will get the exact same sequence +of random numbers as before. + +@pindex calc-rrandom +The @code{calc-rrandom} command (not on any key) produces a random real +number between zero and one. It is equivalent to @samp{random(1.0)}. + +@kindex k a +@pindex calc-random-again +The @kbd{k a} (@code{calc-random-again}) command produces another random +number, re-using the most recent value of @cite{M}. With a numeric +prefix argument @var{n}, it produces @var{n} more random numbers using +that value of @cite{M}. + +@kindex k h +@pindex calc-shuffle +@tindex shuffle +The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several +random values with no duplicates. The value on the top of the stack +specifies the set from which the random values are drawn, and may be any +of the @cite{M} formats described above. The numeric prefix argument +gives the length of the desired list. (If you do not provide a numeric +prefix argument, the length of the list is taken from the top of the +stack, and @cite{M} from second-to-top.) + +If @cite{M} is a floating-point number, zero, or an error form (so +that the random values are being drawn from the set of real numbers) +there is little practical difference between using @kbd{k h} and using +@kbd{k r} several times. But if the set of possible values consists +of just a few integers, or the elements of a vector, then there is +a very real chance that multiple @kbd{k r}'s will produce the same +number more than once. The @kbd{k h} command produces a vector whose +elements are always distinct. (Actually, there is a slight exception: +If @cite{M} is a vector, no given vector element will be drawn more +than once, but if several elements of @cite{M} are equal, they may +each make it into the result vector.) + +One use of @kbd{k h} is to rearrange a list at random. This happens +if the prefix argument is equal to the number of values in the list: +@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list +@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument +@var{n} is negative it is replaced by the size of the set represented +by @cite{M}. Naturally, this is allowed only when @cite{M} specifies +a small discrete set of possibilities. + +To do the equivalent of @kbd{k h} but with duplications allowed, +given @cite{M} on the stack and with @var{n} just entered as a numeric +prefix, use @kbd{v b} to build a vector of copies of @cite{M}, then use +@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the +elements of this vector. @xref{Matrix Functions}. + +@menu +* Random Number Generator:: (Complete description of Calc's algorithm) +@end menu + +@node Random Number Generator, , Random Numbers, Random Numbers +@subsection Random Number Generator + +Calc's random number generator uses several methods to ensure that +the numbers it produces are highly random. Knuth's @emph{Art of +Computer Programming}, Volume II, contains a thorough description +of the theory of random number generators and their measurement and +characterization. + +If @code{RandSeed} has no stored value, Calc calls Emacs' built-in +@code{random} function to get a stream of random numbers, which it +then treats in various ways to avoid problems inherent in the simple +random number generators that many systems use to implement @code{random}. + +When Calc's random number generator is first invoked, it ``seeds'' +the low-level random sequence using the time of day, so that the +random number sequence will be different every time you use Calc. + +Since Emacs Lisp doesn't specify the range of values that will be +returned by its @code{random} function, Calc exercises the function +several times to estimate the range. When Calc subsequently uses +the @code{random} function, it takes only 10 bits of the result +near the most-significant end. (It avoids at least the bottom +four bits, preferably more, and also tries to avoid the top two +bits.) This strategy works well with the linear congruential +generators that are typically used to implement @code{random}. + +If @code{RandSeed} contains an integer, Calc uses this integer to +seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A, +computing @c{$X_{n-55} - X_{n-24}$} +@cite{X_n-55 - X_n-24}). This method expands the seed +value into a large table which is maintained internally; the variable +@code{RandSeed} is changed from, e.g., 42 to the vector @cite{[42]} +to indicate that the seed has been absorbed into this table. When +@code{RandSeed} contains a vector, @kbd{k r} and related commands +continue to use the same internal table as last time. There is no +way to extract the complete state of the random number generator +so that you can restart it from any point; you can only restart it +from the same initial seed value. A simple way to restart from the +same seed is to type @kbd{s r RandSeed} to get the seed vector, +@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed} +to reseed the generator with that number. + +Calc uses a ``shuffling'' method as described in algorithm 3.2.2B +of Knuth. It fills a table with 13 random 10-bit numbers. Then, +to generate a new random number, it uses the previous number to +index into the table, picks the value it finds there as the new +random number, then replaces that table entry with a new value +obtained from a call to the base random number generator (either +the additive congruential generator or the @code{random} function +supplied by the system). If there are any flaws in the base +generator, shuffling will tend to even them out. But if the system +provides an excellent @code{random} function, shuffling will not +damage its randomness. + +To create a random integer of a certain number of digits, Calc +builds the integer three decimal digits at a time. For each group +of three digits, Calc calls its 10-bit shuffling random number generator +(which returns a value from 0 to 1023); if the random value is 1000 +or more, Calc throws it out and tries again until it gets a suitable +value. + +To create a random floating-point number with precision @var{p}, Calc +simply creates a random @var{p}-digit integer and multiplies by +@c{$10^{-p}$} +@cite{10^-p}. The resulting random numbers should be very clean, but note +that relatively small numbers will have few significant random digits. +In other words, with a precision of 12, you will occasionally get +numbers on the order of @c{$10^{-9}$} +@cite{10^-9} or @c{$10^{-10}$} +@cite{10^-10}, but those numbers +will only have two or three random digits since they correspond to small +integers times @c{$10^{-12}$} +@cite{10^-12}. + +To create a random integer in the interval @samp{[0 .. @var{m})}, Calc +counts the digits in @var{m}, creates a random integer with three +additional digits, then reduces modulo @var{m}. Unless @var{m} is a +power of ten the resulting values will be very slightly biased toward +the lower numbers, but this bias will be less than 0.1%. (For example, +if @var{m} is 42, Calc will reduce a random integer less than 100000 +modulo 42 to get a result less than 42. It is easy to show that the +numbers 40 and 41 will be only 2380/2381 as likely to result from this +modulo operation as numbers 39 and below.) If @var{m} is a power of +ten, however, the numbers should be completely unbiased. + +The Gaussian random numbers generated by @samp{random(0.0)} use the +``polar'' method described in Knuth section 3.4.1C. This method +generates a pair of Gaussian random numbers at a time, so only every +other call to @samp{random(0.0)} will require significant calculations. + +@node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions +@section Combinatorial Functions + +@noindent +Commands relating to combinatorics and number theory begin with the +@kbd{k} key prefix. + +@kindex k g +@pindex calc-gcd +@tindex gcd +The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the +Greatest Common Divisor of two integers. It also accepts fractions; +the GCD of two fractions is defined by taking the GCD of the +numerators, and the LCM of the denominators. This definition is +consistent with the idea that @samp{a / gcd(a,x)} should yield an +integer for any @samp{a} and @samp{x}. For other types of arguments, +the operation is left in symbolic form.@refill + +@kindex k l +@pindex calc-lcm +@tindex lcm +The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the +Least Common Multiple of two integers or fractions. The product of +the LCM and GCD of two numbers is equal to the product of the +numbers.@refill + +@kindex k E +@pindex calc-extended-gcd +@tindex egcd +The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes +the GCD of two integers @cite{x} and @cite{y} and returns a vector +@cite{[g, a, b]} where @c{$g = \gcd(x,y) = a x + b y$} +@cite{g = gcd(x,y) = a x + b y}. + +@kindex ! +@pindex calc-factorial +@tindex fact +@c @mindex @null +@tindex ! +The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the +factorial of the number at the top of the stack. If the number is an +integer, the result is an exact integer. If the number is an +integer-valued float, the result is a floating-point approximation. If +the number is a non-integral real number, the generalized factorial is used, +as defined by the Euler Gamma function. Please note that computation of +large factorials can be slow; using floating-point format will help +since fewer digits must be maintained. The same is true of many of +the commands in this section.@refill + +@kindex k d +@pindex calc-double-factorial +@tindex dfact +@c @mindex @null +@tindex !! +The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command +computes the ``double factorial'' of an integer. For an even integer, +this is the product of even integers from 2 to @cite{N}. For an odd +integer, this is the product of odd integers from 3 to @cite{N}. If +the argument is an integer-valued float, the result is a floating-point +approximation. This function is undefined for negative even integers. +The notation @cite{N!!} is also recognized for double factorials.@refill + +@kindex k c +@pindex calc-choose +@tindex choose +The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the +binomial coefficient @cite{N}-choose-@cite{M}, where @cite{M} is the number +on the top of the stack and @cite{N} is second-to-top. If both arguments +are integers, the result is an exact integer. Otherwise, the result is a +floating-point approximation. The binomial coefficient is defined for all +real numbers by @c{$N! \over M! (N-M)!\,$} +@cite{N! / M! (N-M)!}. + +@kindex H k c +@pindex calc-perm +@tindex perm +@ifinfo +The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the +number-of-permutations function @cite{N! / (N-M)!}. +@end ifinfo +@tex +The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the +number-of-perm\-utations function $N! \over (N-M)!\,$. +@end tex + +@kindex k b +@kindex H k b +@pindex calc-bernoulli-number +@tindex bern +The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command +computes a given Bernoulli number. The value at the top of the stack +is a nonnegative integer @cite{n} that specifies which Bernoulli number +is desired. The @kbd{H k b} command computes a Bernoulli polynomial, +taking @cite{n} from the second-to-top position and @cite{x} from the +top of the stack. If @cite{x} is a variable or formula the result is +a polynomial in @cite{x}; if @cite{x} is a number the result is a number. + +@kindex k e +@kindex H k e +@pindex calc-euler-number +@tindex euler +The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly +computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial. +Bernoulli and Euler numbers occur in the Taylor expansions of several +functions. + +@kindex k s +@kindex H k s +@pindex calc-stirling-number +@tindex stir1 +@tindex stir2 +The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command +computes a Stirling number of the first kind@c{ $n \brack m$} +@asis{}, given two integers +@cite{n} and @cite{m} on the stack. The @kbd{H k s} [@code{stir2}] +command computes a Stirling number of the second kind@c{ $n \brace m$} +@asis{}. These are +the number of @cite{m}-cycle permutations of @cite{n} objects, and +the number of ways to partition @cite{n} objects into @cite{m} +non-empty sets, respectively. + +@kindex k p +@pindex calc-prime-test +@cindex Primes +The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on +the top of the stack is prime. For integers less than eight million, the +answer is always exact and reasonably fast. For larger integers, a +probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P). +The number is first checked against small prime factors (up to 13). Then, +any number of iterations of the algorithm are performed. Each step either +discovers that the number is non-prime, or substantially increases the +certainty that the number is prime. After a few steps, the chance that +a number was mistakenly described as prime will be less than one percent. +(Indeed, this is a worst-case estimate of the probability; in practice +even a single iteration is quite reliable.) After the @kbd{k p} command, +the number will be reported as definitely prime or non-prime if possible, +or otherwise ``probably'' prime with a certain probability of error. + +@c @starindex +@tindex prime +The normal @kbd{k p} command performs one iteration of the primality +test. Pressing @kbd{k p} repeatedly for the same integer will perform +additional iterations. Also, @kbd{k p} with a numeric prefix performs +the specified number of iterations. There is also an algebraic function +@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @cite{n} +is (probably) prime and 0 if not. + +@kindex k f +@pindex calc-prime-factors +@tindex prfac +The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command +attempts to decompose an integer into its prime factors. For numbers up +to 25 million, the answer is exact although it may take some time. The +result is a vector of the prime factors in increasing order. For larger +inputs, prime factors above 5000 may not be found, in which case the +last number in the vector will be an unfactored integer greater than 25 +million (with a warning message). For negative integers, the first +element of the list will be @i{-1}. For inputs @i{-1}, @i{0}, and +@i{1}, the result is a list of the same number. + +@kindex k n +@pindex calc-next-prime +@c @mindex nextpr@idots +@tindex nextprime +The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds +the next prime above a given number. Essentially, it searches by calling +@code{calc-prime-test} on successive integers until it finds one that +passes the test. This is quite fast for integers less than eight million, +but once the probabilistic test comes into play the search may be rather +slow. Ordinarily this command stops for any prime that passes one iteration +of the primality test. With a numeric prefix argument, a number must pass +the specified number of iterations before the search stops. (This only +matters when searching above eight million.) You can always use additional +@kbd{k p} commands to increase your certainty that the number is indeed +prime. + +@kindex I k n +@pindex calc-prev-prime +@c @mindex prevpr@idots +@tindex prevprime +The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command +analogously finds the next prime less than a given number. + +@kindex k t +@pindex calc-totient +@tindex totient +The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the +Euler ``totient'' function@c{ $\phi(n)$} +@asis{}, the number of integers less than @cite{n} which +are relatively prime to @cite{n}. + +@kindex k m +@pindex calc-moebius +@tindex moebius +The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the +@c{M\"obius $\mu$} +@asis{Moebius ``mu''} function. If the input number is a product of @cite{k} +distinct factors, this is @cite{(-1)^k}. If the input number has any +duplicate factors (i.e., can be divided by the same prime more than once), +the result is zero. + +@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions +@section Probability Distribution Functions + +@noindent +The functions in this section compute various probability distributions. +For continuous distributions, this is the integral of the probability +density function from @cite{x} to infinity. (These are the ``upper +tail'' distribution functions; there are also corresponding ``lower +tail'' functions which integrate from minus infinity to @cite{x}.) +For discrete distributions, the upper tail function gives the sum +from @cite{x} to infinity; the lower tail function gives the sum +from minus infinity up to, but not including,@w{ }@cite{x}. + +To integrate from @cite{x} to @cite{y}, just use the distribution +function twice and subtract. For example, the probability that a +Gaussian random variable with mean 2 and standard deviation 1 will +lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)} +(``the probability that it is greater than 2.5, but not greater than 2.8''), +or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}. + +@kindex k B +@kindex I k B +@pindex calc-utpb +@tindex utpb +@tindex ltpb +The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the +binomial distribution. Push the parameters @var{n}, @var{p}, and +then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the +probability that an event will occur @var{x} or more times out +of @var{n} trials, if its probability of occurring in any given +trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is +the probability that the event will occur fewer than @var{x} times. + +The other probability distribution functions similarly take the +form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}] +and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters +@var{x}. The arguments to the algebraic functions are the value of +the random variable first, then whatever other parameters define the +distribution. Note these are among the few Calc functions where the +order of the arguments in algebraic form differs from the order of +arguments as found on the stack. (The random variable comes last on +the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5 +k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to +recover the original arguments but substitute a new value for @cite{x}.) + +@kindex k C +@pindex calc-utpc +@tindex utpc +@c @mindex @idots +@kindex I k C +@c @mindex @null +@tindex ltpc +The @samp{utpc(x,v)} function uses the chi-square distribution with +@c{$\nu$} +@cite{v} degrees of freedom. It is the probability that a model is +correct if its chi-square statistic is @cite{x}. + +@kindex k F +@pindex calc-utpf +@tindex utpf +@c @mindex @idots +@kindex I k F +@c @mindex @null +@tindex ltpf +The @samp{utpf(F,v1,v2)} function uses the F distribution, used in +various statistical tests. The parameters @c{$\nu_1$} +@cite{v1} and @c{$\nu_2$} +@cite{v2} +are the degrees of freedom in the numerator and denominator, +respectively, used in computing the statistic @cite{F}. + +@kindex k N +@pindex calc-utpn +@tindex utpn +@c @mindex @idots +@kindex I k N +@c @mindex @null +@tindex ltpn +The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution +with mean @cite{m} and standard deviation @c{$\sigma$} +@cite{s}. It is the +probability that such a normal-distributed random variable would +exceed @cite{x}. + +@kindex k P +@pindex calc-utpp +@tindex utpp +@c @mindex @idots +@kindex I k P +@c @mindex @null +@tindex ltpp +The @samp{utpp(n,x)} function uses a Poisson distribution with +mean @cite{x}. It is the probability that @cite{n} or more such +Poisson random events will occur. + +@kindex k T +@pindex calc-ltpt +@tindex utpt +@c @mindex @idots +@kindex I k T +@c @mindex @null +@tindex ltpt +The @samp{utpt(t,v)} function uses the Student's ``t'' distribution +with @c{$\nu$} +@cite{v} degrees of freedom. It is the probability that a +t-distributed random variable will be greater than @cite{t}. +(Note: This computes the distribution function @c{$A(t|\nu)$} +@cite{A(t|v)} +where @c{$A(0|\nu) = 1$} +@cite{A(0|v) = 1} and @c{$A(\infty|\nu) \to 0$} +@cite{A(inf|v) -> 0}. The +@code{UTPT} operation on the HP-48 uses a different definition +which returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.) + +While Calc does not provide inverses of the probability distribution +functions, the @kbd{a R} command can be used to solve for the inverse. +Since the distribution functions are monotonic, @kbd{a R} is guaranteed +to be able to find a solution given any initial guess. +@xref{Numerical Solutions}. + +@node Matrix Functions, Algebra, Scientific Functions, Top +@chapter Vector/Matrix Functions + +@noindent +Many of the commands described here begin with the @kbd{v} prefix. +(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.) +The commands usually apply to both plain vectors and matrices; some +apply only to matrices or only to square matrices. If the argument +has the wrong dimensions the operation is left in symbolic form. + +Vectors are entered and displayed using @samp{[a,b,c]} notation. +Matrices are vectors of which all elements are vectors of equal length. +(Though none of the standard Calc commands use this concept, a +three-dimensional matrix or rank-3 tensor could be defined as a +vector of matrices, and so on.) + +@menu +* Packing and Unpacking:: +* Building Vectors:: +* Extracting Elements:: +* Manipulating Vectors:: +* Vector and Matrix Arithmetic:: +* Set Operations:: +* Statistical Operations:: +* Reducing and Mapping:: +* Vector and Matrix Formats:: +@end menu + +@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions +@section Packing and Unpacking + +@noindent +Calc's ``pack'' and ``unpack'' commands collect stack entries to build +composite objects such as vectors and complex numbers. They are +described in this chapter because they are most often used to build +vectors. + +@kindex v p +@pindex calc-pack +The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several +elements from the stack into a matrix, complex number, HMS form, error +form, etc. It uses a numeric prefix argument to specify the kind of +object to be built; this argument is referred to as the ``packing mode.'' +If the packing mode is a nonnegative integer, a vector of that +length is created. For example, @kbd{C-u 5 v p} will pop the top +five stack elements and push back a single vector of those five +elements. (@kbd{C-u 0 v p} simply creates an empty vector.) + +The same effect can be had by pressing @kbd{[} to push an incomplete +vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak +the incomplete object up past a certain number of elements, and +then pressing @kbd{]} to complete the vector. + +Negative packing modes create other kinds of composite objects: + +@table @cite +@item -1 +Two values are collected to build a complex number. For example, +@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number +@cite{(5, 7)}. The result is always a rectangular complex +number. The two input values must both be real numbers, +i.e., integers, fractions, or floats. If they are not, Calc +will instead build a formula like @samp{a + (0, 1) b}. (The +other packing modes also create a symbolic answer if the +components are not suitable.) + +@item -2 +Two values are collected to build a polar complex number. +The first is the magnitude; the second is the phase expressed +in either degrees or radians according to the current angular +mode. + +@item -3 +Three values are collected into an HMS form. The first +two values (hours and minutes) must be integers or +integer-valued floats. The third value may be any real +number. + +@item -4 +Two values are collected into an error form. The inputs +may be real numbers or formulas. + +@item -5 +Two values are collected into a modulo form. The inputs +must be real numbers. + +@item -6 +Two values are collected into the interval @samp{[a .. b]}. +The inputs may be real numbers, HMS or date forms, or formulas. + +@item -7 +Two values are collected into the interval @samp{[a .. b)}. + +@item -8 +Two values are collected into the interval @samp{(a .. b]}. + +@item -9 +Two values are collected into the interval @samp{(a .. b)}. + +@item -10 +Two integer values are collected into a fraction. + +@item -11 +Two values are collected into a floating-point number. +The first is the mantissa; the second, which must be an +integer, is the exponent. The result is the mantissa +times ten to the power of the exponent. + +@item -12 +This is treated the same as @i{-11} by the @kbd{v p} command. +When unpacking, @i{-12} specifies that a floating-point mantissa +is desired. + +@item -13 +A real number is converted into a date form. + +@item -14 +Three numbers (year, month, day) are packed into a pure date form. + +@item -15 +Six numbers are packed into a date/time form. +@end table + +With any of the two-input negative packing modes, either or both +of the inputs may be vectors. If both are vectors of the same +length, the result is another vector made by packing corresponding +elements of the input vectors. If one input is a vector and the +other is a plain number, the number is packed along with each vector +element to produce a new vector. For example, @kbd{C-u -4 v p} +could be used to convert a vector of numbers and a vector of errors +into a single vector of error forms; @kbd{C-u -5 v p} could convert +a vector of numbers and a single number @var{M} into a vector of +numbers modulo @var{M}. + +If you don't give a prefix argument to @kbd{v p}, it takes +the packing mode from the top of the stack. The elements to +be packed then begin at stack level 2. Thus +@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to +enter the error form @samp{1 +/- 2}. + +If the packing mode taken from the stack is a vector, the result is a +matrix with the dimensions specified by the elements of the vector, +which must each be integers. For example, if the packing mode is +@samp{[2, 3]}, then six numbers will be taken from the stack and +returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}. + +If any elements of the vector are negative, other kinds of +packing are done at that level as described above. For +example, @samp{[2, 3, -4]} takes 12 objects and creates a +@c{$2\times3$} +@asis{2x3} matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}. +Also, @samp{[-4, -10]} will convert four integers into an +error form consisting of two fractions: @samp{a:b +/- c:d}. + +@c @starindex +@tindex pack +There is an equivalent algebraic function, +@samp{pack(@var{mode}, @var{items})} where @var{mode} is a +packing mode (an integer or a vector of integers) and @var{items} +is a vector of objects to be packed (re-packed, really) according +to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])} +yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is +left in symbolic form if the packing mode is illegal, or if the +number of data items does not match the number of items required +by the mode. + +@kindex v u +@pindex calc-unpack +The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex +number, HMS form, or other composite object on the top of the stack and +``unpacks'' it, pushing each of its elements onto the stack as separate +objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value +at the top of the stack is a formula, @kbd{v u} unpacks it by pushing +each of the arguments of the top-level operator onto the stack. + +You can optionally give a numeric prefix argument to @kbd{v u} +to specify an explicit (un)packing mode. If the packing mode is +negative and the input is actually a vector or matrix, the result +will be two or more similar vectors or matrices of the elements. +For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]}, +the result of @kbd{C-u -4 v u} will be the two vectors +@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}. + +Note that the prefix argument can have an effect even when the input is +not a vector. For example, if the input is the number @i{-5}, then +@kbd{c-u -1 v u} yields @i{-5} and 0 (the components of @i{-5} +when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5 +and 180 (assuming degrees mode); and @kbd{C-u -10 v u} yields @i{-5} +and 1 (the numerator and denominator of @i{-5}, viewed as a rational +number). Plain @kbd{v u} with this input would complain that the input +is not a composite object. + +Unpacking mode @i{-11} converts a float into an integer mantissa and +an integer exponent, where the mantissa is not divisible by 10 +(except that 0.0 is represented by a mantissa and exponent of 0). +Unpacking mode @i{-12} converts a float into a floating-point mantissa +and integer exponent, where the mantissa (for non-zero numbers) +is guaranteed to lie in the range [1 .. 10). In both cases, +the mantissa is shifted left or right (and the exponent adjusted +to compensate) in order to satisfy these constraints. + +Positive unpacking modes are treated differently than for @kbd{v p}. +A mode of 1 is much like plain @kbd{v u} with no prefix argument, +except that in addition to the components of the input object, +a suitable packing mode to re-pack the object is also pushed. +Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the +original object. + +A mode of 2 unpacks two levels of the object; the resulting +re-packing mode will be a vector of length 2. This might be used +to unpack a matrix, say, or a vector of error forms. Higher +unpacking modes unpack the input even more deeply. + +@c @starindex +@tindex unpack +There are two algebraic functions analogous to @kbd{v u}. +The @samp{unpack(@var{mode}, @var{item})} function unpacks the +@var{item} using the given @var{mode}, returning the result as +a vector of components. Here the @var{mode} must be an +integer, not a vector. For example, @samp{unpack(-4, a +/- b)} +returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}. + +@c @starindex +@tindex unpackt +The @code{unpackt} function is like @code{unpack} but instead +of returning a simple vector of items, it returns a vector of +two things: The mode, and the vector of items. For example, +@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]}, +and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}. +The identity for re-building the original object is +@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The +@code{apply} function builds a function call given the function +name and a vector of arguments.) + +@cindex Numerator of a fraction, extracting +Subscript notation is a useful way to extract a particular part +of an object. For example, to get the numerator of a rational +number, you can use @samp{unpack(-10, @var{x})_1}. + +@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions +@section Building Vectors + +@noindent +Vectors and matrices can be added, +subtracted, multiplied, and divided; @pxref{Basic Arithmetic}.@refill + +@kindex | +@pindex calc-concat +@c @mindex @null +@tindex | +The @kbd{|} (@code{calc-concat}) command ``concatenates'' two vectors +into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack +will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments +are matrices, the rows of the first matrix are concatenated with the +rows of the second. (In other words, two matrices are just two vectors +of row-vectors as far as @kbd{|} is concerned.) + +If either argument to @kbd{|} is a scalar (a non-vector), it is treated +like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |} +produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a +matrix and the other is a plain vector, the vector is treated as a +one-row matrix. + +@kindex H | +@tindex append +The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates +two vectors without any special cases. Both inputs must be vectors. +Whether or not they are matrices is not taken into account. If either +argument is a scalar, the @code{append} function is left in symbolic form. +See also @code{cons} and @code{rcons} below. + +@kindex I | +@kindex H I | +The @kbd{I |} and @kbd{H I |} commands are similar, but they use their +two stack arguments in the opposite order. Thus @kbd{I |} is equivalent +to @kbd{TAB |}, but possibly more convenient and also a bit faster. + +@kindex v d +@pindex calc-diag +@tindex diag +The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal +square matrix. The optional numeric prefix gives the number of rows +and columns in the matrix. If the value at the top of the stack is a +vector, the elements of the vector are used as the diagonal elements; the +prefix, if specified, must match the size of the vector. If the value on +the stack is a scalar, it is used for each element on the diagonal, and +the prefix argument is required. + +To build a constant square matrix, e.g., a @c{$3\times3$} +@asis{3x3} matrix filled with ones, +use @kbd{0 M-3 v d 1 +}, i.e., build a zero matrix first and then add a +constant value to that matrix. (Another alternative would be to use +@kbd{v b} and @kbd{v a}; see below.) + +@kindex v i +@pindex calc-ident +@tindex idn +The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity +matrix of the specified size. It is a convenient form of @kbd{v d} +where the diagonal element is always one. If no prefix argument is given, +this command prompts for one. + +In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)}, +except that @cite{a} is required to be a scalar (non-vector) quantity. +If @cite{n} is omitted, @samp{idn(a)} represents @cite{a} times an +identity matrix of unknown size. Calc can operate algebraically on +such generic identity matrices, and if one is combined with a matrix +whose size is known, it is converted automatically to an identity +matrix of a suitable matching size. The @kbd{v i} command with an +argument of zero creates a generic identity matrix, @samp{idn(1)}. +Note that in dimensioned matrix mode (@pxref{Matrix Mode}), generic +identity matrices are immediately expanded to the current default +dimensions. + +@kindex v x +@pindex calc-index +@tindex index +The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector +of consecutive integers from 1 to @var{n}, where @var{n} is the numeric +prefix argument. If you do not provide a prefix argument, you will be +prompted to enter a suitable number. If @var{n} is negative, the result +is a vector of negative integers from @var{n} to @i{-1}. + +With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes +three values from the stack: @var{n}, @var{start}, and @var{incr} (with +@var{incr} at top-of-stack). Counting starts at @var{start} and increases +by @var{incr} for successive vector elements. If @var{start} or @var{n} +is in floating-point format, the resulting vector elements will also be +floats. Note that @var{start} and @var{incr} may in fact be any kind +of numbers or formulas. + +When @var{start} and @var{incr} are specified, a negative @var{n} has a +different interpretation: It causes a geometric instead of arithmetic +sequence to be generated. For example, @samp{index(-3, a, b)} produces +@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form, +@samp{index(@var{n}, @var{start})}, the default value for @var{incr} +is one for positive @var{n} or two for negative @var{n}. + +@kindex v b +@pindex calc-build-vector +@tindex cvec +The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a +vector of @var{n} copies of the value on the top of the stack, where @var{n} +is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)} +can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}. +(Interactively, just use @kbd{v b} twice: once to build a row, then again +to build a matrix of copies of that row.) + +@kindex v h +@kindex I v h +@pindex calc-head +@pindex calc-tail +@tindex head +@tindex tail +The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first +element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}] +function returns the vector with its first element removed. In both +cases, the argument must be a non-empty vector. + +@kindex v k +@pindex calc-cons +@tindex cons +The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h} +and a vector @var{t} from the stack, and produces the vector whose head is +@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except +if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors +whereas @code{cons} will insert @var{h} at the front of the vector @var{t}. + +@kindex H v h +@tindex rhead +@c @mindex @idots +@kindex H I v h +@c @mindex @null +@kindex H v k +@c @mindex @null +@tindex rtail +@c @mindex @null +@tindex rcons +Each of these three functions also accepts the Hyperbolic flag [@code{rhead}, +@code{rtail}, @code{rcons}] in which case @var{t} instead represents +the @emph{last} single element of the vector, with @var{h} +representing the remainder of the vector. Thus the vector +@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}. +Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]}, +@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}. + +@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions +@section Extracting Vector Elements + +@noindent +@kindex v r +@pindex calc-mrow +@tindex mrow +The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of +the matrix on the top of the stack, or one element of the plain vector on +the top of the stack. The row or element is specified by the numeric +prefix argument; the default is to prompt for the row or element number. +The matrix or vector is replaced by the specified row or element in the +form of a vector or scalar, respectively. + +@cindex Permutations, applying +With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of +the element or row from the top of the stack, and the vector or matrix +from the second-to-top position. If the index is itself a vector of +integers, the result is a vector of the corresponding elements of the +input vector, or a matrix of the corresponding rows of the input matrix. +This command can be used to obtain any permutation of a vector. + +With @kbd{C-u}, if the index is an interval form with integer components, +it is interpreted as a range of indices and the corresponding subvector or +submatrix is returned. + +@cindex Subscript notation +@kindex a _ +@pindex calc-subscript +@tindex subscr +@tindex _ +Subscript notation in algebraic formulas (@samp{a_b}) stands for the +Calc function @code{subscr}, which is synonymous with @code{mrow}. +Thus, @samp{[x, y, z]_k} produces @cite{x}, @cite{y}, or @cite{z} if +@cite{k} is one, two, or three, respectively. A double subscript +(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will +access the element at row @cite{i}, column @cite{j} of a matrix. +The @kbd{a _} (@code{calc-subscript}) command creates a subscript +formula @samp{a_b} out of two stack entries. (It is on the @kbd{a} +``algebra'' prefix because subscripted variables are often used +purely as an algebraic notation.) + +@tindex mrrow +Given a negative prefix argument, @kbd{v r} instead deletes one row or +element from the matrix or vector on the top of the stack. Thus +@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r} +replaces the matrix with the same matrix with its second row removed. +In algebraic form this function is called @code{mrrow}. + +@tindex getdiag +Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements +of a square matrix in the form of a vector. In algebraic form this +function is called @code{getdiag}. + +@kindex v c +@pindex calc-mcol +@tindex mcol +@tindex mrcol +The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is +the analogous operation on columns of a matrix. Given a plain vector +it extracts (or removes) one element, just like @kbd{v r}. If the +index in @kbd{C-u v c} is an interval or vector and the argument is a +matrix, the result is a submatrix with only the specified columns +retained (and possibly permuted in the case of a vector index).@refill + +To extract a matrix element at a given row and column, use @kbd{v r} to +extract the row as a vector, then @kbd{v c} to extract the column element +from that vector. In algebraic formulas, it is often more convenient to +use subscript notation: @samp{m_i_j} gives row @cite{i}, column @cite{j} +of matrix @cite{m}. + +@kindex v s +@pindex calc-subvector +@tindex subvec +The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts +a subvector of a vector. The arguments are the vector, the starting +index, and the ending index, with the ending index in the top-of-stack +position. The starting index indicates the first element of the vector +to take. The ending index indicates the first element @emph{past} the +range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces +the subvector @samp{[b, c]}. You could get the same result using +@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}. + +If either the start or the end index is zero or negative, it is +interpreted as relative to the end of the vector. Thus +@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In +the algebraic form, the end index can be omitted in which case it +is taken as zero, i.e., elements from the starting element to the +end of the vector are used. The infinity symbol, @code{inf}, also +has this effect when used as the ending index. + +@kindex I v s +@tindex rsubvec +With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector +from a vector. The arguments are interpreted the same as for the +normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)} +produces @samp{[a, d, e]}. It is always true that @code{subvec} and +@code{rsubvec} return complementary parts of the input vector. + +@xref{Selecting Subformulas}, for an alternative way to operate on +vectors one element at a time. + +@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions +@section Manipulating Vectors + +@noindent +@kindex v l +@pindex calc-vlength +@tindex vlen +The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the +length of a vector. The length of a non-vector is considered to be zero. +Note that matrices are just vectors of vectors for the purposes of this +command.@refill + +@kindex H v l +@tindex mdims +With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector +of the dimensions of a vector, matrix, or higher-order object. For +example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since +its argument is a @c{$2\times3$} +@asis{2x3} matrix. + +@kindex v f +@pindex calc-vector-find +@tindex find +The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches +along a vector for the first element equal to a given target. The target +is on the top of the stack; the vector is in the second-to-top position. +If a match is found, the result is the index of the matching element. +Otherwise, the result is zero. The numeric prefix argument, if given, +allows you to select any starting index for the search. + +@kindex v a +@pindex calc-arrange-vector +@tindex arrange +@cindex Arranging a matrix +@cindex Reshaping a matrix +@cindex Flattening a matrix +The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command +rearranges a vector to have a certain number of columns and rows. The +numeric prefix argument specifies the number of columns; if you do not +provide an argument, you will be prompted for the number of columns. +The vector or matrix on the top of the stack is @dfn{flattened} into a +plain vector. If the number of columns is nonzero, this vector is +then formed into a matrix by taking successive groups of @var{n} elements. +If the number of columns does not evenly divide the number of elements +in the vector, the last row will be short and the result will not be +suitable for use as a matrix. For example, with the matrix +@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces +@samp{[[1, 2, 3, 4]]} (a @c{$1\times4$} +@asis{1x4} matrix), @kbd{v a 1} produces +@samp{[[1], [2], [3], [4]]} (a @c{$4\times1$} +@asis{4x1} matrix), @kbd{v a 2} produces +@samp{[[1, 2], [3, 4]]} (the original @c{$2\times2$} +@asis{2x2} matrix), @w{@kbd{v a 3}} produces +@samp{[[1, 2, 3], [4]]} (not a matrix), and @kbd{v a 0} produces +the flattened list @samp{[1, 2, @w{3, 4}]}. + +@cindex Sorting data +@kindex V S +@kindex I V S +@pindex calc-sort +@tindex sort +@tindex rsort +The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of +a vector into increasing order. Real numbers, real infinities, and +constant interval forms come first in this ordering; next come other +kinds of numbers, then variables (in alphabetical order), then finally +come formulas and other kinds of objects; these are sorted according +to a kind of lexicographic ordering with the useful property that +one vector is less or greater than another if the first corresponding +unequal elements are less or greater, respectively. Since quoted strings +are stored by Calc internally as vectors of ASCII character codes +(@pxref{Strings}), this means vectors of strings are also sorted into +alphabetical order by this command. + +The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order. + +@cindex Permutation, inverse of +@cindex Inverse of permutation +@cindex Index tables +@cindex Rank tables +@kindex V G +@kindex I V G +@pindex calc-grade +@tindex grade +@tindex rgrade +The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command +produces an index table or permutation vector which, if applied to the +input vector (as the index of @kbd{C-u v r}, say), would sort the vector. +A permutation vector is just a vector of integers from 1 to @var{n}, where +each integer occurs exactly once. One application of this is to sort a +matrix of data rows using one column as the sort key; extract that column, +grade it with @kbd{V G}, then use the result to reorder the original matrix +with @kbd{C-u v r}. Another interesting property of the @code{V G} command +is that, if the input is itself a permutation vector, the result will +be the inverse of the permutation. The inverse of an index table is +a rank table, whose @var{k}th element says where the @var{k}th original +vector element will rest when the vector is sorted. To get a rank +table, just use @kbd{V G V G}. + +With the Inverse flag, @kbd{I V G} produces an index table that would +sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G} +use a ``stable'' sorting algorithm, i.e., any two elements which are equal +will not be moved out of their original order. Generally there is no way +to tell with @kbd{V S}, since two elements which are equal look the same, +but with @kbd{V G} this can be an important issue. In the matrix-of-rows +example, suppose you have names and telephone numbers as two columns and +you wish to sort by phone number primarily, and by name when the numbers +are equal. You can sort the data matrix by names first, and then again +by phone numbers. Because the sort is stable, any two rows with equal +phone numbers will remain sorted by name even after the second sort. + +@cindex Histograms +@kindex V H +@pindex calc-histogram +@c @mindex histo@idots +@tindex histogram +The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a +histogram of a vector of numbers. Vector elements are assumed to be +integers or real numbers in the range [0..@var{n}) for some ``number of +bins'' @var{n}, which is the numeric prefix argument given to the +command. The result is a vector of @var{n} counts of how many times +each value appeared in the original vector. Non-integers in the input +are rounded down to integers. Any vector elements outside the specified +range are ignored. (You can tell if elements have been ignored by noting +that the counts in the result vector don't add up to the length of the +input vector.) + +@kindex H V H +With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack. +The second-to-top vector is the list of numbers as before. The top +vector is an equal-sized list of ``weights'' to attach to the elements +of the data vector. For example, if the first data element is 4.2 and +the first weight is 10, then 10 will be added to bin 4 of the result +vector. Without the hyperbolic flag, every element has a weight of one. + +@kindex v t +@pindex calc-transpose +@tindex trn +The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes +the transpose of the matrix at the top of the stack. If the argument +is a plain vector, it is treated as a row vector and transposed into +a one-column matrix. + +@kindex v v +@pindex calc-reverse-vector +@tindex rev +The @kbd{v v} (@code{calc-reverse-vector}) [@code{vec}] command reverses +a vector end-for-end. Given a matrix, it reverses the order of the rows. +(To reverse the columns instead, just use @kbd{v t v v v t}. The same +principle can be used to apply other vector commands to the columns of +a matrix.) + +@kindex v m +@pindex calc-mask-vector +@tindex vmask +The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses +one vector as a mask to extract elements of another vector. The mask +is in the second-to-top position; the target vector is on the top of +the stack. These vectors must have the same length. The result is +the same as the target vector, but with all elements which correspond +to zeros in the mask vector deleted. Thus, for example, +@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}. +@xref{Logical Operations}. + +@kindex v e +@pindex calc-expand-vector +@tindex vexp +The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command +expands a vector according to another mask vector. The result is a +vector the same length as the mask, but with nonzero elements replaced +by successive elements from the target vector. The length of the target +vector is normally the number of nonzero elements in the mask. If the +target vector is longer, its last few elements are lost. If the target +vector is shorter, the last few nonzero mask elements are left +unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])} +produces @samp{[a, 0, b, 0, 7]}. + +@kindex H v e +With the Hyperbolic flag, @kbd{H v e} takes a filler value from the +top of the stack; the mask and target vectors come from the third and +second elements of the stack. This filler is used where the mask is +zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces +@samp{[a, z, c, z, 7]}. If the filler value is itself a vector, +then successive values are taken from it, so that the effect is to +interleave two vectors according to the mask: +@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces +@samp{[a, x, b, 7, y, 0]}. + +Another variation on the masking idea is to combine @samp{[a, b, c, d, e]} +with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}. +You can accomplish this with @kbd{V M a &}, mapping the logical ``and'' +operation across the two vectors. @xref{Logical Operations}. Note that +the @code{? :} operation also discussed there allows other types of +masking using vectors. + +@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions +@section Vector and Matrix Arithmetic + +@noindent +Basic arithmetic operations like addition and multiplication are defined +for vectors and matrices as well as for numbers. Division of matrices, in +the sense of multiplying by the inverse, is supported. (Division by a +matrix actually uses LU-decomposition for greater accuracy and speed.) +@xref{Basic Arithmetic}. + +The following functions are applied element-wise if their arguments are +vectors or matrices: @code{change-sign}, @code{conj}, @code{arg}, +@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean}, +@code{float}, @code{frac}. @xref{Function Index}.@refill + +@kindex V J +@pindex calc-conj-transpose +@tindex ctrn +The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes +the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}. + +@c @mindex A +@kindex A (vectors) +@pindex calc-abs (vectors) +@c @mindex abs +@tindex abs (vectors) +The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the +Frobenius norm of a vector or matrix argument. This is the square +root of the sum of the squares of the absolute values of the +elements of the vector or matrix. If the vector is interpreted as +a point in two- or three-dimensional space, this is the distance +from that point to the origin.@refill + +@kindex v n +@pindex calc-rnorm +@tindex rnorm +The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes +the row norm, or infinity-norm, of a vector or matrix. For a plain +vector, this is the maximum of the absolute values of the elements. +For a matrix, this is the maximum of the row-absolute-value-sums, +i.e., of the sums of the absolute values of the elements along the +various rows. + +@kindex V N +@pindex calc-cnorm +@tindex cnorm +The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes +the column norm, or one-norm, of a vector or matrix. For a plain +vector, this is the sum of the absolute values of the elements. +For a matrix, this is the maximum of the column-absolute-value-sums. +General @cite{k}-norms for @cite{k} other than one or infinity are +not provided. + +@kindex V C +@pindex calc-cross +@tindex cross +The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the +right-handed cross product of two vectors, each of which must have +exactly three elements. + +@c @mindex & +@kindex & (matrices) +@pindex calc-inv (matrices) +@c @mindex inv +@tindex inv (matrices) +The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the +inverse of a square matrix. If the matrix is singular, the inverse +operation is left in symbolic form. Matrix inverses are recorded so +that once an inverse (or determinant) of a particular matrix has been +computed, the inverse and determinant of the matrix can be recomputed +quickly in the future. + +If the argument to @kbd{&} is a plain number @cite{x}, this +command simply computes @cite{1/x}. This is okay, because the +@samp{/} operator also does a matrix inversion when dividing one +by a matrix. + +@kindex V D +@pindex calc-mdet +@tindex det +The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the +determinant of a square matrix. + +@kindex V L +@pindex calc-mlud +@tindex lud +The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the +LU decomposition of a matrix. The result is a list of three matrices +which, when multiplied together left-to-right, form the original matrix. +The first is a permutation matrix that arises from pivoting in the +algorithm, the second is lower-triangular with ones on the diagonal, +and the third is upper-triangular. + +@kindex V T +@pindex calc-mtrace +@tindex tr +The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the +trace of a square matrix. This is defined as the sum of the diagonal +elements of the matrix. + +@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions +@section Set Operations using Vectors + +@noindent +@cindex Sets, as vectors +Calc includes several commands which interpret vectors as @dfn{sets} of +objects. A set is a collection of objects; any given object can appear +only once in the set. Calc stores sets as vectors of objects in +sorted order. Objects in a Calc set can be any of the usual things, +such as numbers, variables, or formulas. Two set elements are considered +equal if they are identical, except that numerically equal numbers like +the integer 4 and the float 4.0 are considered equal even though they +are not ``identical.'' Variables are treated like plain symbols without +attached values by the set operations; subtracting the set @samp{[b]} +from @samp{[a, b]} always yields the set @samp{[a]} even though if +the variables @samp{a} and @samp{b} both equalled 17, you might +expect the answer @samp{[]}. + +If a set contains interval forms, then it is assumed to be a set of +real numbers. In this case, all set operations require the elements +of the set to be only things that are allowed in intervals: Real +numbers, plus and minus infinity, HMS forms, and date forms. If +there are variables or other non-real objects present in a real set, +all set operations on it will be left in unevaluated form. + +If the input to a set operation is a plain number or interval form +@var{a}, it is treated like the one-element vector @samp{[@var{a}]}. +The result is always a vector, except that if the set consists of a +single interval, the interval itself is returned instead. + +@xref{Logical Operations}, for the @code{in} function which tests if +a certain value is a member of a given set. To test if the set @cite{A} +is a subset of the set @cite{B}, use @samp{vdiff(A, B) = []}. + +@kindex V + +@pindex calc-remove-duplicates +@tindex rdup +The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command +converts an arbitrary vector into set notation. It works by sorting +the vector as if by @kbd{V S}, then removing duplicates. (For example, +@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then +reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as +necessary. You rarely need to use @kbd{V +} explicitly, since all the +other set-based commands apply @kbd{V +} to their inputs before using +them. + +@kindex V V +@pindex calc-set-union +@tindex vunion +The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes +the union of two sets. An object is in the union of two sets if and +only if it is in either (or both) of the input sets. (You could +accomplish the same thing by concatenating the sets with @kbd{|}, +then using @kbd{V +}.) + +@kindex V ^ +@pindex calc-set-intersect +@tindex vint +The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes +the intersection of two sets. An object is in the intersection if +and only if it is in both of the input sets. Thus if the input +sets are disjoint, i.e., if they share no common elements, the result +will be the empty vector @samp{[]}. Note that the characters @kbd{V} +and @kbd{^} were chosen to be close to the conventional mathematical +notation for set union@c{ ($A \cup B$)} +@asis{} and intersection@c{ ($A \cap B$)} +@asis{}. + +@kindex V - +@pindex calc-set-difference +@tindex vdiff +The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes +the difference between two sets. An object is in the difference +@cite{A - B} if and only if it is in @cite{A} but not in @cite{B}. +Thus subtracting @samp{[y,z]} from a set will remove the elements +@samp{y} and @samp{z} if they are present. You can also think of this +as a general @dfn{set complement} operator; if @cite{A} is the set of +all possible values, then @cite{A - B} is the ``complement'' of @cite{B}. +Obviously this is only practical if the set of all possible values in +your problem is small enough to list in a Calc vector (or simple +enough to express in a few intervals). + +@kindex V X +@pindex calc-set-xor +@tindex vxor +The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes +the ``exclusive-or,'' or ``symmetric difference'' of two sets. +An object is in the symmetric difference of two sets if and only +if it is in one, but @emph{not} both, of the sets. Objects that +occur in both sets ``cancel out.'' + +@kindex V ~ +@pindex calc-set-complement +@tindex vcompl +The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command +computes the complement of a set with respect to the real numbers. +Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}. +For example, @samp{vcompl([2, (3 .. 4]])} evaluates to +@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}. + +@kindex V F +@pindex calc-set-floor +@tindex vfloor +The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command +reinterprets a set as a set of integers. Any non-integer values, +and intervals that do not enclose any integers, are removed. Open +intervals are converted to equivalent closed intervals. Successive +integers are converted into intervals of integers. For example, the +complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted +the complement with respect to the set of integers you could type +@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}. + +@kindex V E +@pindex calc-set-enumerate +@tindex venum +The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command +converts a set of integers into an explicit vector. Intervals in +the set are expanded out to lists of all integers encompassed by +the intervals. This only works for finite sets (i.e., sets which +do not involve @samp{-inf} or @samp{inf}). + +@kindex V : +@pindex calc-set-span +@tindex vspan +The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any +set of reals into an interval form that encompasses all its elements. +The lower limit will be the smallest element in the set; the upper +limit will be the largest element. For an empty set, @samp{vspan([])} +returns the empty interval @w{@samp{[0 .. 0)}}. + +@kindex V # +@pindex calc-set-cardinality +@tindex vcard +The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts +the number of integers in a set. The result is the length of the vector +that would be produced by @kbd{V E}, although the computation is much +more efficient than actually producing that vector. + +@cindex Sets, as binary numbers +Another representation for sets that may be more appropriate in some +cases is binary numbers. If you are dealing with sets of integers +in the range 0 to 49, you can use a 50-bit binary number where a +particular bit is 1 if the corresponding element is in the set. +@xref{Binary Functions}, for a list of commands that operate on +binary numbers. Note that many of the above set operations have +direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}), +@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}), +@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}), +respectively. You can use whatever representation for sets is most +convenient to you. + +@kindex b p +@kindex b u +@pindex calc-pack-bits +@pindex calc-unpack-bits +@tindex vpack +@tindex vunpack +The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command +converts an integer that represents a set in binary into a set +in vector/interval notation. For example, @samp{vunpack(67)} +returns @samp{[[0 .. 1], 6]}. If the input is negative, the set +it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}. +Use @kbd{V E} afterwards to expand intervals to individual +values if you wish. Note that this command uses the @kbd{b} +(binary) prefix key. + +The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command +converts the other way, from a vector or interval representing +a set of nonnegative integers into a binary integer describing +the same set. The set may include positive infinity, but must +not include any negative numbers. The input is interpreted as a +set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware +that a simple input like @samp{[100]} can result in a huge integer +representation (@c{$2^{100}$} +@cite{2^100}, a 31-digit integer, in this case). + +@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions +@section Statistical Operations on Vectors + +@noindent +@cindex Statistical functions +The commands in this section take vectors as arguments and compute +various statistical measures on the data stored in the vectors. The +references used in the definitions of these functions are Bevington's +@emph{Data Reduction and Error Analysis for the Physical Sciences}, +and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and +Vetterling. + +The statistical commands use the @kbd{u} prefix key followed by +a shifted letter or other character. + +@xref{Manipulating Vectors}, for a description of @kbd{V H} +(@code{calc-histogram}). + +@xref{Curve Fitting}, for the @kbd{a F} command for doing +least-squares fits to statistical data. + +@xref{Probability Distribution Functions}, for several common +probability distribution functions. + +@menu +* Single-Variable Statistics:: +* Paired-Sample Statistics:: +@end menu + +@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations +@subsection Single-Variable Statistics + +@noindent +These functions do various statistical computations on single +vectors. Given a numeric prefix argument, they actually pop +@var{n} objects from the stack and combine them into a data +vector. Each object may be either a number or a vector; if a +vector, any sub-vectors inside it are ``flattened'' as if by +@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object +is popped, which (in order to be useful) is usually a vector. + +If an argument is a variable name, and the value stored in that +variable is a vector, then the stored vector is used. This method +has the advantage that if your data vector is large, you can avoid +the slow process of manipulating it directly on the stack. + +These functions are left in symbolic form if any of their arguments +are not numbers or vectors, e.g., if an argument is a formula, or +a non-vector variable. However, formulas embedded within vector +arguments are accepted; the result is a symbolic representation +of the computation, based on the assumption that the formula does +not itself represent a vector. All varieties of numbers such as +error forms and interval forms are acceptable. + +Some of the functions in this section also accept a single error form +or interval as an argument. They then describe a property of the +normal or uniform (respectively) statistical distribution described +by the argument. The arguments are interpreted in the same way as +the @var{M} argument of the random number function @kbd{k r}. In +particular, an interval with integer limits is considered an integer +distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}. +An interval with at least one floating-point limit is a continuous +distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as +@samp{[2.0 .. 5.0]}! + +@kindex u # +@pindex calc-vector-count +@tindex vcount +The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command +computes the number of data values represented by the inputs. +For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7. +If the argument is a single vector with no sub-vectors, this +simply computes the length of the vector. + +@kindex u + +@kindex u * +@pindex calc-vector-sum +@pindex calc-vector-prod +@tindex vsum +@tindex vprod +@cindex Summations (statistical) +The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command +computes the sum of the data values. The @kbd{u *} +(@code{calc-vector-prod}) [@code{vprod}] command computes the +product of the data values. If the input is a single flat vector, +these are the same as @kbd{V R +} and @kbd{V R *} +(@pxref{Reducing and Mapping}).@refill + +@kindex u X +@kindex u N +@pindex calc-vector-max +@pindex calc-vector-min +@tindex vmax +@tindex vmin +The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command +computes the maximum of the data values, and the @kbd{u N} +(@code{calc-vector-min}) [@code{vmin}] command computes the minimum. +If the argument is an interval, this finds the minimum or maximum +value in the interval. (Note that @samp{vmax([2..6)) = 5} as +described above.) If the argument is an error form, this returns +plus or minus infinity. + +@kindex u M +@pindex calc-vector-mean +@tindex vmean +@cindex Mean of data values +The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command +computes the average (arithmetic mean) of the data values. +If the inputs are error forms @c{$x$ @code{+/-} $\sigma$} +@samp{x +/- s}, this is the weighted +mean of the @cite{x} values with weights @c{$1 / \sigma^2$} +@cite{1 / s^2}. +@tex +\turnoffactive +$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over + \displaystyle \sum { 1 \over \sigma_i^2 } } $$ +@end tex +If the inputs are not error forms, this is simply the sum of the +values divided by the count of the values.@refill + +Note that a plain number can be considered an error form with +error @c{$\sigma = 0$} +@cite{s = 0}. If the input to @kbd{u M} is a mixture of +plain numbers and error forms, the result is the mean of the +plain numbers, ignoring all values with non-zero errors. (By the +above definitions it's clear that a plain number effectively +has an infinite weight, next to which an error form with a finite +weight is completely negligible.) + +This function also works for distributions (error forms or +intervals). The mean of an error form `@i{a} @t{+/-} @i{b}' is simply +@cite{a}. The mean of an interval is the mean of the minimum +and maximum values of the interval. + +@kindex I u M +@pindex calc-vector-mean-error +@tindex vmeane +The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}] +command computes the mean of the data points expressed as an +error form. This includes the estimated error associated with +the mean. If the inputs are error forms, the error is the square +root of the reciprocal of the sum of the reciprocals of the squares +of the input errors. (I.e., the variance is the reciprocal of the +sum of the reciprocals of the variances.) +@tex +\turnoffactive +$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$ +@end tex +If the inputs are plain +numbers, the error is equal to the standard deviation of the values +divided by the square root of the number of values. (This works +out to be equivalent to calculating the standard deviation and +then assuming each value's error is equal to this standard +deviation.)@refill +@tex +\turnoffactive +$$ \sigma_\mu^2 = {\sigma^2 \over N} $$ +@end tex + +@kindex H u M +@pindex calc-vector-median +@tindex vmedian +@cindex Median of data values +The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}] +command computes the median of the data values. The values are +first sorted into numerical order; the median is the middle +value after sorting. (If the number of data values is even, +the median is taken to be the average of the two middle values.) +The median function is different from the other functions in +this section in that the arguments must all be real numbers; +variables are not accepted even when nested inside vectors. +(Otherwise it is not possible to sort the data values.) If +any of the input values are error forms, their error parts are +ignored. + +The median function also accepts distributions. For both normal +(error form) and uniform (interval) distributions, the median is +the same as the mean. + +@kindex H I u M +@pindex calc-vector-harmonic-mean +@tindex vhmean +@cindex Harmonic mean +The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}] +command computes the harmonic mean of the data values. This is +defined as the reciprocal of the arithmetic mean of the reciprocals +of the values. +@tex +\turnoffactive +$$ { N \over \displaystyle \sum {1 \over x_i} } $$ +@end tex + +@kindex u G +@pindex calc-vector-geometric-mean +@tindex vgmean +@cindex Geometric mean +The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}] +command computes the geometric mean of the data values. This +is the @i{N}th root of the product of the values. This is also +equal to the @code{exp} of the arithmetic mean of the logarithms +of the data values. +@tex +\turnoffactive +$$ \exp \left ( \sum { \ln x_i } \right ) = + \left ( \prod { x_i } \right)^{1 / N} $$ +@end tex + +@kindex H u G +@tindex agmean +The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric +mean'' of two numbers taken from the stack. This is computed by +replacing the two numbers with their arithmetic mean and geometric +mean, then repeating until the two values converge. +@tex +\turnoffactive +$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$ +@end tex + +@cindex Root-mean-square +Another commonly used mean, the RMS (root-mean-square), can be computed +for a vector of numbers simply by using the @kbd{A} command. + +@kindex u S +@pindex calc-vector-sdev +@tindex vsdev +@cindex Standard deviation +@cindex Sample statistics +The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command +computes the standard deviation@c{ $\sigma$} +@asis{} of the data values. If the +values are error forms, the errors are used as weights just +as for @kbd{u M}. This is the @emph{sample} standard deviation, +whose value is the square root of the sum of the squares of the +differences between the values and the mean of the @cite{N} values, +divided by @cite{N-1}. +@tex +\turnoffactive +$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$ +@end tex + +This function also applies to distributions. The standard deviation +of a single error form is simply the error part. The standard deviation +of a continuous interval happens to equal the difference between the +limits, divided by @c{$\sqrt{12}$} +@cite{sqrt(12)}. The standard deviation of an +integer interval is the same as the standard deviation of a vector +of those integers. + +@kindex I u S +@pindex calc-vector-pop-sdev +@tindex vpsdev +@cindex Population statistics +The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}] +command computes the @emph{population} standard deviation. +It is defined by the same formula as above but dividing +by @cite{N} instead of by @cite{N-1}. The population standard +deviation is used when the input represents the entire set of +data values in the distribution; the sample standard deviation +is used when the input represents a sample of the set of all +data values, so that the mean computed from the input is itself +only an estimate of the true mean. +@tex +\turnoffactive +$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$ +@end tex + +For error forms and continuous intervals, @code{vpsdev} works +exactly like @code{vsdev}. For integer intervals, it computes the +population standard deviation of the equivalent vector of integers. + +@kindex H u S +@kindex H I u S +@pindex calc-vector-variance +@pindex calc-vector-pop-variance +@tindex vvar +@tindex vpvar +@cindex Variance of data values +The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and +@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}] +commands compute the variance of the data values. The variance +is the square@c{ $\sigma^2$} +@asis{} of the standard deviation, i.e., the sum of the +squares of the deviations of the data values from the mean. +(This definition also applies when the argument is a distribution.) + +@c @starindex +@tindex vflat +The @code{vflat} algebraic function returns a vector of its +arguments, interpreted in the same way as the other functions +in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)} +returns @samp{[1, 2, 3, 4, 5]}. + +@node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations +@subsection Paired-Sample Statistics + +@noindent +The functions in this section take two arguments, which must be +vectors of equal size. The vectors are each flattened in the same +way as by the single-variable statistical functions. Given a numeric +prefix argument of 1, these functions instead take one object from +the stack, which must be an @c{$N\times2$} +@asis{Nx2} matrix of data values. Once +again, variable names can be used in place of actual vectors and +matrices. + +@kindex u C +@pindex calc-vector-covariance +@tindex vcov +@cindex Covariance +The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command +computes the sample covariance of two vectors. The covariance +of vectors @var{x} and @var{y} is the sum of the products of the +differences between the elements of @var{x} and the mean of @var{x} +times the differences between the corresponding elements of @var{y} +and the mean of @var{y}, all divided by @cite{N-1}. Note that +the variance of a vector is just the covariance of the vector +with itself. Once again, if the inputs are error forms the +errors are used as weight factors. If both @var{x} and @var{y} +are composed of error forms, the error for a given data point +is taken as the square root of the sum of the squares of the two +input errors. +@tex +\turnoffactive +$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$ +$$ \sigma_{x\!y}^2 = + {\displaystyle {1 \over N-1} + \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2} + \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}} +$$ +@end tex + +@kindex I u C +@pindex calc-vector-pop-covariance +@tindex vpcov +The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}] +command computes the population covariance, which is the same as the +sample covariance computed by @kbd{u C} except dividing by @cite{N} +instead of @cite{N-1}. + +@kindex H u C +@pindex calc-vector-correlation +@tindex vcorr +@cindex Correlation coefficient +@cindex Linear correlation +The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}] +command computes the linear correlation coefficient of two vectors. +This is defined by the covariance of the vectors divided by the +product of their standard deviations. (There is no difference +between sample or population statistics here.) +@tex +\turnoffactive +$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$ +@end tex + +@node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions +@section Reducing and Mapping Vectors + +@noindent +The commands in this section allow for more general operations on the +elements of vectors. + +@kindex V A +@pindex calc-apply +@tindex apply +The simplest of these operations is @kbd{V A} (@code{calc-apply}) +[@code{apply}], which applies a given operator to the elements of a vector. +For example, applying the hypothetical function @code{f} to the vector +@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}. +Applying the @code{+} function to the vector @samp{[a, b]} gives +@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an +error, since the @code{+} function expects exactly two arguments. + +While @kbd{V A} is useful in some cases, you will usually find that either +@kbd{V R} or @kbd{V M}, described below, is closer to what you want. + +@menu +* Specifying Operators:: +* Mapping:: +* Reducing:: +* Nesting and Fixed Points:: +* Generalized Products:: +@end menu + +@node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping +@subsection Specifying Operators + +@noindent +Commands in this section (like @kbd{V A}) prompt you to press the key +corresponding to the desired operator. Press @kbd{?} for a partial +list of the available operators. Generally, an operator is any key or +sequence of keys that would normally take one or more arguments from +the stack and replace them with a result. For example, @kbd{V A H C} +uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh} +expects one argument, @kbd{V A H C} requires a vector with a single +element as its argument.) + +You can press @kbd{x} at the operator prompt to select any algebraic +function by name to use as the operator. This includes functions you +have defined yourself using the @kbd{Z F} command. (@xref{Algebraic +Definitions}.) If you give a name for which no function has been +defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}. +Calc will prompt for the number of arguments the function takes if it +can't figure it out on its own (say, because you named a function that +is currently undefined). It is also possible to type a digit key before +the function name to specify the number of arguments, e.g., +@kbd{V M 3 x f RET} calls @code{f} with three arguments even if it +looks like it ought to have only two. This technique may be necessary +if the function allows a variable number of arguments. For example, +the @kbd{v e} [@code{vexp}] function accepts two or three arguments; +if you want to map with the three-argument version, you will have to +type @kbd{V M 3 v e}. + +It is also possible to apply any formula to a vector by treating that +formula as a function. When prompted for the operator to use, press +@kbd{'} (the apostrophe) and type your formula as an algebraic entry. +You will then be prompted for the argument list, which defaults to a +list of all variables that appear in the formula, sorted into alphabetic +order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}. +The default argument list would be @samp{(x y)}, which means that if +this function is applied to the arguments @samp{[3, 10]} the result will +be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this +way often, you might consider defining it as a function with @kbd{Z F}.) + +Another way to specify the arguments to the formula you enter is with +@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$} +has the same effect as the previous example. The argument list is +automatically taken to be @samp{($$ $)}. (The order of the arguments +may seem backwards, but it is analogous to the way normal algebraic +entry interacts with the stack.) + +If you press @kbd{$} at the operator prompt, the effect is similar to +the apostrophe except that the relevant formula is taken from top-of-stack +instead. The actual vector arguments of the @kbd{V A $} or related command +then start at the second-to-top stack position. You will still be +prompted for an argument list. + +@cindex Nameless functions +@cindex Generic functions +A function can be written without a name using the notation @samp{<#1 - #2>}, +which means ``a function of two arguments that computes the first +argument minus the second argument.'' The symbols @samp{#1} and @samp{#2} +are placeholders for the arguments. You can use any names for these +placeholders if you wish, by including an argument list followed by a +colon: @samp{<x, y : x - y>}. When you type @kbd{V A ' $$ + 2$^$$ RET}, +Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function +to map across the vectors. When you type @kbd{V A ' x + 2y^x RET RET}, +Calc builds the nameless function @w{@samp{<x, y : x + 2 y^x>}}. In both +cases, Calc also writes the nameless function to the Trail so that you +can get it back later if you wish. + +If there is only one argument, you can write @samp{#} in place of @samp{#1}. +(Note that @samp{< >} notation is also used for date forms. Calc tells +that @samp{<@var{stuff}>} is a nameless function by the presence of +@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff} +begins with a list of variables followed by a colon.) + +You can type a nameless function directly to @kbd{V A '}, or put one on +the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an +argument list in this case, since the nameless function specifies the +argument list as well as the function itself. In @kbd{V A '}, you can +omit the @samp{< >} marks if you use @samp{#} notation for the arguments, +so that @kbd{V A ' #1+#2 RET} is the same as @kbd{V A ' <#1+#2> RET}, +which in turn is the same as @kbd{V A ' $$+$ RET}. + +@cindex Lambda expressions +@c @starindex +@tindex lambda +The internal format for @samp{<x, y : x + y>} is @samp{lambda(x, y, x + y)}. +(The word @code{lambda} derives from Lisp notation and the theory of +functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA, +ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called +@code{lambda}; the whole point is that the @code{lambda} expression is +used in its symbolic form, not evaluated for an answer until it is applied +to specific arguments by a command like @kbd{V A} or @kbd{V M}. + +(Actually, @code{lambda} does have one special property: Its arguments +are never evaluated; for example, putting @samp{<(2/3) #>} on the stack +will not simplify the @samp{2/3} until the nameless function is actually +called.) + +@tindex add +@tindex sub +@c @mindex @idots +@tindex mul +@c @mindex @null +@tindex div +@c @mindex @null +@tindex pow +@c @mindex @null +@tindex neg +@c @mindex @null +@tindex mod +@c @mindex @null +@tindex vconcat +As usual, commands like @kbd{V A} have algebraic function name equivalents. +For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to +@samp{apply(gcd, v)}. The first argument specifies the operator name, +and is either a variable whose name is the same as the function name, +or a nameless function like @samp{<#^3+1>}. Operators that are normally +written as algebraic symbols have the names @code{add}, @code{sub}, +@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and +@code{vconcat}.@refill + +@c @starindex +@tindex call +The @code{call} function builds a function call out of several arguments: +@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which +in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call}, +like the other functions described here, may be either a variable naming a +function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same +as @samp{x + 2y}). + +(Experts will notice that it's not quite proper to use a variable to name +a function, since the name @code{gcd} corresponds to the Lisp variable +@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc +automatically makes this translation, so you don't have to worry +about it.) + +@node Mapping, Reducing, Specifying Operators, Reducing and Mapping +@subsection Mapping + +@noindent +@kindex V M +@pindex calc-map +@tindex map +The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given +operator elementwise to one or more vectors. For example, mapping +@code{A} [@code{abs}] produces a vector of the absolute values of the +elements in the input vector. Mapping @code{+} pops two vectors from +the stack, which must be of equal length, and produces a vector of the +pairwise sums of the elements. If either argument is a non-vector, it +is duplicated for each element of the other vector. For example, +@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector. +With the 2 listed first, it would have computed a vector of powers of +two. Mapping a user-defined function pops as many arguments from the +stack as the function requires. If you give an undefined name, you will +be prompted for the number of arguments to use.@refill + +If any argument to @kbd{V M} is a matrix, the operator is normally mapped +across all elements of the matrix. For example, given the matrix +@cite{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to +produce another @c{$3\times2$} +@asis{3x2} matrix, @cite{[[1, 2, 3], [4, 5, 6]]}. + +@tindex mapr +The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the +operator prompt) maps by rows instead. For example, @kbd{V M _ A} views +the above matrix as a vector of two 3-element row vectors. It produces +a new vector which contains the absolute values of those row vectors, +namely @cite{[3.74, 8.77]}. (Recall, the absolute value of a vector is +defined as the square root of the sum of the squares of the elements.) +Some operators accept vectors and return new vectors; for example, +@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row +of the matrix to get a new matrix, @cite{[[3, -2, 1], [-6, 5, -4]]}. + +Sometimes a vector of vectors (representing, say, strings, sets, or lists) +happens to look like a matrix. If so, remember to use @kbd{V M _} if you +want to map a function across the whole strings or sets rather than across +their individual elements. + +@tindex mapc +The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it +transposes the input matrix, maps by rows, and then, if the result is a +matrix, transposes again. For example, @kbd{V M : A} takes the absolute +values of the three columns of the matrix, treating each as a 2-vector, +and @kbd{V M : v v} reverses the columns to get the matrix +@cite{[[-4, 5, -6], [1, -2, 3]]}. + +(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like +and column-like appearances, and were not already taken by useful +operators. Also, they appear shifted on most keyboards so they are easy +to type after @kbd{V M}.) + +The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are +not matrices (so if none of the arguments are matrices, they have no +effect at all). If some of the arguments are matrices and others are +plain numbers, the plain numbers are held constant for all rows of the +matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring +a vector takes a dot product of the vector with itself). + +If some of the arguments are vectors with the same lengths as the +rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix +arguments, those vectors are also held constant for every row or +column. + +Sometimes it is useful to specify another mapping command as the operator +to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +} +to each row of the input matrix, which in turn adds the two values on that +row. If you give another vector-operator command as the operator for +@kbd{V M}, it automatically uses map-by-rows mode if you don't specify +otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If +you really want to map-by-elements another mapping command, you can use +a triple-nested mapping command: @kbd{V M V M V A +} means to map +@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is +mapped over the elements of each row.) + +@tindex mapa +@tindex mapd +Previous versions of Calc had ``map across'' and ``map down'' modes +that are now considered obsolete; the old ``map across'' is now simply +@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic +functions @code{mapa} and @code{mapd} are still supported, though. +Note also that, while the old mapping modes were persistent (once you +set the mode, it would apply to later mapping commands until you reset +it), the new @kbd{:} and @kbd{_} modifiers apply only to the current +mapping command. The default @kbd{V M} always means map-by-elements. + +@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like +@kbd{V M} but for equations and inequalities instead of vectors. +@xref{Storing Variables}, for the @kbd{s m} command which modifies a +variable's stored value using a @kbd{V M}-like operator. + +@node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping +@subsection Reducing + +@noindent +@kindex V R +@pindex calc-reduce +@tindex reduce +The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given +binary operator across all the elements of a vector. A binary operator is +a function such as @code{+} or @code{max} which takes two arguments. For +example, reducing @code{+} over a vector computes the sum of the elements +of the vector. Reducing @code{-} computes the first element minus each of +the remaining elements. Reducing @code{max} computes the maximum element +and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]} +produces @samp{f(f(f(a, b), c), d)}. + +@kindex I V R +@tindex rreduce +The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except +that works from right to left through the vector. For example, plain +@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d} +but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))}, +or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently +in power series expansions. + +@kindex V U +@tindex accum +The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an +accumulation operation. Here Calc does the corresponding reduction +operation, but instead of producing only the final result, it produces +a vector of all the intermediate results. Accumulating @code{+} over +the vector @samp{[a, b, c, d]} produces the vector +@samp{[a, a + b, a + b + c, a + b + c + d]}. + +@kindex I V U +@tindex raccum +The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation. +For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the +vector @samp{[a - b + c - d, b - c + d, c - d, d]}. + +@tindex reducea +@tindex rreducea +@tindex reduced +@tindex rreduced +As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For +example, given the matrix @cite{[[a, b, c], [d, e, f]]}, @kbd{V R +} will +compute @cite{a + b + c + d + e + f}. You can type @kbd{V R _} or +@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}] +command reduces ``across'' the matrix; it reduces each row of the matrix +as a vector, then collects the results. Thus @kbd{V R _ +} of this +matrix would produce @cite{[a + b + c, d + e + f]}. Similarly, @kbd{V R :} +[@code{reduced}] reduces down; @kbd{V R : +} would produce @cite{[a + d, +b + e, c + f]}. + +@tindex reducer +@tindex rreducer +There is a third ``by rows'' mode for reduction that is occasionally +useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over +the rows of the matrix themselves. Thus @kbd{V R = +} on the above +matrix would get the same result as @kbd{V R : +}, since adding two +row vectors is equivalent to adding their elements. But @kbd{V R = *} +would multiply the two rows (to get a single number, their dot product), +while @kbd{V R : *} would produce a vector of the products of the columns. + +These three matrix reduction modes work with @kbd{V R} and @kbd{I V R}, +but they are not currently supported with @kbd{V U} or @kbd{I V U}. + +@tindex reducec +@tindex rreducec +The obsolete reduce-by-columns function, @code{reducec}, is still +supported but there is no way to get it through the @kbd{V R} command. + +The commands @kbd{M-# :} and @kbd{M-# _} are equivalent to typing +@kbd{M-# r} to grab a rectangle of data into Calc, and then typing +@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or +rows of the matrix. @xref{Grabbing From Buffers}. + +@node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping +@subsection Nesting and Fixed Points + +@noindent +@kindex H V R +@tindex nest +The @kbd{H V R} [@code{nest}] command applies a function to a given +argument repeatedly. It takes two values, @samp{a} and @samp{n}, from +the stack, where @samp{n} must be an integer. It then applies the +function nested @samp{n} times; if the function is @samp{f} and @samp{n} +is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be +negative if Calc knows an inverse for the function @samp{f}; for +example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}. + +@kindex H V U +@tindex anest +The @kbd{H V U} [@code{anest}] command is an accumulating version of +@code{nest}: It returns a vector of @samp{n+1} values, e.g., +@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and +@samp{F} is the inverse of @samp{f}, then the result is of the +form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}. + +@kindex H I V R +@tindex fixp +@cindex Fixed points +The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except +that it takes only an @samp{a} value from the stack; the function is +applied until it reaches a ``fixed point,'' i.e., until the result +no longer changes. + +@kindex H I V U +@tindex afixp +The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}. +The first element of the return vector will be the initial value @samp{a}; +the last element will be the final result that would have been returned +by @code{fixp}. + +For example, 0.739085 is a fixed point of the cosine function (in radians): +@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say, +1.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating +version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553, +0.65329, ...]}. With a precision of six, this command will take 36 steps +to converge to 0.739085.) + +Newton's method for finding roots is a classic example of iteration +to a fixed point. To find the square root of five starting with an +initial guess, Newton's method would look for a fixed point of the +function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack +and typing @kbd{H I V R ' ($ + 5/$)/2 RET} quickly yields the result +2.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root}) +command to find a root of the equation @samp{x^2 = 5}. + +These examples used numbers for @samp{a} values. Calc keeps applying +the function until two successive results are equal to within the +current precision. For complex numbers, both the real parts and the +imaginary parts must be equal to within the current precision. If +@samp{a} is a formula (say, a variable name), then the function is +applied until two successive results are exactly the same formula. +It is up to you to ensure that the function will eventually converge; +if it doesn't, you may have to press @kbd{C-g} to stop the Calculator. + +The algebraic @code{fixp} function takes two optional arguments, @samp{n} +and @samp{tol}. The first is the maximum number of steps to be allowed, +and must be either an integer or the symbol @samp{inf} (infinity, the +default). The second is a convergence tolerance. If a tolerance is +specified, all results during the calculation must be numbers, not +formulas, and the iteration stops when the magnitude of the difference +between two successive results is less than or equal to the tolerance. +(This implies that a tolerance of zero iterates until the results are +exactly equal.) + +Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)} +computes the square root of @samp{A} given the initial guess @samp{B}, +stopping when the result is correct within the specified tolerance, or +when 20 steps have been taken, whichever is sooner. + +@node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping +@subsection Generalized Products + +@kindex V O +@pindex calc-outer-product +@tindex outer +The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies +a given binary operator to all possible pairs of elements from two +vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]} +and @samp{[x, y, z]} on the stack produces a multiplication table: +@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of +the result matrix is obtained by applying the operator to element @var{r} +of the lefthand vector and element @var{c} of the righthand vector. + +@kindex V I +@pindex calc-inner-product +@tindex inner +The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes +the generalized inner product of two vectors or matrices, given a +``multiplicative'' operator and an ``additive'' operator. These can each +actually be any binary operators; if they are @samp{*} and @samp{+}, +respectively, the result is a standard matrix multiplication. Element +@var{r},@var{c} of the result matrix is obtained by mapping the +multiplicative operator across row @var{r} of the lefthand matrix and +column @var{c} of the righthand matrix, and then reducing with the additive +operator. Just as for the standard @kbd{*} command, this can also do a +vector-matrix or matrix-vector inner product, or a vector-vector +generalized dot product. + +Since @kbd{V I} requires two operators, it prompts twice. In each case, +you can use any of the usual methods for entering the operator. If you +use @kbd{$} twice to take both operator formulas from the stack, the +first (multiplicative) operator is taken from the top of the stack +and the second (additive) operator is taken from second-to-top. + +@node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions +@section Vector and Matrix Display Formats + +@noindent +Commands for controlling vector and matrix display use the @kbd{v} prefix +instead of the usual @kbd{d} prefix. But they are display modes; in +particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys +in the same way (@pxref{Display Modes}). Matrix display is also +influenced by the @kbd{d O} (@code{calc-flat-language}) mode; +@pxref{Normal Language Modes}. + +@kindex V < +@pindex calc-matrix-left-justify +@kindex V = +@pindex calc-matrix-center-justify +@kindex V > +@pindex calc-matrix-right-justify +The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >} +(@code{calc-matrix-right-justify}), and @w{@kbd{v =}} +(@code{calc-matrix-center-justify}) control whether matrix elements +are justified to the left, right, or center of their columns.@refill + +@kindex V [ +@pindex calc-vector-brackets +@kindex V @{ +@pindex calc-vector-braces +@kindex V ( +@pindex calc-vector-parens +The @kbd{v [} (@code{calc-vector-brackets}) command turns the square +brackets that surround vectors and matrices displayed in the stack on +and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (} +(@code{calc-vector-parens}) commands use curly braces or parentheses, +respectively, instead of square brackets. For example, @kbd{v @{} might +be used in preparation for yanking a matrix into a buffer running +Mathematica. (In fact, the Mathematica language mode uses this mode; +@pxref{Mathematica Language Mode}.) Note that, regardless of the +display mode, either brackets or braces may be used to enter vectors, +and parentheses may never be used for this purpose.@refill + +@kindex V ] +@pindex calc-matrix-brackets +The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the +``big'' style display of matrices. It prompts for a string of code +letters; currently implemented letters are @code{R}, which enables +brackets on each row of the matrix; @code{O}, which enables outer +brackets in opposite corners of the matrix; and @code{C}, which +enables commas or semicolons at the ends of all rows but the last. +The default format is @samp{RO}. (Before Calc 2.00, the format +was fixed at @samp{ROC}.) Here are some example matrices: + +@group +@example +[ [ 123, 0, 0 ] [ [ 123, 0, 0 ], + [ 0, 123, 0 ] [ 0, 123, 0 ], + [ 0, 0, 123 ] ] [ 0, 0, 123 ] ] + + RO ROC + +@end example +@end group +@noindent +@group +@example + [ 123, 0, 0 [ 123, 0, 0 ; + 0, 123, 0 0, 123, 0 ; + 0, 0, 123 ] 0, 0, 123 ] + + O OC + +@end example +@end group +@noindent +@group +@example + [ 123, 0, 0 ] 123, 0, 0 + [ 0, 123, 0 ] 0, 123, 0 + [ 0, 0, 123 ] 0, 0, 123 + + R @r{blank} +@end example +@end group + +@noindent +Note that of the formats shown here, @samp{RO}, @samp{ROC}, and +@samp{OC} are all recognized as matrices during reading, while +the others are useful for display only. + +@kindex V , +@pindex calc-vector-commas +The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and +off in vector and matrix display.@refill + +In vectors of length one, and in all vectors when commas have been +turned off, Calc adds extra parentheses around formulas that might +otherwise be ambiguous. For example, @samp{[a b]} could be a vector +of the one formula @samp{a b}, or it could be a vector of two +variables with commas turned off. Calc will display the former +case as @samp{[(a b)]}. You can disable these extra parentheses +(to make the output less cluttered at the expense of allowing some +ambiguity) by adding the letter @code{P} to the control string you +give to @kbd{v ]} (as described above). + +@kindex V . +@pindex calc-full-vectors +The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated +display of long vectors on and off. In this mode, vectors of six +or more elements, or matrices of six or more rows or columns, will +be displayed in an abbreviated form that displays only the first +three elements and the last element: @samp{[a, b, c, ..., z]}. +When very large vectors are involved this will substantially +improve Calc's display speed. + +@kindex t . +@pindex calc-full-trail-vectors +The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a +similar mode for recording vectors in the Trail. If you turn on +this mode, vectors of six or more elements and matrices of six or +more rows or columns will be abbreviated when they are put in the +Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be +unable to recover those vectors. If you are working with very +large vectors, this mode will improve the speed of all operations +that involve the trail. + +@kindex V / +@pindex calc-break-vectors +The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line +vector display on and off. Normally, matrices are displayed with one +row per line but all other types of vectors are displayed in a single +line. This mode causes all vectors, whether matrices or not, to be +displayed with a single element per line. Sub-vectors within the +vectors will still use the normal linear form. + +@node Algebra, Units, Matrix Functions, Top +@chapter Algebra + +@noindent +This section covers the Calc features that help you work with +algebraic formulas. First, the general sub-formula selection +mechanism is described; this works in conjunction with any Calc +commands. Then, commands for specific algebraic operations are +described. Finally, the flexible @dfn{rewrite rule} mechanism +is discussed. + +The algebraic commands use the @kbd{a} key prefix; selection +commands use the @kbd{j} (for ``just a letter that wasn't used +for anything else'') prefix. + +@xref{Editing Stack Entries}, to see how to manipulate formulas +using regular Emacs editing commands.@refill + +When doing algebraic work, you may find several of the Calculator's +modes to be helpful, including algebraic-simplification mode (@kbd{m A}) +or no-simplification mode (@kbd{m O}), +algebraic-entry mode (@kbd{m a}), fraction mode (@kbd{m f}), and +symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions +of these modes. You may also wish to select ``big'' display mode (@kbd{d B}). +@xref{Normal Language Modes}.@refill + +@menu +* Selecting Subformulas:: +* Algebraic Manipulation:: +* Simplifying Formulas:: +* Polynomials:: +* Calculus:: +* Solving Equations:: +* Numerical Solutions:: +* Curve Fitting:: +* Summations:: +* Logical Operations:: +* Rewrite Rules:: +@end menu + +@node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra +@section Selecting Sub-Formulas + +@noindent +@cindex Selections +@cindex Sub-formulas +@cindex Parts of formulas +When working with an algebraic formula it is often necessary to +manipulate a portion of the formula rather than the formula as a +whole. Calc allows you to ``select'' a portion of any formula on +the stack. Commands which would normally operate on that stack +entry will now operate only on the sub-formula, leaving the +surrounding part of the stack entry alone. + +One common non-algebraic use for selection involves vectors. To work +on one element of a vector in-place, simply select that element as a +``sub-formula'' of the vector. + +@menu +* Making Selections:: +* Changing Selections:: +* Displaying Selections:: +* Operating on Selections:: +* Rearranging with Selections:: +@end menu + +@node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas +@subsection Making Selections + +@noindent +@kindex j s +@pindex calc-select-here +To select a sub-formula, move the Emacs cursor to any character in that +sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will +highlight the smallest portion of the formula that contains that +character. By default the sub-formula is highlighted by blanking out +all of the rest of the formula with dots. Selection works in any +display mode but is perhaps easiest in ``big'' (@kbd{d B}) mode. +Suppose you enter the following formula: + +@group +@smallexample + 3 ___ + (a + b) + V c +1: --------------- + 2 x + 1 +@end smallexample +@end group + +@noindent +(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the +cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes +to + +@group +@smallexample + . ... + .. . b. . . . +1* ............... + . . . . +@end smallexample +@end group + +@noindent +Every character not part of the sub-formula @samp{b} has been changed +to a dot. The @samp{*} next to the line number is to remind you that +the formula has a portion of it selected. (In this case, it's very +obvious, but it might not always be. If Embedded Mode is enabled, +the word @samp{Sel} also appears in the mode line because the stack +may not be visible. @pxref{Embedded Mode}.) + +If you had instead placed the cursor on the parenthesis immediately to +the right of the @samp{b}, the selection would have been: + +@group +@smallexample + . ... + (a + b) . . . +1* ............... + . . . . +@end smallexample +@end group + +@noindent +The portion selected is always large enough to be considered a complete +formula all by itself, so selecting the parenthesis selects the whole +formula that it encloses. Putting the cursor on the the @samp{+} sign +would have had the same effect. + +(Strictly speaking, the Emacs cursor is really the manifestation of +the Emacs ``point,'' which is a position @emph{between} two characters +in the buffer. So purists would say that Calc selects the smallest +sub-formula which contains the character to the right of ``point.'') + +If you supply a numeric prefix argument @var{n}, the selection is +expanded to the @var{n}th enclosing sub-formula. Thus, positioning +the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select +@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3}, +and so on. + +If the cursor is not on any part of the formula, or if you give a +numeric prefix that is too large, the entire formula is selected. + +If the cursor is on the @samp{.} line that marks the top of the stack +(i.e., its normal ``rest position''), this command selects the entire +formula at stack level 1. Most selection commands similarly operate +on the formula at the top of the stack if you haven't positioned the +cursor on any stack entry. + +@kindex j a +@pindex calc-select-additional +The @kbd{j a} (@code{calc-select-additional}) command enlarges the +current selection to encompass the cursor. To select the smallest +sub-formula defined by two different points, move to the first and +press @kbd{j s}, then move to the other and press @kbd{j a}. This +is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to +select the two ends of a region of text during normal Emacs editing. + +@kindex j o +@pindex calc-select-once +The @kbd{j o} (@code{calc-select-once}) command selects a formula in +exactly the same way as @kbd{j s}, except that the selection will +last only as long as the next command that uses it. For example, +@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated +by the cursor. + +(A somewhat more precise definition: The @kbd{j o} command sets a flag +such that the next command involving selected stack entries will clear +the selections on those stack entries afterwards. All other selection +commands except @kbd{j a} and @kbd{j O} clear this flag.) + +@kindex j S +@kindex j O +@pindex calc-select-here-maybe +@pindex calc-select-once-maybe +The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O} +(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s} +and @kbd{j o}, respectively, except that if the formula already +has a selection they have no effect. This is analogous to the +behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection}; +@pxref{Selections with Rewrite Rules}) and is mainly intended to be +used in keyboard macros that implement your own selection-oriented +commands.@refill + +Selection of sub-formulas normally treats associative terms like +@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula. +If you place the cursor anywhere inside @samp{a + b - c + d} except +on one of the variable names and use @kbd{j s}, you will select the +entire four-term sum. + +@kindex j b +@pindex calc-break-selections +The @kbd{j b} (@code{calc-break-selections}) command controls a mode +in which the ``deep structure'' of these associative formulas shows +through. Calc actually stores the above formulas as @samp{((a + b) - c) + d} +and @samp{x * (y * z)}. (Note that for certain obscure reasons, Calc +treats multiplication as right-associative.) Once you have enabled +@kbd{j b} mode, selecting with the cursor on the @samp{-} sign would +only select the @samp{a + b - c} portion, which makes sense when the +deep structure of the sum is considered. There is no way to select +the @samp{b - c + d} portion; although this might initially look +like just as legitimate a sub-formula as @samp{a + b - c}, the deep +structure shows that it isn't. The @kbd{d U} command can be used +to view the deep structure of any formula (@pxref{Normal Language Modes}). + +When @kbd{j b} mode has not been enabled, the deep structure is +generally hidden by the selection commands---what you see is what +you get. + +@kindex j u +@pindex calc-unselect +The @kbd{j u} (@code{calc-unselect}) command unselects the formula +that the cursor is on. If there was no selection in the formula, +this command has no effect. With a numeric prefix argument, it +unselects the @var{n}th stack element rather than using the cursor +position. + +@kindex j c +@pindex calc-clear-selections +The @kbd{j c} (@code{calc-clear-selections}) command unselects all +stack elements. + +@node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas +@subsection Changing Selections + +@noindent +@kindex j m +@pindex calc-select-more +Once you have selected a sub-formula, you can expand it using the +@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is +selected, pressing @w{@kbd{j m}} repeatedly works as follows: + +@group +@smallexample + 3 ... 3 ___ 3 ___ + (a + b) . . . (a + b) + V c (a + b) + V c +1* ............... 1* ............... 1* --------------- + . . . . . . . . 2 x + 1 +@end smallexample +@end group + +@noindent +In the last example, the entire formula is selected. This is roughly +the same as having no selection at all, but because there are subtle +differences the @samp{*} character is still there on the line number. + +With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n} +times (or until the entire formula is selected). Note that @kbd{j s} +with argument @var{n} is equivalent to plain @kbd{j s} followed by +@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there +is no current selection, it is equivalent to @w{@kbd{j s}}. + +Even though @kbd{j m} does not explicitly use the location of the +cursor within the formula, it nevertheless uses the cursor to determine +which stack element to operate on. As usual, @kbd{j m} when the cursor +is not on any stack element operates on the top stack element. + +@kindex j l +@pindex calc-select-less +The @kbd{j l} (@code{calc-select-less}) command reduces the current +selection around the cursor position. That is, it selects the +immediate sub-formula of the current selection which contains the +cursor, the opposite of @kbd{j m}. If the cursor is not inside the +current selection, the command de-selects the formula. + +@kindex j 1-9 +@pindex calc-select-part +The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands +select the @var{n}th sub-formula of the current selection. They are +like @kbd{j l} (@code{calc-select-less}) except they use counting +rather than the cursor position to decide which sub-formula to select. +For example, if the current selection is @kbd{a + b + c} or +@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a}, +@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of +these cases, @kbd{j 4} through @kbd{j 9} would be errors. + +If there is no current selection, @kbd{j 1} through @kbd{j 9} select +the @var{n}th top-level sub-formula. (In other words, they act as if +the entire stack entry were selected first.) To select the @var{n}th +sub-formula where @var{n} is greater than nine, you must instead invoke +@w{@kbd{j 1}} with @var{n} as a numeric prefix argument.@refill + +@kindex j n +@kindex j p +@pindex calc-select-next +@pindex calc-select-previous +The @kbd{j n} (@code{calc-select-next}) and @kbd{j p} +(@code{calc-select-previous}) commands change the current selection +to the next or previous sub-formula at the same level. For example, +if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n} +selects @samp{c}. Further @kbd{j n} commands would be in error because, +even though there is something to the right of @samp{c} (namely, @samp{x}), +it is not at the same level; in this case, it is not a term of the +same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select +the whole product @samp{a*b*c} as a term of the sum) followed by +@w{@kbd{j n}} would successfully select the @samp{x}. + +Similarly, @kbd{j p} moves the selection from the @samp{b} in this +sample formula to the @samp{a}. Both commands accept numeric prefix +arguments to move several steps at a time. + +It is interesting to compare Calc's selection commands with the +Emacs Info system's commands for navigating through hierarchically +organized documentation. Calc's @kbd{j n} command is completely +analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to +@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}. +(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.) +The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and +@kbd{j l}; in each case, you can jump directly to a sub-component +of the hierarchy simply by pointing to it with the cursor. + +@node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas +@subsection Displaying Selections + +@noindent +@kindex j d +@pindex calc-show-selections +The @kbd{j d} (@code{calc-show-selections}) command controls how +selected sub-formulas are displayed. One of the alternatives is +illustrated in the above examples; if we press @kbd{j d} we switch +to the other style in which the selected portion itself is obscured +by @samp{#} signs: + +@group +@smallexample + 3 ... # ___ + (a + b) . . . ## # ## + V c +1* ............... 1* --------------- + . . . . 2 x + 1 +@end smallexample +@end group + +@node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas +@subsection Operating on Selections + +@noindent +Once a selection is made, all Calc commands that manipulate items +on the stack will operate on the selected portions of the items +instead. (Note that several stack elements may have selections +at once, though there can be only one selection at a time in any +given stack element.) + +@kindex j e +@pindex calc-enable-selections +The @kbd{j e} (@code{calc-enable-selections}) command disables the +effect that selections have on Calc commands. The current selections +still exist, but Calc commands operate on whole stack elements anyway. +This mode can be identified by the fact that the @samp{*} markers on +the line numbers are gone, even though selections are visible. To +reactivate the selections, press @kbd{j e} again. + +To extract a sub-formula as a new formula, simply select the +sub-formula and press @key{RET}. This normally duplicates the top +stack element; here it duplicates only the selected portion of that +element. + +To replace a sub-formula with something different, you can enter the +new value onto the stack and press @key{TAB}. This normally exchanges +the top two stack elements; here it swaps the value you entered into +the selected portion of the formula, returning the old selected +portion to the top of the stack. + +@group +@smallexample + 3 ... ... ___ + (a + b) . . . 17 x y . . . 17 x y + V c +2* ............... 2* ............. 2: ------------- + . . . . . . . . 2 x + 1 + + 3 3 +1: 17 x y 1: (a + b) 1: (a + b) +@end smallexample +@end group + +In this example we select a sub-formula of our original example, +enter a new formula, @key{TAB} it into place, then deselect to see +the complete, edited formula. + +If you want to swap whole formulas around even though they contain +selections, just use @kbd{j e} before and after. + +@kindex j ' +@pindex calc-enter-selection +The @kbd{j '} (@code{calc-enter-selection}) command is another way +to replace a selected sub-formula. This command does an algebraic +entry just like the regular @kbd{'} key. When you press @key{RET}, +the formula you type replaces the original selection. You can use +the @samp{$} symbol in the formula to refer to the original +selection. If there is no selection in the formula under the cursor, +the cursor is used to make a temporary selection for the purposes of +the command. Thus, to change a term of a formula, all you have to +do is move the Emacs cursor to that term and press @kbd{j '}. + +@kindex j ` +@pindex calc-edit-selection +The @kbd{j `} (@code{calc-edit-selection}) command is a similar +analogue of the @kbd{`} (@code{calc-edit}) command. It edits the +selected sub-formula in a separate buffer. If there is no +selection, it edits the sub-formula indicated by the cursor. + +To delete a sub-formula, press @key{DEL}. This generally replaces +the sub-formula with the constant zero, but in a few suitable contexts +it uses the constant one instead. The @key{DEL} key automatically +deselects and re-simplifies the entire formula afterwards. Thus: + +@group +@smallexample + ### + 17 x y + # # 17 x y 17 # y 17 y +1* ------------- 1: ------- 1* ------- 1: ------- + 2 x + 1 2 x + 1 2 x + 1 2 x + 1 +@end smallexample +@end group + +In this example, we first delete the @samp{sqrt(c)} term; Calc +accomplishes this by replacing @samp{sqrt(c)} with zero and +resimplifying. We then delete the @kbd{x} in the numerator; +since this is part of a product, Calc replaces it with @samp{1} +and resimplifies. + +If you select an element of a vector and press @key{DEL}, that +element is deleted from the vector. If you delete one side of +an equation or inequality, only the opposite side remains. + +@kindex j DEL +@pindex calc-del-selection +The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like +@key{DEL} but with the auto-selecting behavior of @kbd{j '} and +@kbd{j `}. It deletes the selected portion of the formula +indicated by the cursor, or, in the absence of a selection, it +deletes the sub-formula indicated by the cursor position. + +@kindex j RET +@pindex calc-grab-selection +(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection}) +command.) + +Normal arithmetic operations also apply to sub-formulas. Here we +select the denominator, press @kbd{5 -} to subtract five from the +denominator, press @kbd{n} to negate the denominator, then +press @kbd{Q} to take the square root. + +@group +@smallexample + .. . .. . .. . .. . +1* ....... 1* ....... 1* ....... 1* .......... + 2 x + 1 2 x - 4 4 - 2 x _________ + V 4 - 2 x +@end smallexample +@end group + +Certain types of operations on selections are not allowed. For +example, for an arithmetic function like @kbd{-} no more than one of +the arguments may be a selected sub-formula. (As the above example +shows, the result of the subtraction is spliced back into the argument +which had the selection; if there were more than one selection involved, +this would not be well-defined.) If you try to subtract two selections, +the command will abort with an error message. + +Operations on sub-formulas sometimes leave the formula as a whole +in an ``un-natural'' state. Consider negating the @samp{2 x} term +of our sample formula by selecting it and pressing @kbd{n} +(@code{calc-change-sign}).@refill + +@group +@smallexample + .. . .. . +1* .......... 1* ........... + ......... .......... + . . . 2 x . . . -2 x +@end smallexample +@end group + +Unselecting the sub-formula reveals that the minus sign, which would +normally have cancelled out with the subtraction automatically, has +not been able to do so because the subtraction was not part of the +selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing +any other mathematical operation on the whole formula will cause it +to be simplified. + +@group +@smallexample + 17 y 17 y +1: ----------- 1: ---------- + __________ _________ + V 4 - -2 x V 4 + 2 x +@end smallexample +@end group + +@node Rearranging with Selections, , Operating on Selections, Selecting Subformulas +@subsection Rearranging Formulas using Selections + +@noindent +@kindex j R +@pindex calc-commute-right +The @kbd{j R} (@code{calc-commute-right}) command moves the selected +sub-formula to the right in its surrounding formula. Generally the +selection is one term of a sum or product; the sum or product is +rearranged according to the commutative laws of algebra. + +As with @kbd{j '} and @kbd{j DEL}, the term under the cursor is used +if there is no selection in the current formula. All commands described +in this section share this property. In this example, we place the +cursor on the @samp{a} and type @kbd{j R}, then repeat. + +@smallexample +1: a + b - c 1: b + a - c 1: b - c + a +@end smallexample + +@noindent +Note that in the final step above, the @samp{a} is switched with +the @samp{c} but the signs are adjusted accordingly. When moving +terms of sums and products, @kbd{j R} will never change the +mathematical meaning of the formula. + +The selected term may also be an element of a vector or an argument +of a function. The term is exchanged with the one to its right. +In this case, the ``meaning'' of the vector or function may of +course be drastically changed. + +@smallexample +1: [a, b, c] 1: [b, a, c] 1: [b, c, a] + +1: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a) +@end smallexample + +@kindex j L +@pindex calc-commute-left +The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R} +except that it swaps the selected term with the one to its left. + +With numeric prefix arguments, these commands move the selected +term several steps at a time. It is an error to try to move a +term left or right past the end of its enclosing formula. +With numeric prefix arguments of zero, these commands move the +selected term as far as possible in the given direction. + +@kindex j D +@pindex calc-sel-distribute +The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected +sum or product into the surrounding formula using the distributive +law. For example, in @samp{a * (b - c)} with the @samp{b - c} +selected, the result is @samp{a b - a c}. This also distributes +products or quotients into surrounding powers, and can also do +transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)}, +where @samp{a + b} is the selected term, and @samp{ln(a ^ b)} +to @samp{ln(a) b}, where @samp{a ^ b} is the selected term. + +For multiple-term sums or products, @kbd{j D} takes off one term +at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b} +with the @samp{c - d} selected so that you can type @kbd{j D} +repeatedly to expand completely. The @kbd{j D} command allows a +numeric prefix argument which specifies the maximum number of +times to expand at once; the default is one time only. + +@vindex DistribRules +The @kbd{j D} command is implemented using rewrite rules. +@xref{Selections with Rewrite Rules}. The rules are stored in +the Calc variable @code{DistribRules}. A convenient way to view +these rules is to use @kbd{s e} (@code{calc-edit-variable}) which +displays and edits the stored value of a variable. Press @key{M-# M-#} +to return from editing mode; be careful not to make any actual changes +or else you will affect the behavior of future @kbd{j D} commands! + +To extend @kbd{j D} to handle new cases, just edit @code{DistribRules} +as described above. You can then use the @kbd{s p} command to save +this variable's value permanently for future Calc sessions. +@xref{Operations on Variables}. + +@kindex j M +@pindex calc-sel-merge +@vindex MergeRules +The @kbd{j M} (@code{calc-sel-merge}) command is the complement +of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or +@samp{a c} selected, the result is @samp{a * (b - c)}. Once +again, @kbd{j M} can also merge calls to functions like @code{exp} +and @code{ln}; examine the variable @code{MergeRules} to see all +the relevant rules. + +@kindex j C +@pindex calc-sel-commute +@vindex CommuteRules +The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments +of the selected sum, product, or equation. It always behaves as +if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is +treated as the nested sums @samp{(a + b) + c} by this command. +If you put the cursor on the first @samp{+}, the result is +@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the +result is @samp{c + (a + b)} (which the default simplifications +will rearrange to @samp{(c + a) + b}). The relevant rules are stored +in the variable @code{CommuteRules}. + +You may need to turn default simplifications off (with the @kbd{m O} +command) in order to get the full benefit of @kbd{j C}. For example, +commuting @samp{a - b} produces @samp{-b + a}, but the default +simplifications will ``simplify'' this right back to @samp{a - b} if +you don't turn them off. The same is true of some of the other +manipulations described in this section. + +@kindex j N +@pindex calc-sel-negate +@vindex NegateRules +The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected +term with the negative of that term, then adjusts the surrounding +formula in order to preserve the meaning. For example, given +@samp{exp(a - b)} where @samp{a - b} is selected, the result is +@samp{1 / exp(b - a)}. By contrast, selecting a term and using the +regular @kbd{n} (@code{calc-change-sign}) command negates the +term without adjusting the surroundings, thus changing the meaning +of the formula as a whole. The rules variable is @code{NegateRules}. + +@kindex j & +@pindex calc-sel-invert +@vindex InvertRules +The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N} +except it takes the reciprocal of the selected term. For example, +given @samp{a - ln(b)} with @samp{b} selected, the result is +@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}. + +@kindex j E +@pindex calc-sel-jump-equals +@vindex JumpRules +The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the +selected term from one side of an equation to the other. Given +@samp{a + b = c + d} with @samp{c} selected, the result is +@samp{a + b - c = d}. This command also works if the selected +term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The +relevant rules variable is @code{JumpRules}. + +@kindex j I +@kindex H j I +@pindex calc-sel-isolate +The @kbd{j I} (@code{calc-sel-isolate}) command isolates the +selected term on its side of an equation. It uses the @kbd{a S} +(@code{calc-solve-for}) command to solve the equation, and the +Hyperbolic flag affects it in the same way. @xref{Solving Equations}. +When it applies, @kbd{j I} is often easier to use than @kbd{j E}. +It understands more rules of algebra, and works for inequalities +as well as equations. + +@kindex j * +@kindex j / +@pindex calc-sel-mult-both-sides +@pindex calc-sel-div-both-sides +The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a +formula using algebraic entry, then multiplies both sides of the +selected quotient or equation by that formula. It simplifies each +side with @kbd{a s} (@code{calc-simplify}) before re-forming the +quotient or equation. You can suppress this simplification by +providing any numeric prefix argument. There is also a @kbd{j /} +(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but +dividing instead of multiplying by the factor you enter. + +As a special feature, if the numerator of the quotient is 1, then +the denominator is expanded at the top level using the distributive +law (i.e., using the @kbd{C-u -1 a x} command). Suppose the +formula on the stack is @samp{1 / (sqrt(a) + 1)}, and you wish +to eliminate the square root in the denominator by multiplying both +sides by @samp{sqrt(a) - 1}. Calc's default simplifications would +change the result @samp{(sqrt(a) - 1) / (sqrt(a) - 1) (sqrt(a) + 1)} +right back to the original form by cancellation; Calc expands the +denominator to @samp{sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1} to prevent +this. (You would now want to use an @kbd{a x} command to expand +the rest of the way, whereupon the denominator would cancel out to +the desired form, @samp{a - 1}.) When the numerator is not 1, this +initial expansion is not necessary because Calc's default +simplifications will not notice the potential cancellation. + +If the selection is an inequality, @kbd{j *} and @kbd{j /} will +accept any factor, but will warn unless they can prove the factor +is either positive or negative. (In the latter case the direction +of the inequality will be switched appropriately.) @xref{Declarations}, +for ways to inform Calc that a given variable is positive or +negative. If Calc can't tell for sure what the sign of the factor +will be, it will assume it is positive and display a warning +message. + +For selections that are not quotients, equations, or inequalities, +these commands pull out a multiplicative factor: They divide (or +multiply) by the entered formula, simplify, then multiply (or divide) +back by the formula. + +@kindex j + +@kindex j - +@pindex calc-sel-add-both-sides +@pindex calc-sel-sub-both-sides +The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -} +(@code{calc-sel-sub-both-sides}) commands analogously add to or +subtract from both sides of an equation or inequality. For other +types of selections, they extract an additive factor. A numeric +prefix argument suppresses simplification of the intermediate +results. + +@kindex j U +@pindex calc-sel-unpack +The @kbd{j U} (@code{calc-sel-unpack}) command replaces the +selected function call with its argument. For example, given +@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result +is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you +wanted to change the @code{sin} to @code{cos}, just press @kbd{C} +now to take the cosine of the selected part.) + +@kindex j v +@pindex calc-sel-evaluate +The @kbd{j v} (@code{calc-sel-evaluate}) command performs the +normal default simplifications on the selected sub-formula. +These are the simplifications that are normally done automatically +on all results, but which may have been partially inhibited by +previous selection-related operations, or turned off altogether +by the @kbd{m O} command. This command is just an auto-selecting +version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}). + +With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies +the @kbd{a s} (@code{calc-simplify}) command to the selected +sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v} +applies the @kbd{a e} (@code{calc-simplify-extended}) command. +@xref{Simplifying Formulas}. With a negative prefix argument +it simplifies at the top level only, just as with @kbd{a v}. +Here the ``top'' level refers to the top level of the selected +sub-formula. + +@kindex j " +@pindex calc-sel-expand-formula +The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "} +(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}. + +You can use the @kbd{j r} (@code{calc-rewrite-selection}) command +to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}. + +@node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra +@section Algebraic Manipulation + +@noindent +The commands in this section perform general-purpose algebraic +manipulations. They work on the whole formula at the top of the +stack (unless, of course, you have made a selection in that +formula). + +Many algebra commands prompt for a variable name or formula. If you +answer the prompt with a blank line, the variable or formula is taken +from top-of-stack, and the normal argument for the command is taken +from the second-to-top stack level. + +@kindex a v +@pindex calc-alg-evaluate +The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal +default simplifications on a formula; for example, @samp{a - -b} is +changed to @samp{a + b}. These simplifications are normally done +automatically on all Calc results, so this command is useful only if +you have turned default simplifications off with an @kbd{m O} +command. @xref{Simplification Modes}. + +It is often more convenient to type @kbd{=}, which is like @kbd{a v} +but which also substitutes stored values for variables in the formula. +Use @kbd{a v} if you want the variables to ignore their stored values. + +If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies +as if in algebraic simplification mode. This is equivalent to typing +@kbd{a s}; @pxref{Simplifying Formulas}. If you give a numeric prefix +of 3 or more, it uses extended simplification mode (@kbd{a e}). + +If you give a negative prefix argument @i{-1}, @i{-2}, or @i{-3}, +it simplifies in the corresponding mode but only works on the top-level +function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will +simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas +@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector +@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])} +in no-simplify mode. Using @kbd{a v} will evaluate this all the way to +10; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}. +(@xref{Reducing and Mapping}.) + +@tindex evalv +@tindex evalvn +The @kbd{=} command corresponds to the @code{evalv} function, and +the related @kbd{N} command, which is like @kbd{=} but temporarily +disables symbolic (@kbd{m s}) mode during the evaluation, corresponds +to the @code{evalvn} function. (These commands interpret their prefix +arguments differently than @kbd{a v}; @kbd{=} treats the prefix as +the number of stack elements to evaluate at once, and @kbd{N} treats +it as a temporary different working precision.) + +The @code{evalvn} function can take an alternate working precision +as an optional second argument. This argument can be either an +integer, to set the precision absolutely, or a vector containing +a single integer, to adjust the precision relative to the current +precision. Note that @code{evalvn} with a larger than current +precision will do the calculation at this higher precision, but the +result will as usual be rounded back down to the current precision +afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision +of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)} +will return @samp{9.26535897932e-5} (computing a 25-digit result which +is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])} +will return @samp{9.2654e-5}. + +@kindex a " +@pindex calc-expand-formula +The @kbd{a "} (@code{calc-expand-formula}) command expands functions +into their defining formulas wherever possible. For example, +@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions, +like @code{sin} and @code{gcd}, are not defined by simple formulas +and so are unaffected by this command. One important class of +functions which @emph{can} be expanded is the user-defined functions +created by the @kbd{Z F} command. @xref{Algebraic Definitions}. +Other functions which @kbd{a "} can expand include the probability +distribution functions, most of the financial functions, and the +hyperbolic and inverse hyperbolic functions. A numeric prefix argument +affects @kbd{a "} in the same way as it does @kbd{a v}: A positive +argument expands all functions in the formula and then simplifies in +various ways; a negative argument expands and simplifies only the +top-level function call. + +@kindex a M +@pindex calc-map-equation +@tindex mapeq +The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies +a given function or operator to one or more equations. It is analogous +to @kbd{V M}, which operates on vectors instead of equations. +@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes +@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with +@samp{x = y+1} and @cite{6} on the stack produces @samp{x+6 = y+7}. +With two equations on the stack, @kbd{a M +} would add the lefthand +sides together and the righthand sides together to get the two +respective sides of a new equation. + +Mapping also works on inequalities. Mapping two similar inequalities +produces another inequality of the same type. Mapping an inequality +with an equation produces an inequality of the same type. Mapping a +@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}. +If inequalities with opposite direction (e.g., @samp{<} and @samp{>}) +are mapped, the direction of the second inequality is reversed to +match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2} +reverses the latter to get @samp{2 < a}, which then allows the +combination @samp{a + 2 < b + a}, which the @kbd{a s} command can +then simplify to get @samp{2 < b}. + +Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate +or invert an inequality will reverse the direction of the inequality. +Other adjustments to inequalities are @emph{not} done automatically; +@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even +though this is not true for all values of the variables. + +@kindex H a M +@tindex mapeqp +With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain +mapping operation without reversing the direction of any inequalities. +Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}. +(This change is mathematically incorrect, but perhaps you were +fixing an inequality which was already incorrect.) + +@kindex I a M +@tindex mapeqr +With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses +the direction of the inequality. You might use @kbd{I a M C} to +change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are +working with small positive angles. + +@kindex a b +@pindex calc-substitute +@tindex subst +The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes +all occurrences +of some variable or sub-expression of an expression with a new +sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)} +in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces +@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}. +Note that this is a purely structural substitution; the lone @samp{x} and +the @samp{sin(2 x)} stayed the same because they did not look like +@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for +doing substitutions.@refill + +The @kbd{a b} command normally prompts for two formulas, the old +one and the new one. If you enter a blank line for the first +prompt, all three arguments are taken from the stack (new, then old, +then target expression). If you type an old formula but then enter a +blank line for the new one, the new formula is taken from top-of-stack +and the target from second-to-top. If you answer both prompts, the +target is taken from top-of-stack as usual. + +Note that @kbd{a b} has no understanding of commutativity or +associativity. The pattern @samp{x+y} will not match the formula +@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z} +because the @samp{+} operator is left-associative, so the ``deep +structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U} +(@code{calc-unformatted-language}) mode to see the true structure of +a formula. The rewrite rule mechanism, discussed later, does not have +these limitations. + +As an algebraic function, @code{subst} takes three arguments: +Target expression, old, new. Note that @code{subst} is always +evaluated immediately, even if its arguments are variables, so if +you wish to put a call to @code{subst} onto the stack you must +turn the default simplifications off first (with @kbd{m O}). + +@node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra +@section Simplifying Formulas + +@noindent +@kindex a s +@pindex calc-simplify +@tindex simplify +The @kbd{a s} (@code{calc-simplify}) [@code{simplify}] command applies +various algebraic rules to simplify a formula. This includes rules which +are not part of the default simplifications because they may be too slow +to apply all the time, or may not be desirable all of the time. For +example, non-adjacent terms of sums are combined, as in @samp{a + b + 2 a} +to @samp{b + 3 a}, and some formulas like @samp{sin(arcsin(x))} are +simplified to @samp{x}. + +The sections below describe all the various kinds of algebraic +simplifications Calc provides in full detail. None of Calc's +simplification commands are designed to pull rabbits out of hats; +they simply apply certain specific rules to put formulas into +less redundant or more pleasing forms. Serious algebra in Calc +must be done manually, usually with a combination of selections +and rewrite rules. @xref{Rearranging with Selections}. +@xref{Rewrite Rules}. + +@xref{Simplification Modes}, for commands to control what level of +simplification occurs automatically. Normally only the ``default +simplifications'' occur. + +@menu +* Default Simplifications:: +* Algebraic Simplifications:: +* Unsafe Simplifications:: +* Simplification of Units:: +@end menu + +@node Default Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas +@subsection Default Simplifications + +@noindent +@cindex Default simplifications +This section describes the ``default simplifications,'' those which are +normally applied to all results. For example, if you enter the variable +@cite{x} on the stack twice and push @kbd{+}, Calc's default +simplifications automatically change @cite{x + x} to @cite{2 x}. + +The @kbd{m O} command turns off the default simplifications, so that +@cite{x + x} will remain in this form unless you give an explicit +``simplify'' command like @kbd{=} or @kbd{a v}. @xref{Algebraic +Manipulation}. The @kbd{m D} command turns the default simplifications +back on. + +The most basic default simplification is the evaluation of functions. +For example, @cite{2 + 3} is evaluated to @cite{5}, and @cite{@t{sqrt}(9)} +is evaluated to @cite{3}. Evaluation does not occur if the arguments +to a function are somehow of the wrong type (@cite{@t{tan}([2,3,4])}, +range (@cite{@t{tan}(90)}), or number (@cite{@t{tan}(3,5)}), or if the +function name is not recognized (@cite{@t{f}(5)}), or if ``symbolic'' +mode (@pxref{Symbolic Mode}) prevents evaluation (@cite{@t{sqrt}(2)}). + +Calc simplifies (evaluates) the arguments to a function before it +simplifies the function itself. Thus @cite{@t{sqrt}(5+4)} is +simplified to @cite{@t{sqrt}(9)} before the @code{sqrt} function +itself is applied. There are very few exceptions to this rule: +@code{quote}, @code{lambda}, and @code{condition} (the @code{::} +operator) do not evaluate their arguments, @code{if} (the @code{? :} +operator) does not evaluate all of its arguments, and @code{evalto} +does not evaluate its lefthand argument. + +Most commands apply the default simplifications to all arguments they +take from the stack, perform a particular operation, then simplify +the result before pushing it back on the stack. In the common special +case of regular arithmetic commands like @kbd{+} and @kbd{Q} [@code{sqrt}], +the arguments are simply popped from the stack and collected into a +suitable function call, which is then simplified (the arguments being +simplified first as part of the process, as described above). + +The default simplifications are too numerous to describe completely +here, but this section will describe the ones that apply to the +major arithmetic operators. This list will be rather technical in +nature, and will probably be interesting to you only if you are +a serious user of Calc's algebra facilities. + +@tex +\bigskip +@end tex + +As well as the simplifications described here, if you have stored +any rewrite rules in the variable @code{EvalRules} then these rules +will also be applied before any built-in default simplifications. +@xref{Automatic Rewrites}, for details. + +@tex +\bigskip +@end tex + +And now, on with the default simplifications: + +Arithmetic operators like @kbd{+} and @kbd{*} always take two +arguments in Calc's internal form. Sums and products of three or +more terms are arranged by the associative law of algebra into +a left-associative form for sums, @cite{((a + b) + c) + d}, and +a right-associative form for products, @cite{a * (b * (c * d))}. +Formulas like @cite{(a + b) + (c + d)} are rearranged to +left-associative form, though this rarely matters since Calc's +algebra commands are designed to hide the inner structure of +sums and products as much as possible. Sums and products in +their proper associative form will be written without parentheses +in the examples below. + +Sums and products are @emph{not} rearranged according to the +commutative law (@cite{a + b} to @cite{b + a}) except in a few +special cases described below. Some algebra programs always +rearrange terms into a canonical order, which enables them to +see that @cite{a b + b a} can be simplified to @cite{2 a b}. +Calc assumes you have put the terms into the order you want +and generally leaves that order alone, with the consequence +that formulas like the above will only be simplified if you +explicitly give the @kbd{a s} command. @xref{Algebraic +Simplifications}. + +Differences @cite{a - b} are treated like sums @cite{a + (-b)} +for purposes of simplification; one of the default simplifications +is to rewrite @cite{a + (-b)} or @cite{(-b) + a}, where @cite{-b} +represents a ``negative-looking'' term, into @cite{a - b} form. +``Negative-looking'' means negative numbers, negated formulas like +@cite{-x}, and products or quotients in which either term is +negative-looking. + +Other simplifications involving negation are @cite{-(-x)} to @cite{x}; +@cite{-(a b)} or @cite{-(a/b)} where either @cite{a} or @cite{b} is +negative-looking, simplified by negating that term, or else where +@cite{a} or @cite{b} is any number, by negating that number; +@cite{-(a + b)} to @cite{-a - b}, and @cite{-(b - a)} to @cite{a - b}. +(This, and rewriting @cite{(-b) + a} to @cite{a - b}, are the only +cases where the order of terms in a sum is changed by the default +simplifications.) + +The distributive law is used to simplify sums in some cases: +@cite{a x + b x} to @cite{(a + b) x}, where @cite{a} represents +a number or an implicit 1 or @i{-1} (as in @cite{x} or @cite{-x}) +and similarly for @cite{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or +@kbd{j M} commands to merge sums with non-numeric coefficients +using the distributive law. + +The distributive law is only used for sums of two terms, or +for adjacent terms in a larger sum. Thus @cite{a + b + b + c} +is simplified to @cite{a + 2 b + c}, but @cite{a + b + c + b} +is not simplified. The reason is that comparing all terms of a +sum with one another would require time proportional to the +square of the number of terms; Calc relegates potentially slow +operations like this to commands that have to be invoked +explicitly, like @kbd{a s}. + +Finally, @cite{a + 0} and @cite{0 + a} are simplified to @cite{a}. +A consequence of the above rules is that @cite{0 - a} is simplified +to @cite{-a}. + +@tex +\bigskip +@end tex + +The products @cite{1 a} and @cite{a 1} are simplified to @cite{a}; +@cite{(-1) a} and @cite{a (-1)} are simplified to @cite{-a}; +@cite{0 a} and @cite{a 0} are simplified to @cite{0}, except that +in matrix mode where @cite{a} is not provably scalar the result +is the generic zero matrix @samp{idn(0)}, and that if @cite{a} is +infinite the result is @samp{nan}. + +Also, @cite{(-a) b} and @cite{a (-b)} are simplified to @cite{-(a b)}, +where this occurs for negated formulas but not for regular negative +numbers. + +Products are commuted only to move numbers to the front: +@cite{a b 2} is commuted to @cite{2 a b}. + +The product @cite{a (b + c)} is distributed over the sum only if +@cite{a} and at least one of @cite{b} and @cite{c} are numbers: +@cite{2 (x + 3)} goes to @cite{2 x + 6}. The formula +@cite{(-a) (b - c)}, where @cite{-a} is a negative number, is +rewritten to @cite{a (c - b)}. + +The distributive law of products and powers is used for adjacent +terms of the product: @cite{x^a x^b} goes to @c{$x^{a+b}$} +@cite{x^(a+b)} +where @cite{a} is a number, or an implicit 1 (as in @cite{x}), +or the implicit one-half of @cite{@t{sqrt}(x)}, and similarly for +@cite{b}. The result is written using @samp{sqrt} or @samp{1/sqrt} +if the sum of the powers is @cite{1/2} or @cite{-1/2}, respectively. +If the sum of the powers is zero, the product is simplified to +@cite{1} or to @samp{idn(1)} if matrix mode is enabled. + +The product of a negative power times anything but another negative +power is changed to use division: @c{$x^{-2} y$} +@cite{x^(-2) y} goes to @cite{y / x^2} unless matrix mode is +in effect and neither @cite{x} nor @cite{y} are scalar (in which +case it is considered unsafe to rearrange the order of the terms). + +Finally, @cite{a (b/c)} is rewritten to @cite{(a b)/c}, and also +@cite{(a/b) c} is changed to @cite{(a c)/b} unless in matrix mode. + +@tex +\bigskip +@end tex + +Simplifications for quotients are analogous to those for products. +The quotient @cite{0 / x} is simplified to @cite{0}, with the same +exceptions that were noted for @cite{0 x}. Likewise, @cite{x / 1} +and @cite{x / (-1)} are simplified to @cite{x} and @cite{-x}, +respectively. + +The quotient @cite{x / 0} is left unsimplified or changed to an +infinite quantity, as directed by the current infinite mode. +@xref{Infinite Mode}. + +The expression @c{$a / b^{-c}$} +@cite{a / b^(-c)} is changed to @cite{a b^c}, +where @cite{-c} is any negative-looking power. Also, @cite{1 / b^c} +is changed to @c{$b^{-c}$} +@cite{b^(-c)} for any power @cite{c}. + +Also, @cite{(-a) / b} and @cite{a / (-b)} go to @cite{-(a/b)}; +@cite{(a/b) / c} goes to @cite{a / (b c)}; and @cite{a / (b/c)} +goes to @cite{(a c) / b} unless matrix mode prevents this +rearrangement. Similarly, @cite{a / (b:c)} is simplified to +@cite{(c:b) a} for any fraction @cite{b:c}. + +The distributive law is applied to @cite{(a + b) / c} only if +@cite{c} and at least one of @cite{a} and @cite{b} are numbers. +Quotients of powers and square roots are distributed just as +described for multiplication. + +Quotients of products cancel only in the leading terms of the +numerator and denominator. In other words, @cite{a x b / a y b} +is cancelled to @cite{x b / y b} but not to @cite{x / y}. Once +again this is because full cancellation can be slow; use @kbd{a s} +to cancel all terms of the quotient. + +Quotients of negative-looking values are simplified according +to @cite{(-a) / (-b)} to @cite{a / b}, @cite{(-a) / (b - c)} +to @cite{a / (c - b)}, and @cite{(a - b) / (-c)} to @cite{(b - a) / c}. + +@tex +\bigskip +@end tex + +The formula @cite{x^0} is simplified to @cite{1}, or to @samp{idn(1)} +in matrix mode. The formula @cite{0^x} is simplified to @cite{0} +unless @cite{x} is a negative number or complex number, in which +case the result is an infinity or an unsimplified formula according +to the current infinite mode. Note that @cite{0^0} is an +indeterminate form, as evidenced by the fact that the simplifications +for @cite{x^0} and @cite{0^x} conflict when @cite{x=0}. + +Powers of products or quotients @cite{(a b)^c}, @cite{(a/b)^c} +are distributed to @cite{a^c b^c}, @cite{a^c / b^c} only if @cite{c} +is an integer, or if either @cite{a} or @cite{b} are nonnegative +real numbers. Powers of powers @cite{(a^b)^c} are simplified to +@c{$a^{b c}$} +@cite{a^(b c)} only when @cite{c} is an integer and @cite{b c} also +evaluates to an integer. Without these restrictions these simplifications +would not be safe because of problems with principal values. +(In other words, @c{$((-3)^{1/2})^2$} +@cite{((-3)^1:2)^2} is safe to simplify, but +@c{$((-3)^2)^{1/2}$} +@cite{((-3)^2)^1:2} is not.) @xref{Declarations}, for ways to inform +Calc that your variables satisfy these requirements. + +As a special case of this rule, @cite{@t{sqrt}(x)^n} is simplified to +@c{$x^{n/2}$} +@cite{x^(n/2)} only for even integers @cite{n}. + +If @cite{a} is known to be real, @cite{b} is an even integer, and +@cite{c} is a half- or quarter-integer, then @cite{(a^b)^c} is +simplified to @c{$@t{abs}(a^{b c})$} +@cite{@t{abs}(a^(b c))}. + +Also, @cite{(-a)^b} is simplified to @cite{a^b} if @cite{b} is an +even integer, or to @cite{-(a^b)} if @cite{b} is an odd integer, +for any negative-looking expression @cite{-a}. + +Square roots @cite{@t{sqrt}(x)} generally act like one-half powers +@c{$x^{1:2}$} +@cite{x^1:2} for the purposes of the above-listed simplifications. + +Also, note that @c{$1 / x^{1:2}$} +@cite{1 / x^1:2} is changed to @c{$x^{-1:2}$} +@cite{x^(-1:2)}, +but @cite{1 / @t{sqrt}(x)} is left alone. + +@tex +\bigskip +@end tex + +Generic identity matrices (@pxref{Matrix Mode}) are simplified by the +following rules: @cite{@t{idn}(a) + b} to @cite{a + b} if @cite{b} +is provably scalar, or expanded out if @cite{b} is a matrix; +@cite{@t{idn}(a) + @t{idn}(b)} to @cite{@t{idn}(a + b)}; +@cite{-@t{idn}(a)} to @cite{@t{idn}(-a)}; @cite{a @t{idn}(b)} to +@cite{@t{idn}(a b)} if @cite{a} is provably scalar, or to @cite{a b} +if @cite{a} is provably non-scalar; @cite{@t{idn}(a) @t{idn}(b)} +to @cite{@t{idn}(a b)}; analogous simplifications for quotients +involving @code{idn}; and @cite{@t{idn}(a)^n} to @cite{@t{idn}(a^n)} +where @cite{n} is an integer. + +@tex +\bigskip +@end tex + +The @code{floor} function and other integer truncation functions +vanish if the argument is provably integer-valued, so that +@cite{@t{floor}(@t{round}(x))} simplifies to @cite{@t{round}(x)}. +Also, combinations of @code{float}, @code{floor} and its friends, +and @code{ffloor} and its friends, are simplified in appropriate +ways. @xref{Integer Truncation}. + +The expression @cite{@t{abs}(-x)} changes to @cite{@t{abs}(x)}. +The expression @cite{@t{abs}(@t{abs}(x))} changes to @cite{@t{abs}(x)}; +in fact, @cite{@t{abs}(x)} changes to @cite{x} or @cite{-x} if @cite{x} +is provably nonnegative or nonpositive (@pxref{Declarations}). + +While most functions do not recognize the variable @code{i} as an +imaginary number, the @code{arg} function does handle the two cases +@cite{@t{arg}(@t{i})} and @cite{@t{arg}(-@t{i})} just for convenience. + +The expression @cite{@t{conj}(@t{conj}(x))} simplifies to @cite{x}. +Various other expressions involving @code{conj}, @code{re}, and +@code{im} are simplified, especially if some of the arguments are +provably real or involve the constant @code{i}. For example, +@cite{@t{conj}(a + b i)} is changed to @cite{@t{conj}(a) - @t{conj}(b) i}, +or to @cite{a - b i} if @cite{a} and @cite{b} are known to be real. + +Functions like @code{sin} and @code{arctan} generally don't have +any default simplifications beyond simply evaluating the functions +for suitable numeric arguments and infinity. The @kbd{a s} command +described in the next section does provide some simplifications for +these functions, though. + +One important simplification that does occur is that @cite{@t{ln}(@t{e})} +is simplified to 1, and @cite{@t{ln}(@t{e}^x)} is simplified to @cite{x} +for any @cite{x}. This occurs even if you have stored a different +value in the Calc variable @samp{e}; but this would be a bad idea +in any case if you were also using natural logarithms! + +Among the logical functions, @t{!}@i{(a} @t{<=} @i{b)} changes to +@cite{a > b} and so on. Equations and inequalities where both sides +are either negative-looking or zero are simplified by negating both sides +and reversing the inequality. While it might seem reasonable to simplify +@cite{!!x} to @cite{x}, this would not be valid in general because +@cite{!!2} is 1, not 2. + +Most other Calc functions have few if any default simplifications +defined, aside of course from evaluation when the arguments are +suitable numbers. + +@node Algebraic Simplifications, Unsafe Simplifications, Default Simplifications, Simplifying Formulas +@subsection Algebraic Simplifications + +@noindent +@cindex Algebraic simplifications +The @kbd{a s} command makes simplifications that may be too slow to +do all the time, or that may not be desirable all of the time. +If you find these simplifications are worthwhile, you can type +@kbd{m A} to have Calc apply them automatically. + +This section describes all simplifications that are performed by +the @kbd{a s} command. Note that these occur in addition to the +default simplifications; even if the default simplifications have +been turned off by an @kbd{m O} command, @kbd{a s} will turn them +back on temporarily while it simplifies the formula. + +There is a variable, @code{AlgSimpRules}, in which you can put rewrites +to be applied by @kbd{a s}. Its use is analogous to @code{EvalRules}, +but without the special restrictions. Basically, the simplifier does +@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole +expression being simplified, then it traverses the expression applying +the built-in rules described below. If the result is different from +the original expression, the process repeats with the default +simplifications (including @code{EvalRules}), then @code{AlgSimpRules}, +then the built-in simplifications, and so on. + +@tex +\bigskip +@end tex + +Sums are simplified in two ways. Constant terms are commuted to the +end of the sum, so that @cite{a + 2 + b} changes to @cite{a + b + 2}. +The only exception is that a constant will not be commuted away +from the first position of a difference, i.e., @cite{2 - x} is not +commuted to @cite{-x + 2}. + +Also, terms of sums are combined by the distributive law, as in +@cite{x + y + 2 x} to @cite{y + 3 x}. This always occurs for +adjacent terms, but @kbd{a s} compares all pairs of terms including +non-adjacent ones. + +@tex +\bigskip +@end tex + +Products are sorted into a canonical order using the commutative +law. For example, @cite{b c a} is commuted to @cite{a b c}. +This allows easier comparison of products; for example, the default +simplifications will not change @cite{x y + y x} to @cite{2 x y}, +but @kbd{a s} will; it first rewrites the sum to @cite{x y + x y}, +and then the default simplifications are able to recognize a sum +of identical terms. + +The canonical ordering used to sort terms of products has the +property that real-valued numbers, interval forms and infinities +come first, and are sorted into increasing order. The @kbd{V S} +command uses the same ordering when sorting a vector. + +Sorting of terms of products is inhibited when matrix mode is +turned on; in this case, Calc will never exchange the order of +two terms unless it knows at least one of the terms is a scalar. + +Products of powers are distributed by comparing all pairs of +terms, using the same method that the default simplifications +use for adjacent terms of products. + +Even though sums are not sorted, the commutative law is still +taken into account when terms of a product are being compared. +Thus @cite{(x + y) (y + x)} will be simplified to @cite{(x + y)^2}. +A subtle point is that @cite{(x - y) (y - x)} will @emph{not} +be simplified to @cite{-(x - y)^2}; Calc does not notice that +one term can be written as a constant times the other, even if +that constant is @i{-1}. + +A fraction times any expression, @cite{(a:b) x}, is changed to +a quotient involving integers: @cite{a x / b}. This is not +done for floating-point numbers like @cite{0.5}, however. This +is one reason why you may find it convenient to turn Fraction mode +on while doing algebra; @pxref{Fraction Mode}. + +@tex +\bigskip +@end tex + +Quotients are simplified by comparing all terms in the numerator +with all terms in the denominator for possible cancellation using +the distributive law. For example, @cite{a x^2 b / c x^3 d} will +cancel @cite{x^2} from both sides to get @cite{a b / c x d}. +(The terms in the denominator will then be rearranged to @cite{c d x} +as described above.) If there is any common integer or fractional +factor in the numerator and denominator, it is cancelled out; +for example, @cite{(4 x + 6) / 8 x} simplifies to @cite{(2 x + 3) / 4 x}. + +Non-constant common factors are not found even by @kbd{a s}. To +cancel the factor @cite{a} in @cite{(a x + a) / a^2} you could first +use @kbd{j M} on the product @cite{a x} to Merge the numerator to +@cite{a (1+x)}, which can then be simplified successfully. + +@tex +\bigskip +@end tex + +Integer powers of the variable @code{i} are simplified according +to the identity @cite{i^2 = -1}. If you store a new value other +than the complex number @cite{(0,1)} in @code{i}, this simplification +will no longer occur. This is done by @kbd{a s} instead of by default +in case someone (unwisely) uses the name @code{i} for a variable +unrelated to complex numbers; it would be unfortunate if Calc +quietly and automatically changed this formula for reasons the +user might not have been thinking of. + +Square roots of integer or rational arguments are simplified in +several ways. (Note that these will be left unevaluated only in +Symbolic mode.) First, square integer or rational factors are +pulled out so that @cite{@t{sqrt}(8)} is rewritten as +@c{$2\,\t{sqrt}(2)$} +@cite{2 sqrt(2)}. Conceptually speaking this implies factoring +the argument into primes and moving pairs of primes out of the +square root, but for reasons of efficiency Calc only looks for +primes up to 29. + +Square roots in the denominator of a quotient are moved to the +numerator: @cite{1 / @t{sqrt}(3)} changes to @cite{@t{sqrt}(3) / 3}. +The same effect occurs for the square root of a fraction: +@cite{@t{sqrt}(2:3)} changes to @cite{@t{sqrt}(6) / 3}. + +@tex +\bigskip +@end tex + +The @code{%} (modulo) operator is simplified in several ways +when the modulus @cite{M} is a positive real number. First, if +the argument is of the form @cite{x + n} for some real number +@cite{n}, then @cite{n} is itself reduced modulo @cite{M}. For +example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}. + +If the argument is multiplied by a constant, and this constant +has a common integer divisor with the modulus, then this factor is +cancelled out. For example, @samp{12 x % 15} is changed to +@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15} +is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may +not seem ``simpler,'' they allow Calc to discover useful information +about modulo forms in the presence of declarations. + +If the modulus is 1, then Calc can use @code{int} declarations to +evaluate the expression. For example, the idiom @samp{x % 2} is +often used to check whether a number is odd or even. As described +above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to +@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc +can simplify these to 0 and 1 (respectively) if @code{n} has been +declared to be an integer. + +@tex +\bigskip +@end tex + +Trigonometric functions are simplified in several ways. First, +@cite{@t{sin}(@t{arcsin}(x))} is simplified to @cite{x}, and +similarly for @code{cos} and @code{tan}. If the argument to +@code{sin} is negative-looking, it is simplified to @cite{-@t{sin}(x)}, +and similarly for @code{cos} and @code{tan}. Finally, certain +special values of the argument are recognized; +@pxref{Trigonometric and Hyperbolic Functions}. + +Trigonometric functions of inverses of different trigonometric +functions can also be simplified, as in @cite{@t{sin}(@t{arccos}(x))} +to @cite{@t{sqrt}(1 - x^2)}. + +Hyperbolic functions of their inverses and of negative-looking +arguments are also handled, as are exponentials of inverse +hyperbolic functions. + +No simplifications for inverse trigonometric and hyperbolic +functions are known, except for negative arguments of @code{arcsin}, +@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that +@cite{@t{arcsin}(@t{sin}(x))} can @emph{not} safely change to +@cite{x}, since this only correct within an integer multiple +of @c{$2 \pi$} +@cite{2 pi} radians or 360 degrees. However, +@cite{@t{arcsinh}(@t{sinh}(x))} is simplified to @cite{x} if +@cite{x} is known to be real. + +Several simplifications that apply to logarithms and exponentials +are that @cite{@t{exp}(@t{ln}(x))}, @c{$@t{e}^{\ln(x)}$} +@cite{e^@t{ln}(x)}, and +@c{$10^{{\rm log10}(x)}$} +@cite{10^@t{log10}(x)} all reduce to @cite{x}. +Also, @cite{@t{ln}(@t{exp}(x))}, etc., can reduce to @cite{x} if +@cite{x} is provably real. The form @cite{@t{exp}(x)^y} is simplified +to @cite{@t{exp}(x y)}. If @cite{x} is a suitable multiple of @c{$\pi i$} +@cite{pi i} +(as described above for the trigonometric functions), then @cite{@t{exp}(x)} +or @cite{e^x} will be expanded. Finally, @cite{@t{ln}(x)} is simplified +to a form involving @code{pi} and @code{i} where @cite{x} is provably +negative, positive imaginary, or negative imaginary. + +The error functions @code{erf} and @code{erfc} are simplified when +their arguments are negative-looking or are calls to the @code{conj} +function. + +@tex +\bigskip +@end tex + +Equations and inequalities are simplified by cancelling factors +of products, quotients, or sums on both sides. Inequalities +change sign if a negative multiplicative factor is cancelled. +Non-constant multiplicative factors as in @cite{a b = a c} are +cancelled from equations only if they are provably nonzero (generally +because they were declared so; @pxref{Declarations}). Factors +are cancelled from inequalities only if they are nonzero and their +sign is known. + +Simplification also replaces an equation or inequality with +1 or 0 (``true'' or ``false'') if it can through the use of +declarations. If @cite{x} is declared to be an integer greater +than 5, then @cite{x < 3}, @cite{x = 3}, and @cite{x = 7.5} are +all simplified to 0, but @cite{x > 3} is simplified to 1. +By a similar analysis, @cite{abs(x) >= 0} is simplified to 1, +as is @cite{x^2 >= 0} if @cite{x} is known to be real. + +@node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas +@subsection ``Unsafe'' Simplifications + +@noindent +@cindex Unsafe simplifications +@cindex Extended simplification +@kindex a e +@pindex calc-simplify-extended +@c @mindex esimpl@idots +@tindex esimplify +The @kbd{a e} (@code{calc-simplify-extended}) [@code{esimplify}] command +is like @kbd{a s} +except that it applies some additional simplifications which are not +``safe'' in all cases. Use this only if you know the values in your +formula lie in the restricted ranges for which these simplifications +are valid. The symbolic integrator uses @kbd{a e}; +one effect of this is that the integrator's results must be used with +caution. Where an integral table will often attach conditions like +``for positive @cite{a} only,'' Calc (like most other symbolic +integration programs) will simply produce an unqualified result.@refill + +Because @kbd{a e}'s simplifications are unsafe, it is sometimes better +to type @kbd{C-u -3 a v}, which does extended simplification only +on the top level of the formula without affecting the sub-formulas. +In fact, @kbd{C-u -3 j v} allows you to target extended simplification +to any specific part of a formula. + +The variable @code{ExtSimpRules} contains rewrites to be applied by +the @kbd{a e} command. These are applied in addition to +@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules} +step described above is simply followed by an @kbd{a r ExtSimpRules} step.) + +Following is a complete list of ``unsafe'' simplifications performed +by @kbd{a e}. + +@tex +\bigskip +@end tex + +Inverse trigonometric or hyperbolic functions, called with their +corresponding non-inverse functions as arguments, are simplified +by @kbd{a e}. For example, @cite{@t{arcsin}(@t{sin}(x))} changes +to @cite{x}. Also, @cite{@t{arcsin}(@t{cos}(x))} and +@cite{@t{arccos}(@t{sin}(x))} both change to @cite{@t{pi}/2 - x}. +These simplifications are unsafe because they are valid only for +values of @cite{x} in a certain range; outside that range, values +are folded down to the 360-degree range that the inverse trigonometric +functions always produce. + +Powers of powers @cite{(x^a)^b} are simplified to @c{$x^{a b}$} +@cite{x^(a b)} +for all @cite{a} and @cite{b}. These results will be valid only +in a restricted range of @cite{x}; for example, in @c{$(x^2)^{1:2}$} +@cite{(x^2)^1:2} +the powers cancel to get @cite{x}, which is valid for positive values +of @cite{x} but not for negative or complex values. + +Similarly, @cite{@t{sqrt}(x^a)} and @cite{@t{sqrt}(x)^a} are both +simplified (possibly unsafely) to @c{$x^{a/2}$} +@cite{x^(a/2)}. + +Forms like @cite{@t{sqrt}(1 - @t{sin}(x)^2)} are simplified to, e.g., +@cite{@t{cos}(x)}. Calc has identities of this sort for @code{sin}, +@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}. + +Arguments of square roots are partially factored to look for +squared terms that can be extracted. For example, +@cite{@t{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to @cite{a b @t{sqrt}(a+b)}. + +The simplifications of @cite{@t{ln}(@t{exp}(x))}, @cite{@t{ln}(@t{e}^x)}, +and @cite{@t{log10}(10^x)} to @cite{x} are also unsafe because +of problems with principal values (although these simplifications +are safe if @cite{x} is known to be real). + +Common factors are cancelled from products on both sides of an +equation, even if those factors may be zero: @cite{a x / b x} +to @cite{a / b}. Such factors are never cancelled from +inequalities: Even @kbd{a e} is not bold enough to reduce +@cite{a x < b x} to @cite{a < b} (or @cite{a > b}, depending +on whether you believe @cite{x} is positive or negative). +The @kbd{a M /} command can be used to divide a factor out of +both sides of an inequality. + +@node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas +@subsection Simplification of Units + +@noindent +The simplifications described in this section are applied by the +@kbd{u s} (@code{calc-simplify-units}) command. These are in addition +to the regular @kbd{a s} (but not @kbd{a e}) simplifications described +earlier. @xref{Basic Operations on Units}. + +The variable @code{UnitSimpRules} contains rewrites to be applied by +the @kbd{u s} command. These are applied in addition to @code{EvalRules} +and @code{AlgSimpRules}. + +Scalar mode is automatically put into effect when simplifying units. +@xref{Matrix Mode}. + +Sums @cite{a + b} involving units are simplified by extracting the +units of @cite{a} as if by the @kbd{u x} command (call the result +@cite{u_a}), then simplifying the expression @cite{b / u_a} +using @kbd{u b} and @kbd{u s}. If the result has units then the sum +is inconsistent and is left alone. Otherwise, it is rewritten +in terms of the units @cite{u_a}. + +If units auto-ranging mode is enabled, products or quotients in +which the first argument is a number which is out of range for the +leading unit are modified accordingly. + +When cancelling and combining units in products and quotients, +Calc accounts for unit names that differ only in the prefix letter. +For example, @samp{2 km m} is simplified to @samp{2000 m^2}. +However, compatible but different units like @code{ft} and @code{in} +are not combined in this way. + +Quotients @cite{a / b} are simplified in three additional ways. First, +if @cite{b} is a number or a product beginning with a number, Calc +computes the reciprocal of this number and moves it to the numerator. + +Second, for each pair of unit names from the numerator and denominator +of a quotient, if the units are compatible (e.g., they are both +units of area) then they are replaced by the ratio between those +units. For example, in @samp{3 s in N / kg cm} the units +@samp{in / cm} will be replaced by @cite{2.54}. + +Third, if the units in the quotient exactly cancel out, so that +a @kbd{u b} command on the quotient would produce a dimensionless +number for an answer, then the quotient simplifies to that number. + +For powers and square roots, the ``unsafe'' simplifications +@cite{(a b)^c} to @cite{a^c b^c}, @cite{(a/b)^c} to @cite{a^c / b^c}, +and @cite{(a^b)^c} to @c{$a^{b c}$} +@cite{a^(b c)} are done if the powers are +real numbers. (These are safe in the context of units because +all numbers involved can reasonably be assumed to be real.) + +Also, if a unit name is raised to a fractional power, and the +base units in that unit name all occur to powers which are a +multiple of the denominator of the power, then the unit name +is expanded out into its base units, which can then be simplified +according to the previous paragraph. For example, @samp{acre^1.5} +is simplified by noting that @cite{1.5 = 3:2}, that @samp{acre} +is defined in terms of @samp{m^2}, and that the 2 in the power of +@code{m} is a multiple of 2 in @cite{3:2}. Thus, @code{acre^1.5} is +replaced by approximately @c{$(4046 m^2)^{1.5}$} +@cite{(4046 m^2)^1.5}, which is then +changed to @c{$4046^{1.5} \, (m^2)^{1.5}$} +@cite{4046^1.5 (m^2)^1.5}, then to @cite{257440 m^3}. + +The functions @code{float}, @code{frac}, @code{clean}, @code{abs}, +as well as @code{floor} and the other integer truncation functions, +applied to unit names or products or quotients involving units, are +simplified. For example, @samp{round(1.6 in)} is changed to +@samp{round(1.6) round(in)}; the lefthand term evaluates to 2, +and the righthand term simplifies to @code{in}. + +The functions @code{sin}, @code{cos}, and @code{tan} with arguments +that have angular units like @code{rad} or @code{arcmin} are +simplified by converting to base units (radians), then evaluating +with the angular mode temporarily set to radians. + +@node Polynomials, Calculus, Simplifying Formulas, Algebra +@section Polynomials + +A @dfn{polynomial} is a sum of terms which are coefficients times +various powers of a ``base'' variable. For example, @cite{2 x^2 + 3 x - 4} +is a polynomial in @cite{x}. Some formulas can be considered +polynomials in several different variables: @cite{1 + 2 x + 3 y + 4 x y^2} +is a polynomial in both @cite{x} and @cite{y}. Polynomial coefficients +are often numbers, but they may in general be any formulas not +involving the base variable. + +@kindex a f +@pindex calc-factor +@tindex factor +The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a +polynomial into a product of terms. For example, the polynomial +@cite{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another +example, @cite{a c + b d + b c + a d} is factored into the product +@cite{(a + b) (c + d)}. + +Calc currently has three algorithms for factoring. Formulas which are +linear in several variables, such as the second example above, are +merged according to the distributive law. Formulas which are +polynomials in a single variable, with constant integer or fractional +coefficients, are factored into irreducible linear and/or quadratic +terms. The first example above factors into three linear terms +(@cite{x}, @cite{x+1}, and @cite{x+1} again). Finally, formulas +which do not fit the above criteria are handled by the algebraic +rewrite mechanism. + +Calc's polynomial factorization algorithm works by using the general +root-finding command (@w{@kbd{a P}}) to solve for the roots of the +polynomial. It then looks for roots which are rational numbers +or complex-conjugate pairs, and converts these into linear and +quadratic terms, respectively. Because it uses floating-point +arithmetic, it may be unable to find terms that involve large +integers (whose number of digits approaches the current precision). +Also, irreducible factors of degree higher than quadratic are not +found, and polynomials in more than one variable are not treated. +(A more robust factorization algorithm may be included in a future +version of Calc.) + +@vindex FactorRules +@c @starindex +@tindex thecoefs +@c @starindex +@c @mindex @idots +@tindex thefactors +The rewrite-based factorization method uses rules stored in the variable +@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the +operation of rewrite rules. The default @code{FactorRules} are able +to factor quadratic forms symbolically into two linear terms, +@cite{(a x + b) (c x + d)}. You can edit these rules to include other +cases if you wish. To use the rules, Calc builds the formula +@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial +base variable and @code{a}, @code{b}, etc., are polynomial coefficients +(which may be numbers or formulas). The constant term is written first, +i.e., in the @code{a} position. When the rules complete, they should have +changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])} +where each @code{fi} should be a factored term, e.g., @samp{x - ai}. +Calc then multiplies these terms together to get the complete +factored form of the polynomial. If the rules do not change the +@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the +polynomial alone on the assumption that it is unfactorable. (Note that +the function names @code{thecoefs} and @code{thefactors} are used only +as placeholders; there are no actual Calc functions by those names.) + +@kindex H a f +@tindex factors +The @kbd{H a f} [@code{factors}] command also factors a polynomial, +but it returns a list of factors instead of an expression which is the +product of the factors. Each factor is represented by a sub-vector +of the factor, and the power with which it appears. For example, +@cite{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @cite{(x + 7) x^2 (x - 3)^2} +in @kbd{a f}, or to @cite{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}. +If there is an overall numeric factor, it always comes first in the list. +The functions @code{factor} and @code{factors} allow a second argument +when written in algebraic form; @samp{factor(x,v)} factors @cite{x} with +respect to the specific variable @cite{v}. The default is to factor with +respect to all the variables that appear in @cite{x}. + +@kindex a c +@pindex calc-collect +@tindex collect +The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a +formula as a +polynomial in a given variable, ordered in decreasing powers of that +variable. For example, given @cite{1 + 2 x + 3 y + 4 x y^2} on +the stack, @kbd{a c x} would produce @cite{(2 + 4 y^2) x + (1 + 3 y)}, +and @kbd{a c y} would produce @cite{(4 x) y^2 + 3 y + (1 + 2 x)}. +The polynomial will be expanded out using the distributive law as +necessary: Collecting @cite{x} in @cite{(x - 1)^3} produces +@cite{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @cite{x} will +not be expanded. + +The ``variable'' you specify at the prompt can actually be any +expression: @kbd{a c ln(x+1)} will collect together all terms multiplied +by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears +in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will +treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants. + +@kindex a x +@pindex calc-expand +@tindex expand +The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an +expression by applying the distributive law everywhere. It applies to +products, quotients, and powers involving sums. By default, it fully +distributes all parts of the expression. With a numeric prefix argument, +the distributive law is applied only the specified number of times, then +the partially expanded expression is left on the stack. + +The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use +@kbd{a x} if you want to expand all products of sums in your formula. +Use @kbd{j D} if you want to expand a particular specified term of +the formula. There is an exactly analogous correspondence between +@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands +also know many other kinds of expansions, such as +@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f} +do not do.) + +Calc's automatic simplifications will sometimes reverse a partial +expansion. For example, the first step in expanding @cite{(x+1)^3} is +to write @cite{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries +to put this formula onto the stack, though, Calc will automatically +simplify it back to @cite{(x+1)^3} form. The solution is to turn +simplification off first (@pxref{Simplification Modes}), or to run +@kbd{a x} without a numeric prefix argument so that it expands all +the way in one step. + +@kindex a a +@pindex calc-apart +@tindex apart +The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a +rational function by partial fractions. A rational function is the +quotient of two polynomials; @code{apart} pulls this apart into a +sum of rational functions with simple denominators. In algebraic +notation, the @code{apart} function allows a second argument that +specifies which variable to use as the ``base''; by default, Calc +chooses the base variable automatically. + +@kindex a n +@pindex calc-normalize-rat +@tindex nrat +The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command +attempts to arrange a formula into a quotient of two polynomials. +For example, given @cite{1 + (a + b/c) / d}, the result would be +@cite{(b + a c + c d) / c d}. The quotient is reduced, so that +@kbd{a n} will simplify @cite{(x^2 + 2x + 1) / (x^2 - 1)} by dividing +out the common factor @cite{x + 1}, yielding @cite{(x + 1) / (x - 1)}. + +@kindex a \ +@pindex calc-poly-div +@tindex pdiv +The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides +two polynomials @cite{u} and @cite{v}, yielding a new polynomial +@cite{q}. If several variables occur in the inputs, the inputs are +considered multivariate polynomials. (Calc divides by the variable +with the largest power in @cite{u} first, or, in the case of equal +powers, chooses the variables in alphabetical order.) For example, +dividing @cite{x^2 + 3 x + 2} by @cite{x + 2} yields @cite{x + 1}. +The remainder from the division, if any, is reported at the bottom +of the screen and is also placed in the Trail along with the quotient. + +Using @code{pdiv} in algebraic notation, you can specify the particular +variable to be used as the base: `@t{pdiv(}@i{a}@t{,}@i{b}@t{,}@i{x}@t{)}'. +If @code{pdiv} is given only two arguments (as is always the case with +the @kbd{a \} command), then it does a multivariate division as outlined +above. + +@kindex a % +@pindex calc-poly-rem +@tindex prem +The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides +two polynomials and keeps the remainder @cite{r}. The quotient +@cite{q} is discarded. For any formulas @cite{a} and @cite{b}, the +results of @kbd{a \} and @kbd{a %} satisfy @cite{a = q b + r}. +(This is analogous to plain @kbd{\} and @kbd{%}, which compute the +integer quotient and remainder from dividing two numbers.) + +@kindex a / +@kindex H a / +@pindex calc-poly-div-rem +@tindex pdivrem +@tindex pdivide +The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command +divides two polynomials and reports both the quotient and the +remainder as a vector @cite{[q, r]}. The @kbd{H a /} [@code{pdivide}] +command divides two polynomials and constructs the formula +@cite{q + r/b} on the stack. (Naturally if the remainder is zero, +this will immediately simplify to @cite{q}.) + +@kindex a g +@pindex calc-poly-gcd +@tindex pgcd +The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes +the greatest common divisor of two polynomials. (The GCD actually +is unique only to within a constant multiplier; Calc attempts to +choose a GCD which will be unsurprising.) For example, the @kbd{a n} +command uses @kbd{a g} to take the GCD of the numerator and denominator +of a quotient, then divides each by the result using @kbd{a \}. (The +definition of GCD ensures that this division can take place without +leaving a remainder.) + +While the polynomials used in operations like @kbd{a /} and @kbd{a g} +often have integer coefficients, this is not required. Calc can also +deal with polynomials over the rationals or floating-point reals. +Polynomials with modulo-form coefficients are also useful in many +applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc +automatically transforms this into a polynomial over the field of +integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}. + +Congratulations and thanks go to Ove Ewerlid +(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the +polynomial routines used in the above commands. + +@xref{Decomposing Polynomials}, for several useful functions for +extracting the individual coefficients of a polynomial. + +@node Calculus, Solving Equations, Polynomials, Algebra +@section Calculus + +@noindent +The following calculus commands do not automatically simplify their +inputs or outputs using @code{calc-simplify}. You may find it helps +to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help +to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most +readable way. + +@menu +* Differentiation:: +* Integration:: +* Customizing the Integrator:: +* Numerical Integration:: +* Taylor Series:: +@end menu + +@node Differentiation, Integration, Calculus, Calculus +@subsection Differentiation + +@noindent +@kindex a d +@kindex H a d +@pindex calc-derivative +@tindex deriv +@tindex tderiv +The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes +the derivative of the expression on the top of the stack with respect to +some variable, which it will prompt you to enter. Normally, variables +in the formula other than the specified differentiation variable are +considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With +the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used +instead, in which derivatives of variables are not reduced to zero +unless those variables are known to be ``constant,'' i.e., independent +of any other variables. (The built-in special variables like @code{pi} +are considered constant, as are variables that have been declared +@code{const}; @pxref{Declarations}.) + +With a numeric prefix argument @var{n}, this command computes the +@var{n}th derivative. + +When working with trigonometric functions, it is best to switch to +radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)} +in degrees is @samp{(pi/180) cos(x)}, probably not the expected +answer! + +If you use the @code{deriv} function directly in an algebraic formula, +you can write @samp{deriv(f,x,x0)} which represents the derivative +of @cite{f} with respect to @cite{x}, evaluated at the point @c{$x=x_0$} +@cite{x=x0}. + +If the formula being differentiated contains functions which Calc does +not know, the derivatives of those functions are produced by adding +primes (apostrophe characters). For example, @samp{deriv(f(2x), x)} +produces @samp{2 f'(2 x)}, where the function @code{f'} represents the +derivative of @code{f}. + +For functions you have defined with the @kbd{Z F} command, Calc expands +the functions according to their defining formulas unless you have +also defined @code{f'} suitably. For example, suppose we define +@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate +the formula @samp{sinc(2 x)}, the formula will be expanded to +@samp{sin(2 x) / (2 x)} and differentiated. However, if we also +define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the +result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}. + +For multi-argument functions @samp{f(x,y,z)}, the derivative with respect +to the first argument is written @samp{f'(x,y,z)}; derivatives with +respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}. +Various higher-order derivatives can be formed in the obvious way, e.g., +@samp{f'@var{}'(x)} (the second derivative of @code{f}) or +@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each +argument once).@refill + +@node Integration, Customizing the Integrator, Differentiation, Calculus +@subsection Integration + +@noindent +@kindex a i +@pindex calc-integral +@tindex integ +The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the +indefinite integral of the expression on the top of the stack with +respect to a variable. The integrator is not guaranteed to work for +all integrable functions, but it is able to integrate several large +classes of formulas. In particular, any polynomial or rational function +(a polynomial divided by a polynomial) is acceptable. (Rational functions +don't have to be in explicit quotient form, however; @c{$x/(1+x^{-2})$} +@cite{x/(1+x^-2)} +is not strictly a quotient of polynomials, but it is equivalent to +@cite{x^3/(x^2+1)}, which is.) Also, square roots of terms involving +@cite{x} and @cite{x^2} may appear in rational functions being +integrated. Finally, rational functions involving trigonometric or +hyperbolic functions can be integrated. + +@ifinfo +If you use the @code{integ} function directly in an algebraic formula, +you can also write @samp{integ(f,x,v)} which expresses the resulting +indefinite integral in terms of variable @code{v} instead of @code{x}. +With four arguments, @samp{integ(f(x),x,a,b)} represents a definite +integral from @code{a} to @code{b}. +@end ifinfo +@tex +If you use the @code{integ} function directly in an algebraic formula, +you can also write @samp{integ(f,x,v)} which expresses the resulting +indefinite integral in terms of variable @code{v} instead of @code{x}. +With four arguments, @samp{integ(f(x),x,a,b)} represents a definite +integral $\int_a^b f(x) \, dx$. +@end tex + +Please note that the current implementation of Calc's integrator sometimes +produces results that are significantly more complex than they need to +be. For example, the integral Calc finds for @c{$1/(x+\sqrt{x^2+1})$} +@cite{1/(x+sqrt(x^2+1))} +is several times more complicated than the answer Mathematica +returns for the same input, although the two forms are numerically +equivalent. Also, any indefinite integral should be considered to have +an arbitrary constant of integration added to it, although Calc does not +write an explicit constant of integration in its result. For example, +Calc's solution for @c{$1/(1+\tan x)$} +@cite{1/(1+tan(x))} differs from the solution given +in the @emph{CRC Math Tables} by a constant factor of @c{$\pi i / 2$} +@cite{pi i / 2}, +due to a different choice of constant of integration. + +The Calculator remembers all the integrals it has done. If conditions +change in a way that would invalidate the old integrals, say, a switch +from degrees to radians mode, then they will be thrown out. If you +suspect this is not happening when it should, use the +@code{calc-flush-caches} command; @pxref{Caches}. + +@vindex IntegLimit +Calc normally will pursue integration by substitution or integration by +parts up to 3 nested times before abandoning an approach as fruitless. +If the integrator is taking too long, you can lower this limit by storing +a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I} +command is a convenient way to edit @code{IntegLimit}.) If this variable +has no stored value or does not contain a nonnegative integer, a limit +of 3 is used. The lower this limit is, the greater the chance that Calc +will be unable to integrate a function it could otherwise handle. Raising +this limit allows the Calculator to solve more integrals, though the time +it takes may grow exponentially. You can monitor the integrator's actions +by creating an Emacs buffer called @code{*Trace*}. If such a buffer +exists, the @kbd{a i} command will write a log of its actions there. + +If you want to manipulate integrals in a purely symbolic way, you can +set the integration nesting limit to 0 to prevent all but fast +table-lookup solutions of integrals. You might then wish to define +rewrite rules for integration by parts, various kinds of substitutions, +and so on. @xref{Rewrite Rules}. + +@node Customizing the Integrator, Numerical Integration, Integration, Calculus +@subsection Customizing the Integrator + +@noindent +@vindex IntegRules +Calc has two built-in rewrite rules called @code{IntegRules} and +@code{IntegAfterRules} which you can edit to define new integration +methods. @xref{Rewrite Rules}. At each step of the integration process, +Calc wraps the current integrand in a call to the fictitious function +@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the +integrand and @var{var} is the integration variable. If your rules +rewrite this to be a plain formula (not a call to @code{integtry}), then +Calc will use this formula as the integral of @var{expr}. For example, +the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to +integrate a function @code{mysin} that acts like the sine function. +Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y} +will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has +automatically made various transformations on the integral to allow it +to use your rule; integral tables generally give rules for +@samp{mysin(a x + b)}, but you don't need to use this much generality +in your @code{IntegRules}. + +@cindex Exponential integral Ei(x) +@c @starindex +@tindex Ei +As a more serious example, the expression @samp{exp(x)/x} cannot be +integrated in terms of the standard functions, so the ``exponential +integral'' function @c{${\rm Ei}(x)$} +@cite{Ei(x)} was invented to describe it. +We can get Calc to do this integral in terms of a made-up @code{Ei} +function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]} +to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack +and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will +work with Calc's various built-in integration methods (such as +integration by substitution) to solve a variety of other problems +involving @code{Ei}: For example, now Calc will also be able to +integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))} +and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively). + +Your rule may do further integration by calling @code{integ}. For +example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc +to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}. +Note that @code{integ} was called with only one argument. This notation +is allowed only within @code{IntegRules}; it means ``integrate this +with respect to the same integration variable.'' If Calc is unable +to integrate @code{u}, the integration that invoked @code{IntegRules} +also fails. Thus integrating @samp{twice(f(x))} fails, returning the +unevaluated integral @samp{integ(twice(f(x)), x)}. It is still legal +to call @code{integ} with two or more arguments, however; in this case, +if @code{u} is not integrable, @code{twice} itself will still be +integrated: If the above rule is changed to @samp{... := twice(integ(u,x))}, +then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}. + +If a rule instead produces the formula @samp{integsubst(@var{sexpr}, +@var{svar})}, either replacing the top-level @code{integtry} call or +nested anywhere inside the expression, then Calc will apply the +substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to +integrate the original @var{expr}. For example, the rule +@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds +a square root in the integrand, it should attempt the substitution +@samp{u = sqrt(x)}. (This particular rule is unnecessary because +Calc always tries ``obvious'' substitutions where @var{sexpr} actually +appears in the integrand.) The variable @var{svar} may be the same +as the @var{var} that appeared in the call to @code{integtry}, but +it need not be. + +When integrating according to an @code{integsubst}, Calc uses the +equation solver to find the inverse of @var{sexpr} (if the integrand +refers to @var{var} anywhere except in subexpressions that exactly +match @var{sexpr}). It uses the differentiator to find the derivative +of @var{sexpr} and/or its inverse (it has two methods that use one +derivative or the other). You can also specify these items by adding +extra arguments to the @code{integsubst} your rules construct; the +general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv}, +@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still +written as a function of @var{svar}), and @var{sprime} is the +derivative of @var{sexpr} with respect to @var{svar}. If you don't +specify these things, and Calc is not able to work them out on its +own with the information it knows, then your substitution rule will +work only in very specific, simple cases. + +Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules}; +in other words, Calc stops rewriting as soon as any rule in your rule +set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)} +example above would keep on adding layers of @code{integsubst} calls +forever!) + +@vindex IntegSimpRules +Another set of rules, stored in @code{IntegSimpRules}, are applied +every time the integrator uses @kbd{a s} to simplify an intermediate +result. For example, putting the rule @samp{twice(x) := 2 x} into +@code{IntegSimpRules} would tell Calc to convert the @code{twice} +function into a form it knows whenever integration is attempted. + +One more way to influence the integrator is to define a function with +the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's +integrator automatically expands such functions according to their +defining formulas, even if you originally asked for the function to +be left unevaluated for symbolic arguments. (Certain other Calc +systems, such as the differentiator and the equation solver, also +do this.) + +@vindex IntegAfterRules +Sometimes Calc is able to find a solution to your integral, but it +expresses the result in a way that is unnecessarily complicated. If +this happens, you can either use @code{integsubst} as described +above to try to hint at a more direct path to the desired result, or +you can use @code{IntegAfterRules}. This is an extra rule set that +runs after the main integrator returns its result; basically, Calc does +an @kbd{a r IntegAfterRules} on the result before showing it to you. +(It also does an @kbd{a s}, without @code{IntegSimpRules}, after that +to further simplify the result.) For example, Calc's integrator +sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)}; +the default @code{IntegAfterRules} rewrite this into the more readable +form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules}, +@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number +of times until no further changes are possible. Rewriting by +@code{IntegAfterRules} occurs only after the main integrator has +finished, not at every step as for @code{IntegRules} and +@code{IntegSimpRules}. + +@node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus +@subsection Numerical Integration + +@noindent +@kindex a I +@pindex calc-num-integral +@tindex ninteg +If you want a purely numerical answer to an integration problem, you can +use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This +command prompts for an integration variable, a lower limit, and an +upper limit. Except for the integration variable, all other variables +that appear in the integrand formula must have stored values. (A stored +value, if any, for the integration variable itself is ignored.) + +Numerical integration works by evaluating your formula at many points in +the specified interval. Calc uses an ``open Romberg'' method; this means +that it does not evaluate the formula actually at the endpoints (so that +it is safe to integrate @samp{sin(x)/x} from zero, for example). Also, +the Romberg method works especially well when the function being +integrated is fairly smooth. If the function is not smooth, Calc will +have to evaluate it at quite a few points before it can accurately +determine the value of the integral. + +Integration is much faster when the current precision is small. It is +best to set the precision to the smallest acceptable number of digits +before you use @kbd{a I}. If Calc appears to be taking too long, press +@kbd{C-g} to halt it and try a lower precision. If Calc still appears +to need hundreds of evaluations, check to make sure your function is +well-behaved in the specified interval. + +It is possible for the lower integration limit to be @samp{-inf} (minus +infinity). Likewise, the upper limit may be plus infinity. Calc +internally transforms the integral into an equivalent one with finite +limits. However, integration to or across singularities is not supported: +The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found +by Calc's symbolic integrator, for example), but @kbd{a I} will fail +because the integrand goes to infinity at one of the endpoints. + +@node Taylor Series, , Numerical Integration, Calculus +@subsection Taylor Series + +@noindent +@kindex a t +@pindex calc-taylor +@tindex taylor +The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a +power series expansion or Taylor series of a function. You specify the +variable and the desired number of terms. You may give an expression of +the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead +of just a variable to produce a Taylor expansion about the point @var{a}. +You may specify the number of terms with a numeric prefix argument; +otherwise the command will prompt you for the number of terms. Note that +many series expansions have coefficients of zero for some terms, so you +may appear to get fewer terms than you asked for.@refill + +If the @kbd{a i} command is unable to find a symbolic integral for a +function, you can get an approximation by integrating the function's +Taylor series. + +@node Solving Equations, Numerical Solutions, Calculus, Algebra +@section Solving Equations + +@noindent +@kindex a S +@pindex calc-solve-for +@tindex solve +@cindex Equations, solving +@cindex Solving equations +The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges +an equation to solve for a specific variable. An equation is an +expression of the form @cite{L = R}. For example, the command @kbd{a S x} +will rearrange @cite{y = 3x + 6} to the form, @cite{x = y/3 - 2}. If the +input is not an equation, it is treated like an equation of the +form @cite{X = 0}. + +This command also works for inequalities, as in @cite{y < 3x + 6}. +Some inequalities cannot be solved where the analogous equation could +be; for example, solving @c{$a < b \, c$} +@cite{a < b c} for @cite{b} is impossible +without knowing the sign of @cite{c}. In this case, @kbd{a S} will +produce the result @c{$b \mathbin{\hbox{\code{!=}}} a/c$} +@cite{b != a/c} (using the not-equal-to operator) +to signify that the direction of the inequality is now unknown. The +inequality @c{$a \le b \, c$} +@cite{a <= b c} is not even partially solved. +@xref{Declarations}, for a way to tell Calc that the signs of the +variables in a formula are in fact known. + +Two useful commands for working with the result of @kbd{a S} are +@kbd{a .} (@pxref{Logical Operations}), which converts @cite{x = y/3 - 2} +to @cite{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates +another formula with @cite{x} set equal to @cite{y/3 - 2}. + +@menu +* Multiple Solutions:: +* Solving Systems of Equations:: +* Decomposing Polynomials:: +@end menu + +@node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations +@subsection Multiple Solutions + +@noindent +@kindex H a S +@tindex fsolve +Some equations have more than one solution. The Hyperbolic flag +(@code{H a S}) [@code{fsolve}] tells the solver to report the fully +general family of solutions. It will invent variables @code{n1}, +@code{n2}, @dots{}, which represent independent arbitrary integers, and +@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary +signs (either @i{+1} or @i{-1}). If you don't use the Hyperbolic +flag, Calc will use zero in place of all arbitrary integers, and plus +one in place of all arbitrary signs. Note that variables like @code{n1} +and @code{s1} are not given any special interpretation in Calc except by +the equation solver itself. As usual, you can use the @w{@kbd{s l}} +(@code{calc-let}) command to obtain solutions for various actual values +of these variables. + +For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to +get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the +equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to +think about it is that the square-root operation is really a +two-valued function; since every Calc function must return a +single result, @code{sqrt} chooses to return the positive result. +Then @kbd{H a S} doctors this result using @code{s1} to indicate +the full set of possible values of the mathematical square-root. + +There is a similar phenomenon going the other direction: Suppose +we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides +to get @samp{y = x^2}. This is correct, except that it introduces +some dubious solutions. Consider solving @samp{sqrt(y) = -3}: +Calc will report @cite{y = 9} as a valid solution, which is true +in the mathematical sense of square-root, but false (there is no +solution) for the actual Calc positive-valued @code{sqrt}. This +happens for both @kbd{a S} and @kbd{H a S}. + +@cindex @code{GenCount} variable +@vindex GenCount +@c @starindex +@tindex an +@c @starindex +@tindex as +If you store a positive integer in the Calc variable @code{GenCount}, +then Calc will generate formulas of the form @samp{as(@var{n})} for +arbitrary signs, and @samp{an(@var{n})} for arbitrary integers, +where @var{n} represents successive values taken by incrementing +@code{GenCount} by one. While the normal arbitrary sign and +integer symbols start over at @code{s1} and @code{n1} with each +new Calc command, the @code{GenCount} approach will give each +arbitrary value a name that is unique throughout the entire Calc +session. Also, the arbitrary values are function calls instead +of variables, which is advantageous in some cases. For example, +you can make a rewrite rule that recognizes all arbitrary signs +using a pattern like @samp{as(n)}. The @kbd{s l} command only works +on variables, but you can use the @kbd{a b} (@code{calc-substitute}) +command to substitute actual values for function calls like @samp{as(3)}. + +The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient +way to create or edit this variable. Press @kbd{M-# M-#} to finish. + +If you have not stored a value in @code{GenCount}, or if the value +in that variable is not a positive integer, the regular +@code{s1}/@code{n1} notation is used. + +@kindex I a S +@kindex H I a S +@tindex finv +@tindex ffinv +With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression +on top of the stack as a function of the specified variable and solves +to find the inverse function, written in terms of the same variable. +For example, @kbd{I a S x} inverts @cite{2x + 6} to @cite{x/2 - 3}. +You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a +fully general inverse, as described above. + +@kindex a P +@pindex calc-poly-roots +@tindex roots +Some equations, specifically polynomials, have a known, finite number +of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}] +command uses @kbd{H a S} to solve an equation in general form, then, for +all arbitrary-sign variables like @code{s1}, and all arbitrary-integer +variables like @code{n1} for which @code{n1} only usefully varies over +a finite range, it expands these variables out to all their possible +values. The results are collected into a vector, which is returned. +For example, @samp{roots(x^4 = 1, x)} returns the four solutions +@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree +polynomial will always have @var{n} roots on the complex plane. +(If you have given a @code{real} declaration for the solution +variable, then only the real-valued solutions, if any, will be +reported; @pxref{Declarations}.) + +Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver +symbolic solutions if the polynomial has symbolic coefficients. Also +note that Calc's solver is not able to get exact symbolic solutions +to all polynomials. Polynomials containing powers up to @cite{x^4} +can always be solved exactly; polynomials of higher degree sometimes +can be: @cite{x^6 + x^3 + 1} is converted to @cite{(x^3)^2 + (x^3) + 1}, +which can be solved for @cite{x^3} using the quadratic equation, and then +for @cite{x} by taking cube roots. But in many cases, like +@cite{x^6 + x + 1}, Calc does not know how to rewrite the polynomial +into a form it can solve. The @kbd{a P} command can still deliver a +list of numerical roots, however, provided that symbolic mode (@kbd{m s}) +is not turned on. (If you work with symbolic mode on, recall that the +@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the +formula on the stack with symbolic mode temporarily off.) Naturally, +@kbd{a P} can only provide numerical roots if the polynomial coefficents +are all numbers (real or complex). + +@node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations +@subsection Solving Systems of Equations + +@noindent +@cindex Systems of equations, symbolic +You can also use the commands described above to solve systems of +simultaneous equations. Just create a vector of equations, then +specify a vector of variables for which to solve. (You can omit +the surrounding brackets when entering the vector of variables +at the prompt.) + +For example, putting @samp{[x + y = a, x - y = b]} on the stack +and typing @kbd{a S x,y @key{RET}} produces the vector of solutions +@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will +have the same length as the variables vector, and the variables +will be listed in the same order there. Note that the solutions +are not always simplified as far as possible; the solution for +@cite{x} here could be improved by an application of the @kbd{a n} +command. + +Calc's algorithm works by trying to eliminate one variable at a +time by solving one of the equations for that variable and then +substituting into the other equations. Calc will try all the +possibilities, but you can speed things up by noting that Calc +first tries to eliminate the first variable with the first +equation, then the second variable with the second equation, +and so on. It also helps to put the simpler (e.g., more linear) +equations toward the front of the list. Calc's algorithm will +solve any system of linear equations, and also many kinds of +nonlinear systems. + +@c @starindex +@tindex elim +Normally there will be as many variables as equations. If you +give fewer variables than equations (an ``over-determined'' system +of equations), Calc will find a partial solution. For example, +typing @kbd{a S y @key{RET}} with the above system of equations +would produce @samp{[y = a - x]}. There are now several ways to +express this solution in terms of the original variables; Calc uses +the first one that it finds. You can control the choice by adding +variable specifiers of the form @samp{elim(@var{v})} to the +variables list. This says that @var{v} should be eliminated from +the equations; the variable will not appear at all in the solution. +For example, typing @kbd{a S y,elim(x)} would yield +@samp{[y = a - (b+a)/2]}. + +If the variables list contains only @code{elim} specifiers, +Calc simply eliminates those variables from the equations +and then returns the resulting set of equations. For example, +@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable +eliminated will reduce the number of equations in the system +by one. + +Again, @kbd{a S} gives you one solution to the system of +equations. If there are several solutions, you can use @kbd{H a S} +to get a general family of solutions, or, if there is a finite +number of solutions, you can use @kbd{a P} to get a list. (In +the latter case, the result will take the form of a matrix where +the rows are different solutions and the columns correspond to the +variables you requested.) + +Another way to deal with certain kinds of overdetermined systems of +equations is the @kbd{a F} command, which does least-squares fitting +to satisfy the equations. @xref{Curve Fitting}. + +@node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations +@subsection Decomposing Polynomials + +@noindent +@c @starindex +@tindex poly +The @code{poly} function takes a polynomial and a variable as +arguments, and returns a vector of polynomial coefficients (constant +coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns +@cite{[0, 2, 0, 1]}. If the input is not a polynomial in @cite{x}, +the call to @code{poly} is left in symbolic form. If the input does +not involve the variable @cite{x}, the input is returned in a list +of length one, representing a polynomial with only a constant +coefficient. The call @samp{poly(x, x)} returns the vector @cite{[0, 1]}. +The last element of the returned vector is guaranteed to be nonzero; +note that @samp{poly(0, x)} returns the empty vector @cite{[]}. +Note also that @cite{x} may actually be any formula; for example, +@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @cite{[3, -1, 1]}. + +@cindex Coefficients of polynomial +@cindex Degree of polynomial +To get the @cite{x^k} coefficient of polynomial @cite{p}, use +@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @cite{p}, +use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)} +returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)} +gives the @cite{x^2} coefficient of this polynomial, 6. + +@c @starindex +@tindex gpoly +One important feature of the solver is its ability to recognize +formulas which are ``essentially'' polynomials. This ability is +made available to the user through the @code{gpoly} function, which +is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}. +If @var{expr} is a polynomial in some term which includes @var{var}, then +this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]} +where @var{x} is the term that depends on @var{var}, @var{c} is a +vector of polynomial coefficients (like the one returned by @code{poly}), +and @var{a} is a multiplier which is usually 1. Basically, +@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} + +@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is +guaranteed to be non-zero, and @var{c} will not equal @samp{[1]} +(i.e., the trivial decomposition @var{expr} = @var{x} is not +considered a polynomial). One side effect is that @samp{gpoly(x, x)} +and @samp{gpoly(6, x)}, both of which might be expected to recognize +their arguments as polynomials, will not because the decomposition +is considered trivial. + +For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]}, +since the expanded form of this polynomial is @cite{4 - 4 x + x^2}. + +The term @var{x} may itself be a polynomial in @var{var}. This is +done to reduce the size of the @var{c} vector. For example, +@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]}, +since a quadratic polynomial in @cite{x^2} is easier to solve than +a quartic polynomial in @cite{x}. + +A few more examples of the kinds of polynomials @code{gpoly} can +discover: + +@smallexample +sin(x) - 1 [sin(x), [-1, 1], 1] +x + 1/x - 1 [x, [1, -1, 1], 1/x] +x + 1/x [x^2, [1, 1], 1/x] +x^3 + 2 x [x^2, [2, 1], x] +x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2] +x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1] +(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x] +@end smallexample + +The @code{poly} and @code{gpoly} functions accept a third integer argument +which specifies the largest degree of polynomial that is acceptable. +If this is @cite{n}, then only @var{c} vectors of length @cite{n+1} +or less will be returned. Otherwise, the @code{poly} or @code{gpoly} +call will remain in symbolic form. For example, the equation solver +can handle quartics and smaller polynomials, so it calls +@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr} +can be treated by its linear, quadratic, cubic, or quartic formulas. + +@c @starindex +@tindex pdeg +The @code{pdeg} function computes the degree of a polynomial; +@samp{pdeg(p,x)} is the highest power of @code{x} that appears in +@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is +much more efficient. If @code{p} is constant with respect to @code{x}, +then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x} +(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated. +It is possible to omit the second argument @code{x}, in which case +@samp{pdeg(p)} returns the highest total degree of any term of the +polynomial, counting all variables that appear in @code{p}. Note +that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c}; +the degree of the constant zero is considered to be @code{-inf} +(minus infinity). + +@c @starindex +@tindex plead +The @code{plead} function finds the leading term of a polynomial. +Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))}, +though again more efficient. In particular, @samp{plead((2x+1)^10, x)} +returns 1024 without expanding out the list of coefficients. The +value of @code{plead(p,x)} will be zero only if @cite{p = 0}. + +@c @starindex +@tindex pcont +The @code{pcont} function finds the @dfn{content} of a polynomial. This +is the greatest common divisor of all the coefficients of the polynomial. +With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)} +to get a list of coefficients, then uses @code{pgcd} (the polynomial +GCD function) to combine these into an answer. For example, +@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is +basically the ``biggest'' polynomial that can be divided into @code{p} +exactly. The sign of the content is the same as the sign of the leading +coefficient. + +With only one argument, @samp{pcont(p)} computes the numerical +content of the polynomial, i.e., the @code{gcd} of the numerical +coefficients of all the terms in the formula. Note that @code{gcd} +is defined on rational numbers as well as integers; it computes +the @code{gcd} of the numerators and the @code{lcm} of the +denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3. +Dividing the polynomial by this number will clear all the +denominators, as well as dividing by any common content in the +numerators. The numerical content of a polynomial is negative only +if all the coefficients in the polynomial are negative. + +@c @starindex +@tindex pprim +The @code{pprim} function finds the @dfn{primitive part} of a +polynomial, which is simply the polynomial divided (using @code{pdiv} +if necessary) by its content. If the input polynomial has rational +coefficients, the result will have integer coefficients in simplest +terms. + +@node Numerical Solutions, Curve Fitting, Solving Equations, Algebra +@section Numerical Solutions + +@noindent +Not all equations can be solved symbolically. The commands in this +section use numerical algorithms that can find a solution to a specific +instance of an equation to any desired accuracy. Note that the +numerical commands are slower than their algebraic cousins; it is a +good idea to try @kbd{a S} before resorting to these commands. + +(@xref{Curve Fitting}, for some other, more specialized, operations +on numerical data.) + +@menu +* Root Finding:: +* Minimization:: +* Numerical Systems of Equations:: +@end menu + +@node Root Finding, Minimization, Numerical Solutions, Numerical Solutions +@subsection Root Finding + +@noindent +@kindex a R +@pindex calc-find-root +@tindex root +@cindex Newton's method +@cindex Roots of equations +@cindex Numerical root-finding +The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a +numerical solution (or @dfn{root}) of an equation. (This command treats +inequalities the same as equations. If the input is any other kind +of formula, it is interpreted as an equation of the form @cite{X = 0}.) + +The @kbd{a R} command requires an initial guess on the top of the +stack, and a formula in the second-to-top position. It prompts for a +solution variable, which must appear in the formula. All other variables +that appear in the formula must have assigned values, i.e., when +a value is assigned to the solution variable and the formula is +evaluated with @kbd{=}, it should evaluate to a number. Any assigned +value for the solution variable itself is ignored and unaffected by +this command. + +When the command completes, the initial guess is replaced on the stack +by a vector of two numbers: The value of the solution variable that +solves the equation, and the difference between the lefthand and +righthand sides of the equation at that value. Ordinarily, the second +number will be zero or very nearly zero. (Note that Calc uses a +slightly higher precision while finding the root, and thus the second +number may be slightly different from the value you would compute from +the equation yourself.) + +The @kbd{v h} (@code{calc-head}) command is a handy way to extract +the first element of the result vector, discarding the error term. + +The initial guess can be a real number, in which case Calc searches +for a real solution near that number, or a complex number, in which +case Calc searches the whole complex plane near that number for a +solution, or it can be an interval form which restricts the search +to real numbers inside that interval. + +Calc tries to use @kbd{a d} to take the derivative of the equation. +If this succeeds, it uses Newton's method. If the equation is not +differentiable Calc uses a bisection method. (If Newton's method +appears to be going astray, Calc switches over to bisection if it +can, or otherwise gives up. In this case it may help to try again +with a slightly different initial guess.) If the initial guess is a +complex number, the function must be differentiable. + +If the formula (or the difference between the sides of an equation) +is negative at one end of the interval you specify and positive at +the other end, the root finder is guaranteed to find a root. +Otherwise, Calc subdivides the interval into small parts looking for +positive and negative values to bracket the root. When your guess is +an interval, Calc will not look outside that interval for a root. + +@kindex H a R +@tindex wroot +The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except +that if the initial guess is an interval for which the function has +the same sign at both ends, then rather than subdividing the interval +Calc attempts to widen it to enclose a root. Use this mode if +you are not sure if the function has a root in your interval. + +If the function is not differentiable, and you give a simple number +instead of an interval as your initial guess, Calc uses this widening +process even if you did not type the Hyperbolic flag. (If the function +@emph{is} differentiable, Calc uses Newton's method which does not +require a bounding interval in order to work.) + +If Calc leaves the @code{root} or @code{wroot} function in symbolic +form on the stack, it will normally display an explanation for why +no root was found. If you miss this explanation, press @kbd{w} +(@code{calc-why}) to get it back. + +@node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions +@subsection Minimization + +@noindent +@kindex a N +@kindex H a N +@kindex a X +@kindex H a X +@pindex calc-find-minimum +@pindex calc-find-maximum +@tindex minimize +@tindex maximize +@cindex Minimization, numerical +The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command +finds a minimum value for a formula. It is very similar in operation +to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial +guess on the stack, and are prompted for the name of a variable. The guess +may be either a number near the desired minimum, or an interval enclosing +the desired minimum. The function returns a vector containing the +value of the the variable which minimizes the formula's value, along +with the minimum value itself. + +Note that this command looks for a @emph{local} minimum. Many functions +have more than one minimum; some, like @c{$x \sin x$} +@cite{x sin(x)}, have infinitely +many. In fact, there is no easy way to define the ``global'' minimum +of @c{$x \sin x$} +@cite{x sin(x)} but Calc can still locate any particular local minimum +for you. Calc basically goes downhill from the initial guess until it +finds a point at which the function's value is greater both to the left +and to the right. Calc does not use derivatives when minimizing a function. + +If your initial guess is an interval and it looks like the minimum +occurs at one or the other endpoint of the interval, Calc will return +that endpoint only if that endpoint is closed; thus, minimizing @cite{17 x} +over @cite{[2..3]} will return @cite{[2, 38]}, but minimizing over +@cite{(2..3]} would report no minimum found. In general, you should +use closed intervals to find literally the minimum value in that +range of @cite{x}, or open intervals to find the local minimum, if +any, that happens to lie in that range. + +Most functions are smooth and flat near their minimum values. Because +of this flatness, if the current precision is, say, 12 digits, the +variable can only be determined meaningfully to about six digits. Thus +you should set the precision to twice as many digits as you need in your +answer. + +@c @mindex wmin@idots +@tindex wminimize +@c @mindex wmax@idots +@tindex wmaximize +The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R}, +expands the guess interval to enclose a minimum rather than requiring +that the minimum lie inside the interval you supply. + +The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and +@kbd{H a X} [@code{wmaximize}] commands effectively minimize the +negative of the formula you supply. + +The formula must evaluate to a real number at all points inside the +interval (or near the initial guess if the guess is a number). If +the initial guess is a complex number the variable will be minimized +over the complex numbers; if it is real or an interval it will +be minimized over the reals. + +@node Numerical Systems of Equations, , Minimization, Numerical Solutions +@subsection Systems of Equations + +@noindent +@cindex Systems of equations, numerical +The @kbd{a R} command can also solve systems of equations. In this +case, the equation should instead be a vector of equations, the +guess should instead be a vector of numbers (intervals are not +supported), and the variable should be a vector of variables. You +can omit the brackets while entering the list of variables. Each +equation must be differentiable by each variable for this mode to +work. The result will be a vector of two vectors: The variable +values that solved the system of equations, and the differences +between the sides of the equations with those variable values. +There must be the same number of equations as variables. Since +only plain numbers are allowed as guesses, the Hyperbolic flag has +no effect when solving a system of equations. + +It is also possible to minimize over many variables with @kbd{a N} +(or maximize with @kbd{a X}). Once again the variable name should +be replaced by a vector of variables, and the initial guess should +be an equal-sized vector of initial guesses. But, unlike the case of +multidimensional @kbd{a R}, the formula being minimized should +still be a single formula, @emph{not} a vector. Beware that +multidimensional minimization is currently @emph{very} slow. + +@node Curve Fitting, Summations, Numerical Solutions, Algebra +@section Curve Fitting + +@noindent +The @kbd{a F} command fits a set of data to a @dfn{model formula}, +such as @cite{y = m x + b} where @cite{m} and @cite{b} are parameters +to be determined. For a typical set of measured data there will be +no single @cite{m} and @cite{b} that exactly fit the data; in this +case, Calc chooses values of the parameters that provide the closest +possible fit. + +@menu +* Linear Fits:: +* Polynomial and Multilinear Fits:: +* Error Estimates for Fits:: +* Standard Nonlinear Models:: +* Curve Fitting Details:: +* Interpolation:: +@end menu + +@node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting +@subsection Linear Fits + +@noindent +@kindex a F +@pindex calc-curve-fit +@tindex fit +@cindex Linear regression +@cindex Least-squares fits +The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts +to fit a set of data (@cite{x} and @cite{y} vectors of numbers) to a +straight line, polynomial, or other function of @cite{x}. For the +moment we will consider only the case of fitting to a line, and we +will ignore the issue of whether or not the model was in fact a good +fit for the data. + +In a standard linear least-squares fit, we have a set of @cite{(x,y)} +data points that we wish to fit to the model @cite{y = m x + b} +by adjusting the parameters @cite{m} and @cite{b} to make the @cite{y} +values calculated from the formula be as close as possible to the actual +@cite{y} values in the data set. (In a polynomial fit, the model is +instead, say, @cite{y = a x^3 + b x^2 + c x + d}. In a multilinear fit, +we have data points of the form @cite{(x_1,x_2,x_3,y)} and our model is +@cite{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.) + +In the model formula, variables like @cite{x} and @cite{x_2} are called +the @dfn{independent variables}, and @cite{y} is the @dfn{dependent +variable}. Variables like @cite{m}, @cite{a}, and @cite{b} are called +the @dfn{parameters} of the model. + +The @kbd{a F} command takes the data set to be fitted from the stack. +By default, it expects the data in the form of a matrix. For example, +for a linear or polynomial fit, this would be a @c{$2\times N$} +@asis{2xN} matrix where +the first row is a list of @cite{x} values and the second row has the +corresponding @cite{y} values. For the multilinear fit shown above, +the matrix would have four rows (@cite{x_1}, @cite{x_2}, @cite{x_3}, and +@cite{y}, respectively). + +If you happen to have an @c{$N\times2$} +@asis{Nx2} matrix instead of a @c{$2\times N$} +@asis{2xN} matrix, +just press @kbd{v t} first to transpose the matrix. + +After you type @kbd{a F}, Calc prompts you to select a model. For a +linear fit, press the digit @kbd{1}. + +Calc then prompts for you to name the variables. By default it chooses +high letters like @cite{x} and @cite{y} for independent variables and +low letters like @cite{a} and @cite{b} for parameters. (The dependent +variable doesn't need a name.) The two kinds of variables are separated +by a semicolon. Since you generally care more about the names of the +independent variables than of the parameters, Calc also allows you to +name only those and let the parameters use default names. + +For example, suppose the data matrix + +@ifinfo +@group +@example +[ [ 1, 2, 3, 4, 5 ] + [ 5, 7, 9, 11, 13 ] ] +@end example +@end group +@end ifinfo +@tex +\turnoffactive +\turnoffactive +\beforedisplay +$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr + 5 & 7 & 9 & 11 & 13 } +$$ +\afterdisplay +@end tex + +@noindent +is on the stack and we wish to do a simple linear fit. Type +@kbd{a F}, then @kbd{1} for the model, then @kbd{RET} to use +the default names. The result will be the formula @cite{3 + 2 x} +on the stack. Calc has created the model expression @kbd{a + b x}, +then found the optimal values of @cite{a} and @cite{b} to fit the +data. (In this case, it was able to find an exact fit.) Calc then +substituted those values for @cite{a} and @cite{b} in the model +formula. + +The @kbd{a F} command puts two entries in the trail. One is, as +always, a copy of the result that went to the stack; the other is +a vector of the actual parameter values, written as equations: +@cite{[a = 3, b = 2]}, in case you'd rather read them in a list +than pick them out of the formula. (You can type @kbd{t y} +to move this vector to the stack; @pxref{Trail Commands}.) + +Specifying a different independent variable name will affect the +resulting formula: @kbd{a F 1 k RET} produces @kbd{3 + 2 k}. +Changing the parameter names (say, @kbd{a F 1 k;b,m RET}) will affect +the equations that go into the trail. + +@tex +\bigskip +@end tex + +To see what happens when the fit is not exact, we could change +the number 13 in the data matrix to 14 and try the fit again. +The result is: + +@example +2.6 + 2.2 x +@end example + +Evaluating this formula, say with @kbd{v x 5 RET TAB V M $ RET}, shows +a reasonably close match to the y-values in the data. + +@example +[4.8, 7., 9.2, 11.4, 13.6] +@end example + +Since there is no line which passes through all the @i{N} data points, +Calc has chosen a line that best approximates the data points using +the method of least squares. The idea is to define the @dfn{chi-square} +error measure + +@ifinfo +@example +chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N) +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$ +\afterdisplay +@end tex + +@noindent +which is clearly zero if @cite{a + b x} exactly fits all data points, +and increases as various @cite{a + b x_i} values fail to match the +corresponding @cite{y_i} values. There are several reasons why the +summand is squared, one of them being to ensure that @c{$\chi^2 \ge 0$} +@cite{chi^2 >= 0}. +Least-squares fitting simply chooses the values of @cite{a} and @cite{b} +for which the error @c{$\chi^2$} +@cite{chi^2} is as small as possible. + +Other kinds of models do the same thing but with a different model +formula in place of @cite{a + b x_i}. + +@tex +\bigskip +@end tex + +A numeric prefix argument causes the @kbd{a F} command to take the +data in some other form than one big matrix. A positive argument @i{N} +will take @i{N} items from the stack, corresponding to the @i{N} rows +of a data matrix. In the linear case, @i{N} must be 2 since there +is always one independent variable and one dependent variable. + +A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two +items from the stack, an @i{N}-row matrix of @cite{x} values, and a +vector of @cite{y} values. If there is only one independent variable, +the @cite{x} values can be either a one-row matrix or a plain vector, +in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix. + +@node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting +@subsection Polynomial and Multilinear Fits + +@noindent +To fit the data to higher-order polynomials, just type one of the +digits @kbd{2} through @kbd{9} when prompted for a model. For example, +we could fit the original data matrix from the previous section +(with 13, not 14) to a parabola instead of a line by typing +@kbd{a F 2 RET}. + +@example +2.00000000001 x - 1.5e-12 x^2 + 2.99999999999 +@end example + +Note that since the constant and linear terms are enough to fit the +data exactly, it's no surprise that Calc chose a tiny contribution +for @cite{x^2}. (The fact that it's not exactly zero is due only +to roundoff error. Since our data are exact integers, we could get +an exact answer by typing @kbd{m f} first to get fraction mode. +Then the @cite{x^2} term would vanish altogether. Usually, though, +the data being fitted will be approximate floats so fraction mode +won't help.) + +Doing the @kbd{a F 2} fit on the data set with 14 instead of 13 +gives a much larger @cite{x^2} contribution, as Calc bends the +line slightly to improve the fit. + +@example +0.142857142855 x^2 + 1.34285714287 x + 3.59999999998 +@end example + +An important result from the theory of polynomial fitting is that it +is always possible to fit @i{N} data points exactly using a polynomial +of degree @i{N-1}, sometimes called an @dfn{interpolating polynomial}. +Using the modified (14) data matrix, a model number of 4 gives +a polynomial that exactly matches all five data points: + +@example +0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4. +@end example + +The actual coefficients we get with a precision of 12, like +@cite{0.0416666663588}, clearly suffer from loss of precision. +It is a good idea to increase the working precision to several +digits beyond what you need when you do a fitting operation. +Or, if your data are exact, use fraction mode to get exact +results. + +You can type @kbd{i} instead of a digit at the model prompt to fit +the data exactly to a polynomial. This just counts the number of +columns of the data matrix to choose the degree of the polynomial +automatically. + +Fitting data ``exactly'' to high-degree polynomials is not always +a good idea, though. High-degree polynomials have a tendency to +wiggle uncontrollably in between the fitting data points. Also, +if the exact-fit polynomial is going to be used to interpolate or +extrapolate the data, it is numerically better to use the @kbd{a p} +command described below. @xref{Interpolation}. + +@tex +\bigskip +@end tex + +Another generalization of the linear model is to assume the +@cite{y} values are a sum of linear contributions from several +@cite{x} values. This is a @dfn{multilinear} fit, and it is also +selected by the @kbd{1} digit key. (Calc decides whether the fit +is linear or multilinear by counting the rows in the data matrix.) + +Given the data matrix, + +@group +@example +[ [ 1, 2, 3, 4, 5 ] + [ 7, 2, 3, 5, 2 ] + [ 14.5, 15, 18.5, 22.5, 24 ] ] +@end example +@end group + +@noindent +the command @kbd{a F 1 RET} will call the first row @cite{x} and the +second row @cite{y}, and will fit the values in the third row to the +model @cite{a + b x + c y}. + +@example +8. + 3. x + 0.5 y +@end example + +Calc can do multilinear fits with any number of independent variables +(i.e., with any number of data rows). + +@tex +\bigskip +@end tex + +Yet another variation is @dfn{homogeneous} linear models, in which +the constant term is known to be zero. In the linear case, this +means the model formula is simply @cite{a x}; in the multilinear +case, the model might be @cite{a x + b y + c z}; and in the polynomial +case, the model could be @cite{a x + b x^2 + c x^3}. You can get +a homogeneous linear or multilinear model by pressing the letter +@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}. + +It is certainly possible to have other constrained linear models, +like @cite{2.3 + a x} or @cite{a - 4 x}. While there is no single +key to select models like these, a later section shows how to enter +any desired model by hand. In the first case, for example, you +would enter @kbd{a F ' 2.3 + a x}. + +Another class of models that will work but must be entered by hand +are multinomial fits, e.g., @cite{a + b x + c y + d x^2 + e y^2 + f x y}. + +@node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting +@subsection Error Estimates for Fits + +@noindent +@kindex H a F +@tindex efit +With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same +fitting operation as @kbd{a F}, but reports the coefficients as error +forms instead of plain numbers. Fitting our two data matrices (first +with 13, then with 14) to a line with @kbd{H a F} gives the results, + +@example +3. + 2. x +2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x +@end example + +In the first case the estimated errors are zero because the linear +fit is perfect. In the second case, the errors are nonzero but +moderately small, because the data are still very close to linear. + +It is also possible for the @emph{input} to a fitting operation to +contain error forms. The data values must either all include errors +or all be plain numbers. Error forms can go anywhere but generally +go on the numbers in the last row of the data matrix. If the last +row contains error forms +`@i{y_i}@w{ @t{+/-} }@c{$\sigma_i$} +@i{sigma_i}', then the @c{$\chi^2$} +@cite{chi^2} +statistic is now, + +@ifinfo +@example +chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N) +@end example +@end ifinfo +@tex +\turnoffactive +\beforedisplay +$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$ +\afterdisplay +@end tex + +@noindent +so that data points with larger error estimates contribute less to +the fitting operation. + +If there are error forms on other rows of the data matrix, all the +errors for a given data point are combined; the square root of the +sum of the squares of the errors forms the @c{$\sigma_i$} +@cite{sigma_i} used for +the data point. + +Both @kbd{a F} and @kbd{H a F} can accept error forms in the input +matrix, although if you are concerned about error analysis you will +probably use @kbd{H a F} so that the output also contains error +estimates. + +If the input contains error forms but all the @c{$\sigma_i$} +@cite{sigma_i} values are +the same, it is easy to see that the resulting fitted model will be +the same as if the input did not have error forms at all (@c{$\chi^2$} +@cite{chi^2} +is simply scaled uniformly by @c{$1 / \sigma^2$} +@cite{1 / sigma^2}, which doesn't affect +where it has a minimum). But there @emph{will} be a difference +in the estimated errors of the coefficients reported by @kbd{H a F}. + +Consult any text on statistical modelling of data for a discussion +of where these error estimates come from and how they should be +interpreted. + +@tex +\bigskip +@end tex + +@kindex I a F +@tindex xfit +With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more +information. The result is a vector of six items: + +@enumerate +@item +The model formula with error forms for its coefficients or +parameters. This is the result that @kbd{H a F} would have +produced. + +@item +A vector of ``raw'' parameter values for the model. These are the +polynomial coefficients or other parameters as plain numbers, in the +same order as the parameters appeared in the final prompt of the +@kbd{I a F} command. For polynomials of degree @cite{d}, this vector +will have length @cite{M = d+1} with the constant term first. + +@item +The covariance matrix @cite{C} computed from the fit. This is +an @i{M}x@i{M} symmetric matrix; the diagonal elements +@c{$C_{jj}$} +@cite{C_j_j} are the variances @c{$\sigma_j^2$} +@cite{sigma_j^2} of the parameters. +The other elements are covariances @c{$\sigma_{ij}^2$} +@cite{sigma_i_j^2} that describe the +correlation between pairs of parameters. (A related set of +numbers, the @dfn{linear correlation coefficients} @c{$r_{ij}$} +@cite{r_i_j}, +are defined as @c{$\sigma_{ij}^2 / \sigma_i \, \sigma_j$} +@cite{sigma_i_j^2 / sigma_i sigma_j}.) + +@item +A vector of @cite{M} ``parameter filter'' functions whose +meanings are described below. If no filters are necessary this +will instead be an empty vector; this is always the case for the +polynomial and multilinear fits described so far. + +@item +The value of @c{$\chi^2$} +@cite{chi^2} for the fit, calculated by the formulas +shown above. This gives a measure of the quality of the fit; +statisticians consider @c{$\chi^2 \approx N - M$} +@cite{chi^2 = N - M} to indicate a moderately good fit +(where again @cite{N} is the number of data points and @cite{M} +is the number of parameters). + +@item +A measure of goodness of fit expressed as a probability @cite{Q}. +This is computed from the @code{utpc} probability distribution +function using @c{$\chi^2$} +@cite{chi^2} with @cite{N - M} degrees of freedom. A +value of 0.5 implies a good fit; some texts recommend that often +@cite{Q = 0.1} or even 0.001 can signify an acceptable fit. In +particular, @c{$\chi^2$} +@cite{chi^2} statistics assume the errors in your inputs +follow a normal (Gaussian) distribution; if they don't, you may +have to accept smaller values of @cite{Q}. + +The @cite{Q} value is computed only if the input included error +estimates. Otherwise, Calc will report the symbol @code{nan} +for @cite{Q}. The reason is that in this case the @c{$\chi^2$} +@cite{chi^2} +value has effectively been used to estimate the original errors +in the input, and thus there is no redundant information left +over to use for a confidence test. +@end enumerate + +@node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting +@subsection Standard Nonlinear Models + +@noindent +The @kbd{a F} command also accepts other kinds of models besides +lines and polynomials. Some common models have quick single-key +abbreviations; others must be entered by hand as algebraic formulas. + +Here is a complete list of the standard models recognized by @kbd{a F}: + +@table @kbd +@item 1 +Linear or multilinear. @i{a + b x + c y + d z}. +@item 2-9 +Polynomials. @i{a + b x + c x^2 + d x^3}. +@item e +Exponential. @i{a} @t{exp}@i{(b x)} @t{exp}@i{(c y)}. +@item E +Base-10 exponential. @i{a} @t{10^}@i{(b x)} @t{10^}@i{(c y)}. +@item x +Exponential (alternate notation). @t{exp}@i{(a + b x + c y)}. +@item X +Base-10 exponential (alternate). @t{10^}@i{(a + b x + c y)}. +@item l +Logarithmic. @i{a + b} @t{ln}@i{(x) + c} @t{ln}@i{(y)}. +@item L +Base-10 logarithmic. @i{a + b} @t{log10}@i{(x) + c} @t{log10}@i{(y)}. +@item ^ +General exponential. @i{a b^x c^y}. +@item p +Power law. @i{a x^b y^c}. +@item q +Quadratic. @i{a + b (x-c)^2 + d (x-e)^2}. +@item g +Gaussian. @c{${a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)$} +@i{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}. +@end table + +All of these models are used in the usual way; just press the appropriate +letter at the model prompt, and choose variable names if you wish. The +result will be a formula as shown in the above table, with the best-fit +values of the parameters substituted. (You may find it easier to read +the parameter values from the vector that is placed in the trail.) + +All models except Gaussian and polynomials can generalize as shown to any +number of independent variables. Also, all the built-in models have an +additive or multiplicative parameter shown as @cite{a} in the above table +which can be replaced by zero or one, as appropriate, by typing @kbd{h} +before the model key. + +Note that many of these models are essentially equivalent, but express +the parameters slightly differently. For example, @cite{a b^x} and +the other two exponential models are all algebraic rearrangements of +each other. Also, the ``quadratic'' model is just a degree-2 polynomial +with the parameters expressed differently. Use whichever form best +matches the problem. + +The HP-28/48 calculators support four different models for curve +fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}. +These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)}, +@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case, +@cite{a} is what the HP-48 identifies as the ``intercept,'' and +@cite{b} is what it calls the ``slope.'' + +@tex +\bigskip +@end tex + +If the model you want doesn't appear on this list, press @kbd{'} +(the apostrophe key) at the model prompt to enter any algebraic +formula, such as @kbd{m x - b}, as the model. (Not all models +will work, though---see the next section for details.) + +The model can also be an equation like @cite{y = m x + b}. +In this case, Calc thinks of all the rows of the data matrix on +equal terms; this model effectively has two parameters +(@cite{m} and @cite{b}) and two independent variables (@cite{x} +and @cite{y}), with no ``dependent'' variables. Model equations +do not need to take this @cite{y =} form. For example, the +implicit line equation @cite{a x + b y = 1} works fine as a +model. + +When you enter a model, Calc makes an alphabetical list of all +the variables that appear in the model. These are used for the +default parameters, independent variables, and dependent variable +(in that order). If you enter a plain formula (not an equation), +Calc assumes the dependent variable does not appear in the formula +and thus does not need a name. + +For example, if the model formula has the variables @cite{a,mu,sigma,t,x}, +and the data matrix has three rows (meaning two independent variables), +Calc will use @cite{a,mu,sigma} as the default parameters, and the +data rows will be named @cite{t} and @cite{x}, respectively. If you +enter an equation instead of a plain formula, Calc will use @cite{a,mu} +as the parameters, and @cite{sigma,t,x} as the three independent +variables. + +You can, of course, override these choices by entering something +different at the prompt. If you leave some variables out of the list, +those variables must have stored values and those stored values will +be used as constants in the model. (Stored values for the parameters +and independent variables are ignored by the @kbd{a F} command.) +If you list only independent variables, all the remaining variables +in the model formula will become parameters. + +If there are @kbd{$} signs in the model you type, they will stand +for parameters and all other variables (in alphabetical order) +will be independent. Use @kbd{$} for one parameter, @kbd{$$} for +another, and so on. Thus @kbd{$ x + $$} is another way to describe +a linear model. + +If you type a @kbd{$} instead of @kbd{'} at the model prompt itself, +Calc will take the model formula from the stack. (The data must then +appear at the second stack level.) The same conventions are used to +choose which variables in the formula are independent by default and +which are parameters. + +Models taken from the stack can also be expressed as vectors of +two or three elements, @cite{[@var{model}, @var{vars}]} or +@cite{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars} +and @var{params} may be either a variable or a vector of variables. +(If @var{params} is omitted, all variables in @var{model} except +those listed as @var{vars} are parameters.)@refill + +When you enter a model manually with @kbd{'}, Calc puts a 3-vector +describing the model in the trail so you can get it back if you wish. + +@tex +\bigskip +@end tex + +@vindex Model1 +@vindex Model2 +Finally, you can store a model in one of the Calc variables +@code{Model1} or @code{Model2}, then use this model by typing +@kbd{a F u} or @kbd{a F U} (respectively). The value stored in +the variable can be any of the formats that @kbd{a F $} would +accept for a model on the stack. + +@tex +\bigskip +@end tex + +Calc uses the principal values of inverse functions like @code{ln} +and @code{arcsin} when doing fits. For example, when you enter +the model @samp{y = sin(a t + b)} Calc actually uses the easier +form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always +returns results in the range from @i{-90} to 90 degrees (or the +equivalent range in radians). Suppose you had data that you +believed to represent roughly three oscillations of a sine wave, +so that the argument of the sine might go from zero to @c{$3\times360$} +@i{3*360} degrees. +The above model would appear to be a good way to determine the +true frequency and phase of the sine wave, but in practice it +would fail utterly. The righthand side of the actual model +@samp{arcsin(y) = a t + b} will grow smoothly with @cite{t}, but +the lefthand side will bounce back and forth between @i{-90} and 90. +No values of @cite{a} and @cite{b} can make the two sides match, +even approximately. + +There is no good solution to this problem at present. You could +restrict your data to small enough ranges so that the above problem +doesn't occur (i.e., not straddling any peaks in the sine wave). +Or, in this case, you could use a totally different method such as +Fourier analysis, which is beyond the scope of the @kbd{a F} command. +(Unfortunately, Calc does not currently have any facilities for +taking Fourier and related transforms.) + +@node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting +@subsection Curve Fitting Details + +@noindent +Calc's internal least-squares fitter can only handle multilinear +models. More precisely, it can handle any model of the form +@cite{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @cite{a,b,c} +are the parameters and @cite{x,y,z} are the independent variables +(of course there can be any number of each, not just three). + +In a simple multilinear or polynomial fit, it is easy to see how +to convert the model into this form. For example, if the model +is @cite{a + b x + c x^2}, then @cite{f(x) = 1}, @cite{g(x) = x}, +and @cite{h(x) = x^2} are suitable functions. + +For other models, Calc uses a variety of algebraic manipulations +to try to put the problem into the form + +@smallexample +Y(x,y,z) = A(a,b,c) F(x,y,z) + B(a,b,c) G(x,y,z) + C(a,b,c) H(x,y,z) +@end smallexample + +@noindent +where @cite{Y,A,B,C,F,G,H} are arbitrary functions. It computes +@cite{Y}, @cite{F}, @cite{G}, and @cite{H} for all the data points, +does a standard linear fit to find the values of @cite{A}, @cite{B}, +and @cite{C}, then uses the equation solver to solve for @cite{a,b,c} +in terms of @cite{A,B,C}. + +A remarkable number of models can be cast into this general form. +We'll look at two examples here to see how it works. The power-law +model @cite{y = a x^b} with two independent variables and two parameters +can be rewritten as follows: + +@example +y = a x^b +y = a exp(b ln(x)) +y = exp(ln(a) + b ln(x)) +ln(y) = ln(a) + b ln(x) +@end example + +@noindent +which matches the desired form with @c{$Y = \ln(y)$} +@cite{Y = ln(y)}, @c{$A = \ln(a)$} +@cite{A = ln(a)}, +@cite{F = 1}, @cite{B = b}, and @c{$G = \ln(x)$} +@cite{G = ln(x)}. Calc thus computes +the logarithms of your @cite{y} and @cite{x} values, does a linear fit +for @cite{A} and @cite{B}, then solves to get @c{$a = \exp(A)$} +@cite{a = exp(A)} and +@cite{b = B}. + +Another interesting example is the ``quadratic'' model, which can +be handled by expanding according to the distributive law. + +@example +y = a + b*(x - c)^2 +y = a + b c^2 - 2 b c x + b x^2 +@end example + +@noindent +which matches with @cite{Y = y}, @cite{A = a + b c^2}, @cite{F = 1}, +@cite{B = -2 b c}, @cite{G = x} (the @i{-2} factor could just as easily +have been put into @cite{G} instead of @cite{B}), @cite{C = b}, and +@cite{H = x^2}. + +The Gaussian model looks quite complicated, but a closer examination +shows that it's actually similar to the quadratic model but with an +exponential that can be brought to the top and moved into @cite{Y}. + +An example of a model that cannot be put into general linear +form is a Gaussian with a constant background added on, i.e., +@cite{d} + the regular Gaussian formula. If you have a model like +this, your best bet is to replace enough of your parameters with +constants to make the model linearizable, then adjust the constants +manually by doing a series of fits. You can compare the fits by +graphing them, by examining the goodness-of-fit measures returned by +@kbd{I a F}, or by some other method suitable to your application. +Note that some models can be linearized in several ways. The +Gaussian-plus-@i{d} model can be linearized by setting @cite{d} +(the background) to a constant, or by setting @cite{b} (the standard +deviation) and @cite{c} (the mean) to constants. + +To fit a model with constants substituted for some parameters, just +store suitable values in those parameter variables, then omit them +from the list of parameters when you answer the variables prompt. + +@tex +\bigskip +@end tex + +A last desperate step would be to use the general-purpose +@code{minimize} function rather than @code{fit}. After all, both +functions solve the problem of minimizing an expression (the @c{$\chi^2$} +@cite{chi^2} +sum) by adjusting certain parameters in the expression. The @kbd{a F} +command is able to use a vastly more efficient algorithm due to its +special knowledge about linear chi-square sums, but the @kbd{a N} +command can do the same thing by brute force. + +A compromise would be to pick out a few parameters without which the +fit is linearizable, and use @code{minimize} on a call to @code{fit} +which efficiently takes care of the rest of the parameters. The thing +to be minimized would be the value of @c{$\chi^2$} +@cite{chi^2} returned as +the fifth result of the @code{xfit} function: + +@smallexample +minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess) +@end smallexample + +@noindent +where @code{gaus} represents the Gaussian model with background, +@code{data} represents the data matrix, and @code{guess} represents +the initial guess for @cite{d} that @code{minimize} requires. +This operation will only be, shall we say, extraordinarily slow +rather than astronomically slow (as would be the case if @code{minimize} +were used by itself to solve the problem). + +@tex +\bigskip +@end tex + +The @kbd{I a F} [@code{xfit}] command is somewhat trickier when +nonlinear models are used. The second item in the result is the +vector of ``raw'' parameters @cite{A}, @cite{B}, @cite{C}. The +covariance matrix is written in terms of those raw parameters. +The fifth item is a vector of @dfn{filter} expressions. This +is the empty vector @samp{[]} if the raw parameters were the same +as the requested parameters, i.e., if @cite{A = a}, @cite{B = b}, +and so on (which is always true if the model is already linear +in the parameters as written, e.g., for polynomial fits). If the +parameters had to be rearranged, the fifth item is instead a vector +of one formula per parameter in the original model. The raw +parameters are expressed in these ``filter'' formulas as +@samp{fitdummy(1)} for @cite{A}, @samp{fitdummy(2)} for @cite{B}, +and so on. + +When Calc needs to modify the model to return the result, it replaces +@samp{fitdummy(1)} in all the filters with the first item in the raw +parameters list, and so on for the other raw parameters, then +evaluates the resulting filter formulas to get the actual parameter +values to be substituted into the original model. In the case of +@kbd{H a F} and @kbd{I a F} where the parameters must be error forms, +Calc uses the square roots of the diagonal entries of the covariance +matrix as error values for the raw parameters, then lets Calc's +standard error-form arithmetic take it from there. + +If you use @kbd{I a F} with a nonlinear model, be sure to remember +that the covariance matrix is in terms of the raw parameters, +@emph{not} the actual requested parameters. It's up to you to +figure out how to interpret the covariances in the presence of +nontrivial filter functions. + +Things are also complicated when the input contains error forms. +Suppose there are three independent and dependent variables, @cite{x}, +@cite{y}, and @cite{z}, one or more of which are error forms in the +data. Calc combines all the error values by taking the square root +of the sum of the squares of the errors. It then changes @cite{x} +and @cite{y} to be plain numbers, and makes @cite{z} into an error +form with this combined error. The @cite{Y(x,y,z)} part of the +linearized model is evaluated, and the result should be an error +form. The error part of that result is used for @c{$\sigma_i$} +@cite{sigma_i} for +the data point. If for some reason @cite{Y(x,y,z)} does not return +an error form, the combined error from @cite{z} is used directly +for @c{$\sigma_i$} +@cite{sigma_i}. Finally, @cite{z} is also stripped of its error +for use in computing @cite{F(x,y,z)}, @cite{G(x,y,z)} and so on; +the righthand side of the linearized model is computed in regular +arithmetic with no error forms. + +(While these rules may seem complicated, they are designed to do +the most reasonable thing in the typical case that @cite{Y(x,y,z)} +depends only on the dependent variable @cite{z}, and in fact is +often simply equal to @cite{z}. For common cases like polynomials +and multilinear models, the combined error is simply used as the +@c{$\sigma$} +@cite{sigma} for the data point with no further ado.) + +@tex +\bigskip +@end tex + +@vindex FitRules +It may be the case that the model you wish to use is linearizable, +but Calc's built-in rules are unable to figure it out. Calc uses +its algebraic rewrite mechanism to linearize a model. The rewrite +rules are kept in the variable @code{FitRules}. You can edit this +variable using the @kbd{s e FitRules} command; in fact, there is +a special @kbd{s F} command just for editing @code{FitRules}. +@xref{Operations on Variables}. + +@xref{Rewrite Rules}, for a discussion of rewrite rules. + +@c @starindex +@tindex fitvar +@c @starindex +@c @mindex @idots +@tindex fitparam +@c @starindex +@c @mindex @null +@tindex fitmodel +@c @starindex +@c @mindex @null +@tindex fitsystem +@c @starindex +@c @mindex @null +@tindex fitdummy +Calc uses @code{FitRules} as follows. First, it converts the model +to an equation if necessary and encloses the model equation in a +call to the function @code{fitmodel} (which is not actually a defined +function in Calc; it is only used as a placeholder by the rewrite rules). +Parameter variables are renamed to function calls @samp{fitparam(1)}, +@samp{fitparam(2)}, and so on, and independent variables are renamed +to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable +is the highest-numbered @code{fitvar}. For example, the power law +model @cite{a x^b} is converted to @cite{y = a x^b}, then to + +@group +@smallexample +fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2)) +@end smallexample +@end group + +Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}. +(The zero prefix means that rewriting should continue until no further +changes are possible.) + +When rewriting is complete, the @code{fitmodel} call should have +been replaced by a @code{fitsystem} call that looks like this: + +@example +fitsystem(@var{Y}, @var{FGH}, @var{abc}) +@end example + +@noindent +where @var{Y} is a formula that describes the function @cite{Y(x,y,z)}, +@var{FGH} is the vector of formulas @cite{[F(x,y,z), G(x,y,z), H(x,y,z)]}, +and @var{abc} is the vector of parameter filters which refer to the +raw parameters as @samp{fitdummy(1)} for @cite{A}, @samp{fitdummy(2)} +for @cite{B}, etc. While the number of raw parameters (the length of +the @var{FGH} vector) is usually the same as the number of original +parameters (the length of the @var{abc} vector), this is not required. + +The power law model eventually boils down to + +@group +@smallexample +fitsystem(ln(fitvar(2)), + [1, ln(fitvar(1))], + [exp(fitdummy(1)), fitdummy(2)]) +@end smallexample +@end group + +The actual implementation of @code{FitRules} is complicated; it +proceeds in four phases. First, common rearrangements are done +to try to bring linear terms together and to isolate functions like +@code{exp} and @code{ln} either all the way ``out'' (so that they +can be put into @var{Y}) or all the way ``in'' (so that they can +be put into @var{abc} or @var{FGH}). In particular, all +non-constant powers are converted to logs-and-exponentials form, +and the distributive law is used to expand products of sums. +Quotients are rewritten to use the @samp{fitinv} function, where +@samp{fitinv(x)} represents @cite{1/x} while the @code{FitRules} +are operating. (The use of @code{fitinv} makes recognition of +linear-looking forms easier.) If you modify @code{FitRules}, you +will probably only need to modify the rules for this phase. + +Phase two, whose rules can actually also apply during phases one +and three, first rewrites @code{fitmodel} to a two-argument +form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is +initially zero and @var{model} has been changed from @cite{a=b} +to @cite{a-b} form. It then tries to peel off invertible functions +from the outside of @var{model} and put them into @var{Y} instead, +calling the equation solver to invert the functions. Finally, when +this is no longer possible, the @code{fitmodel} is changed to a +four-argument @code{fitsystem}, where the fourth argument is +@var{model} and the @var{FGH} and @var{abc} vectors are initially +empty. (The last vector is really @var{ABC}, corresponding to +raw parameters, for now.) + +Phase three converts a sum of items in the @var{model} to a sum +of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent +terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a} +is all factors that do not involve any variables, @var{b} is all +factors that involve only parameters, and @var{c} is the factors +that involve only independent variables. (If this decomposition +is not possible, the rule set will not complete and Calc will +complain that the model is too complex.) Then @code{fitpart}s +with equal @var{b} or @var{c} components are merged back together +using the distributive law in order to minimize the number of +raw parameters needed. + +Phase four moves the @code{fitpart} terms into the @var{FGH} and +@var{ABC} vectors. Also, some of the algebraic expansions that +were done in phase 1 are undone now to make the formulas more +computationally efficient. Finally, it calls the solver one more +time to convert the @var{ABC} vector to an @var{abc} vector, and +removes the fourth @var{model} argument (which by now will be zero) +to obtain the three-argument @code{fitsystem} that the linear +least-squares solver wants to see. + +@c @starindex +@c @mindex hasfit@idots +@tindex hasfitparams +@c @starindex +@c @mindex @null +@tindex hasfitvars +Two functions which are useful in connection with @code{FitRules} +are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check +whether @cite{x} refers to any parameters or independent variables, +respectively. Specifically, these functions return ``true'' if the +argument contains any @code{fitparam} (or @code{fitvar}) function +calls, and ``false'' otherwise. (Recall that ``true'' means a +nonzero number, and ``false'' means zero. The actual nonzero number +returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s +or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.) + +@tex +\bigskip +@end tex + +The @code{fit} function in algebraic notation normally takes four +arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})}, +where @var{model} is the model formula as it would be typed after +@kbd{a F '}, @var{vars} is the independent variable or a vector of +independent variables, @var{params} likewise gives the parameter(s), +and @var{data} is the data matrix. Note that the length of @var{vars} +must be equal to the number of rows in @var{data} if @var{model} is +an equation, or one less than the number of rows if @var{model} is +a plain formula. (Actually, a name for the dependent variable is +allowed but will be ignored in the plain-formula case.) + +If @var{params} is omitted, the parameters are all variables in +@var{model} except those that appear in @var{vars}. If @var{vars} +is also omitted, Calc sorts all the variables that appear in +@var{model} alphabetically and uses the higher ones for @var{vars} +and the lower ones for @var{params}. + +Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed +where @var{modelvec} is a 2- or 3-vector describing the model +and variables, as discussed previously. + +If Calc is unable to do the fit, the @code{fit} function is left +in symbolic form, ordinarily with an explanatory message. The +message will be ``Model expression is too complex'' if the +linearizer was unable to put the model into the required form. + +The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit} +(for @kbd{I a F}) functions are completely analogous. + +@node Interpolation, , Curve Fitting Details, Curve Fitting +@subsection Polynomial Interpolation + +@kindex a p +@pindex calc-poly-interp +@tindex polint +The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does +a polynomial interpolation at a particular @cite{x} value. It takes +two arguments from the stack: A data matrix of the sort used by +@kbd{a F}, and a single number which represents the desired @cite{x} +value. Calc effectively does an exact polynomial fit as if by @kbd{a F i}, +then substitutes the @cite{x} value into the result in order to get an +approximate @cite{y} value based on the fit. (Calc does not actually +use @kbd{a F i}, however; it uses a direct method which is both more +efficient and more numerically stable.) + +The result of @kbd{a p} is actually a vector of two values: The @cite{y} +value approximation, and an error measure @cite{dy} that reflects Calc's +estimation of the probable error of the approximation at that value of +@cite{x}. If the input @cite{x} is equal to any of the @cite{x} values +in the data matrix, the output @cite{y} will be the corresponding @cite{y} +value from the matrix, and the output @cite{dy} will be exactly zero. + +A prefix argument of 2 causes @kbd{a p} to take separate x- and +y-vectors from the stack instead of one data matrix. + +If @cite{x} is a vector of numbers, @kbd{a p} will return a matrix of +interpolated results for each of those @cite{x} values. (The matrix will +have two columns, the @cite{y} values and the @cite{dy} values.) +If @cite{x} is a formula instead of a number, the @code{polint} function +remains in symbolic form; use the @kbd{a "} command to expand it out to +a formula that describes the fit in symbolic terms. + +In all cases, the @kbd{a p} command leaves the data vectors or matrix +on the stack. Only the @cite{x} value is replaced by the result. + +@kindex H a p +@tindex ratint +The @kbd{H a p} [@code{ratint}] command does a rational function +interpolation. It is used exactly like @kbd{a p}, except that it +uses as its model the quotient of two polynomials. If there are +@cite{N} data points, the numerator and denominator polynomials will +each have degree @cite{N/2} (if @cite{N} is odd, the denominator will +have degree one higher than the numerator). + +Rational approximations have the advantage that they can accurately +describe functions that have poles (points at which the function's value +goes to infinity, so that the denominator polynomial of the approximation +goes to zero). If @cite{x} corresponds to a pole of the fitted rational +function, then the result will be a division by zero. If Infinite mode +is enabled, the result will be @samp{[uinf, uinf]}. + +There is no way to get the actual coefficients of the rational function +used by @kbd{H a p}. (The algorithm never generates these coefficients +explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s +capabilities to fit.) + +@node Summations, Logical Operations, Curve Fitting, Algebra +@section Summations + +@noindent +@cindex Summation of a series +@kindex a + +@pindex calc-summation +@tindex sum +The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes +the sum of a formula over a certain range of index values. The formula +is taken from the top of the stack; the command prompts for the +name of the summation index variable, the lower limit of the +sum (any formula), and the upper limit of the sum. If you +enter a blank line at any of these prompts, that prompt and +any later ones are answered by reading additional elements from +the stack. Thus, @kbd{' k^2 RET ' k RET 1 RET 5 RET a + RET} +produces the result 55. +@tex +\turnoffactive +$$ \sum_{k=1}^5 k^2 = 55 $$ +@end tex + +The choice of index variable is arbitrary, but it's best not to +use a variable with a stored value. In particular, while +@code{i} is often a favorite index variable, it should be avoided +in Calc because @code{i} has the imaginary constant @cite{(0, 1)} +as a value. If you pressed @kbd{=} on a sum over @code{i}, it would +be changed to a nonsensical sum over the ``variable'' @cite{(0, 1)}! +If you really want to use @code{i} as an index variable, use +@w{@kbd{s u i RET}} first to ``unstore'' this variable. +(@xref{Storing Variables}.) + +A numeric prefix argument steps the index by that amount rather +than by one. Thus @kbd{' a_k RET C-u -2 a + k RET 10 RET 0 RET} +yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix +argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the +step value, in which case you can enter any formula or enter +a blank line to take the step value from the stack. With the +@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from +the stack: The formula, the variable, the lower limit, the +upper limit, and (at the top of the stack), the step value. + +Calc knows how to do certain sums in closed form. For example, +@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular, +this is possible if the formula being summed is polynomial or +exponential in the index variable. Sums of logarithms are +transformed into logarithms of products. Sums of trigonometric +and hyperbolic functions are transformed to sums of exponentials +and then done in closed form. Also, of course, sums in which the +lower and upper limits are both numbers can always be evaluated +just by grinding them out, although Calc will use closed forms +whenever it can for the sake of efficiency. + +The notation for sums in algebraic formulas is +@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}. +If @var{step} is omitted, it defaults to one. If @var{high} is +omitted, @var{low} is actually the upper limit and the lower limit +is one. If @var{low} is also omitted, the limits are @samp{-inf} +and @samp{inf}, respectively. + +Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)} +returns @cite{1}. This is done by evaluating the sum in closed +form (to @samp{1. - 0.5^n} in this case), then evaluating this +formula with @code{n} set to @code{inf}. Calc's usual rules +for ``infinite'' arithmetic can find the answer from there. If +infinite arithmetic yields a @samp{nan}, or if the sum cannot be +solved in closed form, Calc leaves the @code{sum} function in +symbolic form. @xref{Infinities}. + +As a special feature, if the limits are infinite (or omitted, as +described above) but the formula includes vectors subscripted by +expressions that involve the iteration variable, Calc narrows +the limits to include only the range of integers which result in +legal subscripts for the vector. For example, the sum +@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}. + +The limits of a sum do not need to be integers. For example, +@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}. +Calc computes the number of iterations using the formula +@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must, +after simplification as if by @kbd{a s}, evaluate to an integer. + +If the number of iterations according to the above formula does +not come out to an integer, the sum is illegal and will be left +in symbolic form. However, closed forms are still supplied, and +you are on your honor not to misuse the resulting formulas by +substituting mismatched bounds into them. For example, +@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and +evaluate the closed form solution for the limits 1 and 10 to get +the rather dubious answer, 29.25. + +If the lower limit is greater than the upper limit (assuming a +positive step size), the result is generally zero. However, +Calc only guarantees a zero result when the upper limit is +exactly one step less than the lower limit, i.e., if the number +of iterations is @i{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero +but the sum from @samp{n} to @samp{n-2} may report a nonzero value +if Calc used a closed form solution. + +Calc's logical predicates like @cite{a < b} return 1 for ``true'' +and 0 for ``false.'' @xref{Logical Operations}. This can be +used to advantage for building conditional sums. For example, +@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all +prime numbers from 1 to 20; the @code{prime} predicate returns 1 if +its argument is prime and 0 otherwise. You can read this expression +as ``the sum of @cite{k^2}, where @cite{k} is prime.'' Indeed, +@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes +squared, since the limits default to plus and minus infinity, but +there are no such sums that Calc's built-in rules can do in +closed form. + +As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the +sum of @cite{f(k)} for all @cite{k} from 1 to @cite{n}, excluding +one value @cite{k_0}. Slightly more tricky is the summand +@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe +the sum of all @cite{1/(k-k_0)} except at @cite{k = k_0}, where +this would be a division by zero. But at @cite{k = k_0}, this +formula works out to the indeterminate form @cite{0 / 0}, which +Calc will not assume is zero. Better would be to use +@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does +an ``if-then-else'' test: This expression says, ``if @c{$k \ne k_0$} +@cite{k != k_0}, +then @cite{1/(k-k_0)}, else zero.'' Now the formula @cite{1/(k-k_0)} +will not even be evaluated by Calc when @cite{k = k_0}. + +@cindex Alternating sums +@kindex a - +@pindex calc-alt-summation +@tindex asum +The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command +computes an alternating sum. Successive terms of the sequence +are given alternating signs, with the first term (corresponding +to the lower index value) being positive. Alternating sums +are converted to normal sums with an extra term of the form +@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately +if the step value is other than one. For example, the Taylor +series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}. +(Calc cannot evaluate this infinite series, but it can approximate +it if you replace @code{inf} with any particular odd number.) +Calc converts this series to a regular sum with a step of one, +namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}. + +@cindex Product of a sequence +@kindex a * +@pindex calc-product +@tindex prod +The @kbd{a *} (@code{calc-product}) [@code{prod}] command is +the analogous way to take a product of many terms. Calc also knows +some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}. +Conditional products can be written @samp{prod(k^prime(k), k, 1, n)} +or @samp{prod(prime(k) ? k : 1, k, 1, n)}. + +@kindex a T +@pindex calc-tabulate +@tindex table +The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command +evaluates a formula at a series of iterated index values, just +like @code{sum} and @code{prod}, but its result is simply a +vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)} +produces @samp{[a_1, a_3, a_5, a_7]}. + +@node Logical Operations, Rewrite Rules, Summations, Algebra +@section Logical Operations + +@noindent +The following commands and algebraic functions return true/false values, +where 1 represents ``true'' and 0 represents ``false.'' In cases where +a truth value is required (such as for the condition part of a rewrite +rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any +nonzero value is accepted to mean ``true.'' (Specifically, anything +for which @code{dnonzero} returns 1 is ``true,'' and anything for +which @code{dnonzero} returns 0 or cannot decide is assumed ``false.'' +Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then'' +portion if its condition is provably true, but it will execute the +``else'' portion for any condition like @cite{a = b} that is not +provably true, even if it might be true. Algebraic functions that +have conditions as arguments, like @code{? :} and @code{&&}, remain +unevaluated if the condition is neither provably true nor provably +false. @xref{Declarations}.) + +@kindex a = +@pindex calc-equal-to +@tindex eq +@tindex = +@tindex == +The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function +(which can also be written @samp{a = b} or @samp{a == b} in an algebraic +formula) is true if @cite{a} and @cite{b} are equal, either because they +are identical expressions, or because they are numbers which are +numerically equal. (Thus the integer 1 is considered equal to the float +1.0.) If the equality of @cite{a} and @cite{b} cannot be determined, +the comparison is left in symbolic form. Note that as a command, this +operation pops two values from the stack and pushes back either a 1 or +a 0, or a formula @samp{a = b} if the values' equality cannot be determined. + +Many Calc commands use @samp{=} formulas to represent @dfn{equations}. +For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges +an equation to solve for a given variable. The @kbd{a M} +(@code{calc-map-equation}) command can be used to apply any +function to both sides of an equation; for example, @kbd{2 a M *} +multiplies both sides of the equation by two. Note that just +@kbd{2 *} would not do the same thing; it would produce the formula +@samp{2 (a = b)} which represents 2 if the equality is true or +zero if not. + +The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =} +or @samp{a = b = c}) tests if all of its arguments are equal. In +algebraic notation, the @samp{=} operator is unusual in that it is +neither left- nor right-associative: @samp{a = b = c} is not the +same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare +one variable with the 1 or 0 that results from comparing two other +variables). + +@kindex a # +@pindex calc-not-equal-to +@tindex neq +@tindex != +The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or +@samp{a != b} function, is true if @cite{a} and @cite{b} are not equal. +This also works with more than two arguments; @samp{a != b != c != d} +tests that all four of @cite{a}, @cite{b}, @cite{c}, and @cite{d} are +distinct numbers. + +@kindex a < +@tindex lt +@c @mindex @idots +@kindex a > +@c @mindex @null +@kindex a [ +@c @mindex @null +@kindex a ] +@pindex calc-less-than +@pindex calc-greater-than +@pindex calc-less-equal +@pindex calc-greater-equal +@c @mindex @null +@tindex gt +@c @mindex @null +@tindex leq +@c @mindex @null +@tindex geq +@c @mindex @null +@tindex < +@c @mindex @null +@tindex > +@c @mindex @null +@tindex <= +@c @mindex @null +@tindex >= +The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}] +operation is true if @cite{a} is less than @cite{b}. Similar functions +are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}], +@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and +@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}]. + +While the inequality functions like @code{lt} do not accept more +than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an +equivalent expression involving intervals: @samp{b in [a .. c)}. +(See the description of @code{in} below.) All four combinations +of @samp{<} and @samp{<=} are allowed, or any of the four combinations +of @samp{>} and @samp{>=}. Four-argument constructions like +@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that +involve both equalities and inequalities, are not allowed. + +@kindex a . +@pindex calc-remove-equal +@tindex rmeq +The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts +the righthand side of the equation or inequality on the top of the +stack. It also works elementwise on vectors. For example, if +@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces +@samp{[2.34, z / 2]}. As a special case, if the righthand side is a +variable and the lefthand side is a number (as in @samp{2.34 = x}), then +Calc keeps the lefthand side instead. Finally, this command works with +assignments @samp{x := 2.34} as well as equations, always taking the +the righthand side, and for @samp{=>} (evaluates-to) operators, always +taking the lefthand side. + +@kindex a & +@pindex calc-logical-and +@tindex land +@tindex && +The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}] +function is true if both of its arguments are true, i.e., are +non-zero numbers. In this case, the result will be either @cite{a} or +@cite{b}, chosen arbitrarily. If either argument is zero, the result is +zero. Otherwise, the formula is left in symbolic form. + +@kindex a | +@pindex calc-logical-or +@tindex lor +@tindex || +The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}] +function is true if either or both of its arguments are true (nonzero). +The result is whichever argument was nonzero, choosing arbitrarily if both +are nonzero. If both @cite{a} and @cite{b} are zero, the result is +zero. + +@kindex a ! +@pindex calc-logical-not +@tindex lnot +@tindex ! +The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}] +function is true if @cite{a} is false (zero), or false if @cite{a} is +true (nonzero). It is left in symbolic form if @cite{a} is not a +number. + +@kindex a : +@pindex calc-logical-if +@tindex if +@c @mindex ? : +@tindex ? +@c @mindex @null +@tindex : +@cindex Arguments, not evaluated +The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}] +function is equal to either @cite{b} or @cite{c} if @cite{a} is a nonzero +number or zero, respectively. If @cite{a} is not a number, the test is +left in symbolic form and neither @cite{b} nor @cite{c} is evaluated in +any way. In algebraic formulas, this is one of the few Calc functions +whose arguments are not automatically evaluated when the function itself +is evaluated. The others are @code{lambda}, @code{quote}, and +@code{condition}. + +One minor surprise to watch out for is that the formula @samp{a?3:4} +will not work because the @samp{3:4} is parsed as a fraction instead of +as three separate symbols. Type something like @samp{a ? 3 : 4} or +@samp{a?(3):4} instead. + +As a special case, if @cite{a} evaluates to a vector, then both @cite{b} +and @cite{c} are evaluated; the result is a vector of the same length +as @cite{a} whose elements are chosen from corresponding elements of +@cite{b} and @cite{c} according to whether each element of @cite{a} +is zero or nonzero. Each of @cite{b} and @cite{c} must be either a +vector of the same length as @cite{a}, or a non-vector which is matched +with all elements of @cite{a}. + +@kindex a @{ +@pindex calc-in-set +@tindex in +The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if +the number @cite{a} is in the set of numbers represented by @cite{b}. +If @cite{b} is an interval form, @cite{a} must be one of the values +encompassed by the interval. If @cite{b} is a vector, @cite{a} must be +equal to one of the elements of the vector. (If any vector elements are +intervals, @cite{a} must be in any of the intervals.) If @cite{b} is a +plain number, @cite{a} must be numerically equal to @cite{b}. +@xref{Set Operations}, for a group of commands that manipulate sets +of this sort. + +@c @starindex +@tindex typeof +The @samp{typeof(a)} function produces an integer or variable which +characterizes @cite{a}. If @cite{a} is a number, vector, or variable, +the result will be one of the following numbers: + +@example + 1 Integer + 2 Fraction + 3 Floating-point number + 4 HMS form + 5 Rectangular complex number + 6 Polar complex number + 7 Error form + 8 Interval form + 9 Modulo form +10 Date-only form +11 Date/time form +12 Infinity (inf, uinf, or nan) +100 Variable +101 Vector (but not a matrix) +102 Matrix +@end example + +Otherwise, @cite{a} is a formula, and the result is a variable which +represents the name of the top-level function call. + +@c @starindex +@tindex integer +@c @starindex +@tindex real +@c @starindex +@tindex constant +The @samp{integer(a)} function returns true if @cite{a} is an integer. +The @samp{real(a)} function +is true if @cite{a} is a real number, either integer, fraction, or +float. The @samp{constant(a)} function returns true if @cite{a} is +any of the objects for which @code{typeof} would produce an integer +code result except for variables, and provided that the components of +an object like a vector or error form are themselves constant. +Note that infinities do not satisfy any of these tests, nor do +special constants like @code{pi} and @code{e}.@refill + +@xref{Declarations}, for a set of similar functions that recognize +formulas as well as actual numbers. For example, @samp{dint(floor(x))} +is true because @samp{floor(x)} is provably integer-valued, but +@samp{integer(floor(x))} does not because @samp{floor(x)} is not +literally an integer constant. + +@c @starindex +@tindex refers +The @samp{refers(a,b)} function is true if the variable (or sub-expression) +@cite{b} appears in @cite{a}, or false otherwise. Unlike the other +tests described here, this function returns a definite ``no'' answer +even if its arguments are still in symbolic form. The only case where +@code{refers} will be left unevaluated is if @cite{a} is a plain +variable (different from @cite{b}). + +@c @starindex +@tindex negative +The @samp{negative(a)} function returns true if @cite{a} ``looks'' negative, +because it is a negative number, because it is of the form @cite{-x}, +or because it is a product or quotient with a term that looks negative. +This is most useful in rewrite rules. Beware that @samp{negative(a)} +evaluates to 1 or 0 for @emph{any} argument @cite{a}, so it can only +be stored in a formula if the default simplifications are turned off +first with @kbd{m O} (or if it appears in an unevaluated context such +as a rewrite rule condition). + +@c @starindex +@tindex variable +The @samp{variable(a)} function is true if @cite{a} is a variable, +or false if not. If @cite{a} is a function call, this test is left +in symbolic form. Built-in variables like @code{pi} and @code{inf} +are considered variables like any others by this test. + +@c @starindex +@tindex nonvar +The @samp{nonvar(a)} function is true if @cite{a} is a non-variable. +If its argument is a variable it is left unsimplified; it never +actually returns zero. However, since Calc's condition-testing +commands consider ``false'' anything not provably true, this is +often good enough. + +@c @starindex +@tindex lin +@c @starindex +@tindex linnt +@c @starindex +@tindex islin +@c @starindex +@tindex islinnt +@cindex Linearity testing +The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt} +check if an expression is ``linear,'' i.e., can be written in the form +@cite{a + b x} for some constants @cite{a} and @cite{b}, and some +variable or subformula @cite{x}. The function @samp{islin(f,x)} checks +if formula @cite{f} is linear in @cite{x}, returning 1 if so. For +example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and +@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function +is similar, except that instead of returning 1 it returns the vector +@cite{[a, b, x]}. For the above examples, this vector would be +@cite{[0, 1, x]}, @cite{[0, -1, x]}, @cite{[3, 0, x]}, and +@cite{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin} +generally remain unevaluated for expressions which are not linear, +e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second +argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))} +returns true. + +The @code{linnt} and @code{islinnt} functions perform a similar check, +but require a ``non-trivial'' linear form, which means that the +@cite{b} coefficient must be non-zero. For example, @samp{lin(2,x)} +returns @cite{[2, 0, x]} and @samp{lin(y,x)} returns @cite{[y, 0, x]}, +but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated +(in other words, these formulas are considered to be only ``trivially'' +linear in @cite{x}). + +All four linearity-testing functions allow you to omit the second +argument, in which case the input may be linear in any non-constant +formula. Here, the @cite{a=0}, @cite{b=1} case is also considered +trivial, and only constant values for @cite{a} and @cite{b} are +recognized. Thus, @samp{lin(2 x y)} returns @cite{[0, 2, x y]}, +@samp{lin(2 - x y)} returns @cite{[2, -1, x y]}, and @samp{lin(x y)} +returns @cite{[0, 1, x y]}. The @code{linnt} function would allow the +first two cases but not the third. Also, neither @code{lin} nor +@code{linnt} accept plain constants as linear in the one-argument +case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false. + +@c @starindex +@tindex istrue +The @samp{istrue(a)} function returns 1 if @cite{a} is a nonzero +number or provably nonzero formula, or 0 if @cite{a} is anything else. +Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is +used to make sure they are not evaluated prematurely. (Note that +declarations are used when deciding whether a formula is true; +@code{istrue} returns 1 when @code{dnonzero} would return 1, and +it returns 0 when @code{dnonzero} would return 0 or leave itself +in symbolic form.) + +@node Rewrite Rules, , Logical Operations, Algebra +@section Rewrite Rules + +@noindent +@cindex Rewrite rules +@cindex Transformations +@cindex Pattern matching +@kindex a r +@pindex calc-rewrite +@tindex rewrite +The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes +substitutions in a formula according to a specified pattern or patterns +known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute}) +matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)} +matches only the @code{sin} function applied to the variable @code{x}, +rewrite rules match general kinds of formulas; rewriting using the rule +@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces +it with @code{cos} of that same argument. The only significance of the +name @code{x} is that the same name is used on both sides of the rule. + +Rewrite rules rearrange formulas already in Calc's memory. +@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are +similar to algebraic rewrite rules but operate when new algebraic +entries are being parsed, converting strings of characters into +Calc formulas. + +@menu +* Entering Rewrite Rules:: +* Basic Rewrite Rules:: +* Conditional Rewrite Rules:: +* Algebraic Properties of Rewrite Rules:: +* Other Features of Rewrite Rules:: +* Composing Patterns in Rewrite Rules:: +* Nested Formulas with Rewrite Rules:: +* Multi-Phase Rewrite Rules:: +* Selections with Rewrite Rules:: +* Matching Commands:: +* Automatic Rewrites:: +* Debugging Rewrites:: +* Examples of Rewrite Rules:: +@end menu + +@node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules +@subsection Entering Rewrite Rules + +@noindent +Rewrite rules normally use the ``assignment'' operator +@samp{@var{old} := @var{new}}. +This operator is equivalent to the function call @samp{assign(old, new)}. +The @code{assign} function is undefined by itself in Calc, so an +assignment formula such as a rewrite rule will be left alone by ordinary +Calc commands. But certain commands, like the rewrite system, interpret +assignments in special ways.@refill + +For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace +every occurrence of the sine of something, squared, with one minus the +square of the cosine of that same thing. All by itself as a formula +on the stack it does nothing, but when given to the @kbd{a r} command +it turns that command into a sine-squared-to-cosine-squared converter. + +To specify a set of rules to be applied all at once, make a vector of +rules. + +When @kbd{a r} prompts you to enter the rewrite rules, you can answer +in several ways: + +@enumerate +@item +With a rule: @kbd{f(x) := g(x) RET}. +@item +With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] RET}. +(You can omit the enclosing square brackets if you wish.) +@item +With the name of a variable that contains the rule or rules vector: +@kbd{myrules RET}. +@item +With any formula except a rule, a vector, or a variable name; this +will be interpreted as the @var{old} half of a rewrite rule, +and you will be prompted a second time for the @var{new} half: +@kbd{f(x) @key{RET} g(x) @key{RET}}. +@item +With a blank line, in which case the rule, rules vector, or variable +will be taken from the top of the stack (and the formula to be +rewritten will come from the second-to-top position). +@end enumerate + +If you enter the rules directly (as opposed to using rules stored +in a variable), those rules will be put into the Trail so that you +can retrieve them later. @xref{Trail Commands}. + +It is most convenient to store rules you use often in a variable and +invoke them by giving the variable name. The @kbd{s e} +(@code{calc-edit-variable}) command is an easy way to create or edit a +rule set stored in a variable. You may also wish to use @kbd{s p} +(@code{calc-permanent-variable}) to save your rules permanently; +@pxref{Operations on Variables}.@refill + +Rewrite rules are compiled into a special internal form for faster +matching. If you enter a rule set directly it must be recompiled +every time. If you store the rules in a variable and refer to them +through that variable, they will be compiled once and saved away +along with the variable for later reference. This is another good +reason to store your rules in a variable. + +Calc also accepts an obsolete notation for rules, as vectors +@samp{[@var{old}, @var{new}]}. But because it is easily confused with a +vector of two rules, the use of this notation is no longer recommended. + +@node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules +@subsection Basic Rewrite Rules + +@noindent +To match a particular formula @cite{x} with a particular rewrite rule +@samp{@var{old} := @var{new}}, Calc compares the structure of @cite{x} with +the structure of @var{old}. Variables that appear in @var{old} are +treated as @dfn{meta-variables}; the corresponding positions in @cite{x} +may contain any sub-formulas. For example, the pattern @samp{f(x,y)} +would match the expression @samp{f(12, a+1)} with the meta-variable +@samp{x} corresponding to 12 and with @samp{y} corresponding to +@samp{a+1}. However, this pattern would not match @samp{f(12)} or +@samp{g(12, a+1)}, since there is no assignment of the meta-variables +that will make the pattern match these expressions. Notice that if +the pattern is a single meta-variable, it will match any expression. + +If a given meta-variable appears more than once in @var{old}, the +corresponding sub-formulas of @cite{x} must be identical. Thus +the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and +@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}. +(@xref{Conditional Rewrite Rules}, for a way to match the latter.) + +Things other than variables must match exactly between the pattern +and the target formula. To match a particular variable exactly, use +the pseudo-function @samp{quote(v)} in the pattern. For example, the +pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or +@samp{sin(a)+y}. + +The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi}, +@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match +literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like +@samp{sin(d + quote(e) + f)}. + +If the @var{old} pattern is found to match a given formula, that +formula is replaced by @var{new}, where any occurrences in @var{new} +of meta-variables from the pattern are replaced with the sub-formulas +that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)} +to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}. + +The normal @kbd{a r} command applies rewrite rules over and over +throughout the target formula until no further changes are possible +(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one +change at a time. + +@node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules +@subsection Conditional Rewrite Rules + +@noindent +A rewrite rule can also be @dfn{conditional}, written in the form +@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete +form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part +is present in the +rule, this is an additional condition that must be satisfied before +the rule is accepted. Once @var{old} has been successfully matched +to the target expression, @var{cond} is evaluated (with all the +meta-variables substituted for the values they matched) and simplified +with @kbd{a s} (@code{calc-simplify}). If the result is a nonzero +number or any other object known to be nonzero (@pxref{Declarations}), +the rule is accepted. If the result is zero or if it is a symbolic +formula that is not known to be nonzero, the rule is rejected. +@xref{Logical Operations}, for a number of functions that return +1 or 0 according to the results of various tests.@refill + +For example, the formula @samp{n > 0} simplifies to 1 or 0 if @cite{n} +is replaced by a positive or nonpositive number, respectively (or if +@cite{n} has been declared to be positive or nonpositive). Thus, +the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to +@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)} +(assuming no outstanding declarations for @cite{a}). In the case of +@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in +the case of @samp{f(12, a+1)}, the condition merely cannot be shown +to be satisfied, but that is enough to reject the rule. + +While Calc will use declarations to reason about variables in the +formula being rewritten, declarations do not apply to meta-variables. +For example, the rule @samp{f(a) := g(a+1)} will match for any values +of @samp{a}, such as complex numbers, vectors, or formulas, even if +@samp{a} has been declared to be real or scalar. If you want the +meta-variable @samp{a} to match only literal real numbers, use +@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only +reals and formulas which are provably real, use @samp{dreal(a)} as +the condition. + +The @samp{::} operator is a shorthand for the @code{condition} +function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to +the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}. + +If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3} +or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent. + +It is also possible to embed conditions inside the pattern: +@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational +convenience, though; where a condition appears in a rule has no +effect on when it is tested. The rewrite-rule compiler automatically +decides when it is best to test each condition while a rule is being +matched. + +Certain conditions are handled as special cases by the rewrite rule +system and are tested very efficiently: Where @cite{x} is any +meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)}, +@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @cite{y} +is either a constant or another meta-variable and @samp{>=} may be +replaced by any of the six relational operators, and @samp{x % a = b} +where @cite{a} and @cite{b} are constants. Other conditions, like +@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check +since Calc must bring the whole evaluator and simplifier into play. + +An interesting property of @samp{::} is that neither of its arguments +will be touched by Calc's default simplifications. This is important +because conditions often are expressions that cannot safely be +evaluated early. For example, the @code{typeof} function never +remains in symbolic form; entering @samp{typeof(a)} will put the +number 100 (the type code for variables like @samp{a}) on the stack. +But putting the condition @samp{... :: typeof(a) = 6} on the stack +is safe since @samp{::} prevents the @code{typeof} from being +evaluated until the condition is actually used by the rewrite system. + +Since @samp{::} protects its lefthand side, too, you can use a dummy +condition to protect a rule that must itself not evaluate early. +For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on +the stack because it will immediately evaluate to @samp{a(f,x) := f(x)}, +where the meta-variable-ness of @code{f} on the righthand side has been +lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course +the condition @samp{1} is always true (nonzero) so it has no effect on +the functioning of the rule. (The rewrite compiler will ensure that +it doesn't even impact the speed of matching the rule.) + +@node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules +@subsection Algebraic Properties of Rewrite Rules + +@noindent +The rewrite mechanism understands the algebraic properties of functions +like @samp{+} and @samp{*}. In particular, pattern matching takes +the associativity and commutativity of the following functions into +account: + +@smallexample ++ - * = != && || and or xor vint vunion vxor gcd lcm max min beta +@end smallexample + +For example, the rewrite rule: + +@example +a x + b x := (a + b) x +@end example + +@noindent +will match formulas of the form, + +@example +a x + b x, x a + x b, a x + x b, x a + b x +@end example + +Rewrites also understand the relationship between the @samp{+} and @samp{-} +operators. The above rewrite rule will also match the formulas, + +@example +a x - b x, x a - x b, a x - x b, x a - b x +@end example + +@noindent +by matching @samp{b} in the pattern to @samp{-b} from the formula. + +Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this +pattern will check all pairs of terms for possible matches. The rewrite +will take whichever suitable pair it discovers first. + +In general, a pattern using an associative operator like @samp{a + b} +will try @i{2 n} different ways to match a sum of @i{n} terms +like @samp{x + y + z - w}. First, @samp{a} is matched against each +of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b} +being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc. +If none of these succeed, then @samp{b} is matched against each of the +four terms with @samp{a} matching the remainder. Half-and-half matches, +like @samp{(x + y) + (z - w)}, are not tried. + +Note that @samp{*} is not commutative when applied to matrices, but +rewrite rules pretend that it is. If you type @kbd{m v} to enable +matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*} +literally, ignoring its usual commutativity property. (In the +current implementation, the associativity also vanishes---it is as +if the pattern had been enclosed in a @code{plain} marker; see below.) +If you are applying rewrites to formulas with matrices, it's best to +enable matrix mode first to prevent algebraically incorrect rewrites +from occurring. + +The pattern @samp{-x} will actually match any expression. For example, +the rule + +@example +f(-x) := -f(x) +@end example + +@noindent +will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use +a @code{plain} marker as described below, or add a @samp{negative(x)} +condition. The @code{negative} function is true if its argument +``looks'' negative, for example, because it is a negative number or +because it is a formula like @samp{-x}. The new rule using this +condition is: + +@example +f(x) := -f(-x) :: negative(x) @r{or, equivalently,} +f(-x) := -f(x) :: negative(-x) +@end example + +In the same way, the pattern @samp{x - y} will match the sum @samp{a + b} +by matching @samp{y} to @samp{-b}. + +The pattern @samp{a b} will also match the formula @samp{x/y} if +@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x} +will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or +@samp{(a + 1:2) x}, depending on the current fraction mode). + +Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and +@samp{^}. For example, the pattern @samp{f(a b)} will not match +@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even +though conceivably these patterns could match with @samp{a = b = x}. +Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a +constant, even though it could be considered to match with @samp{a = x} +and @samp{b = 1/y}. The reasons are partly for efficiency, and partly +because while few mathematical operations are substantively different +for addition and subtraction, often it is preferable to treat the cases +of multiplication, division, and integer powers separately. + +Even more subtle is the rule set + +@example +[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ] +@end example + +@noindent +attempting to match @samp{f(x) - f(y)}. You might think that Calc +will view this subtraction as @samp{f(x) + (-f(y))} and then apply +the above two rules in turn, but actually this will not work because +Calc only does this when considering rules for @samp{+} (like the +first rule in this set). So it will see first that @samp{f(x) + (-f(y))} +does not match @samp{f(a) + f(b)} for any assignments of the +meta-variables, and then it will see that @samp{f(x) - f(y)} does +not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc +tries only one rule at a time, it will not be able to rewrite +@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)} +rule will have to be added. + +Another thing patterns will @emph{not} do is break up complex numbers. +The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas +involving the special constant @samp{i} (such as @samp{3 - 4 i}), but +it will not match actual complex numbers like @samp{(3, -4)}. A version +of the above rule for complex numbers would be + +@example +myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0 +@end example + +@noindent +(Because the @code{re} and @code{im} functions understand the properties +of the special constant @samp{i}, this rule will also work for +@samp{3 - 4 i}. In fact, this particular rule would probably be better +without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the +righthand side of the rule will still give the correct answer for the +conjugate of a real number.) + +It is also possible to specify optional arguments in patterns. The rule + +@example +opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d) +@end example + +@noindent +will match the formula + +@example +5 (x^2 - 4) + 3 x +@end example + +@noindent +in a fairly straightforward manner, but it will also match reduced +formulas like + +@example +x + x^2, 2(x + 1) - x, x + x +@end example + +@noindent +producing, respectively, + +@example +f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0) +@end example + +(The latter two formulas can be entered only if default simplifications +have been turned off with @kbd{m O}.) + +The default value for a term of a sum is zero. The default value +for a part of a product, for a power, or for the denominator of a +quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b} +with @samp{a = -1}. + +In particular, the distributive-law rule can be refined to + +@example +opt(a) x + opt(b) x := (a + b) x +@end example + +@noindent +so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}. + +The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which +are linear in @samp{x}. You can also use the @code{lin} and @code{islin} +functions with rewrite conditions to test for this; @pxref{Logical +Operations}. These functions are not as convenient to use in rewrite +rules, but they recognize more kinds of formulas as linear: +@samp{x/z} is considered linear with @cite{b = 1/z} by @code{lin}, +but it will not match the above pattern because that pattern calls +for a multiplication, not a division. + +As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2} +by 1, + +@example +sin(x)^2 + cos(x)^2 := 1 +@end example + +@noindent +misses many cases because the sine and cosine may both be multiplied by +an equal factor. Here's a more successful rule: + +@example +opt(a) sin(x)^2 + opt(a) cos(x)^2 := a +@end example + +Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2} +because one @cite{a} would have ``matched'' 1 while the other matched 6. + +Calc automatically converts a rule like + +@example +f(x-1, x) := g(x) +@end example + +@noindent +into the form + +@example +f(temp, x) := g(x) :: temp = x-1 +@end example + +@noindent +(where @code{temp} stands for a new, invented meta-variable that +doesn't actually have a name). This modified rule will successfully +match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7, +respectively, then verifying that they differ by one even though +@samp{6} does not superficially look like @samp{x-1}. + +However, Calc does not solve equations to interpret a rule. The +following rule, + +@example +f(x-1, x+1) := g(x) +@end example + +@noindent +will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)} +but not @samp{f(6, 8)}. Calc always interprets at least one occurrence +of a variable by literal matching. If the variable appears ``isolated'' +then Calc is smart enough to use it for literal matching. But in this +last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp) +:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an +actual ``something-minus-one'' in the target formula. + +A successful way to write this would be @samp{f(x, x+2) := g(x+1)}. +You could make this resemble the original form more closely by using +@code{let} notation, which is described in the next section: + +@example +f(xm1, x+1) := g(x) :: let(x := xm1+1) +@end example + +Calc does this rewriting or ``conditionalizing'' for any sub-pattern +which involves only the functions in the following list, operating +only on constants and meta-variables which have already been matched +elsewhere in the pattern. When matching a function call, Calc is +careful to match arguments which are plain variables before arguments +which are calls to any of the functions below, so that a pattern like +@samp{f(x-1, x)} can be conditionalized even though the isolated +@samp{x} comes after the @samp{x-1}. + +@smallexample ++ - * / \ % ^ abs sign round rounde roundu trunc floor ceil +max min re im conj arg +@end smallexample + +You can suppress all of the special treatments described in this +section by surrounding a function call with a @code{plain} marker. +This marker causes the function call which is its argument to be +matched literally, without regard to commutativity, associativity, +negation, or conditionalization. When you use @code{plain}, the +``deep structure'' of the formula being matched can show through. +For example, + +@example +plain(a - a b) := f(a, b) +@end example + +@noindent +will match only literal subtractions. However, the @code{plain} +marker does not affect its arguments' arguments. In this case, +commutativity and associativity is still considered while matching +the @w{@samp{a b}} sub-pattern, so the whole pattern will match +@samp{x - y x} as well as @samp{x - x y}. We could go still +further and use + +@example +plain(a - plain(a b)) := f(a, b) +@end example + +@noindent +which would do a completely strict match for the pattern. + +By contrast, the @code{quote} marker means that not only the +function name but also the arguments must be literally the same. +The above pattern will match @samp{x - x y} but + +@example +quote(a - a b) := f(a, b) +@end example + +@noindent +will match only the single formula @samp{a - a b}. Also, + +@example +quote(a - quote(a b)) := f(a, b) +@end example + +@noindent +will match only @samp{a - quote(a b)}---probably not the desired +effect! + +A certain amount of algebra is also done when substituting the +meta-variables on the righthand side of a rule. For example, +in the rule + +@example +a + f(b) := f(a + b) +@end example + +@noindent +matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if +taken literally, but the rewrite mechanism will simplify the +righthand side to @samp{f(x - y)} automatically. (Of course, +the default simplifications would do this anyway, so this +special simplification is only noticeable if you have turned the +default simplifications off.) This rewriting is done only when +a meta-variable expands to a ``negative-looking'' expression. +If this simplification is not desirable, you can use a @code{plain} +marker on the righthand side: + +@example +a + f(b) := f(plain(a + b)) +@end example + +@noindent +In this example, we are still allowing the pattern-matcher to +use all the algebra it can muster, but the righthand side will +always simplify to a literal addition like @samp{f((-y) + x)}. + +@node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules +@subsection Other Features of Rewrite Rules + +@noindent +Certain ``function names'' serve as markers in rewrite rules. +Here is a complete list of these markers. First are listed the +markers that work inside a pattern; then come the markers that +work in the righthand side of a rule. + +@c @starindex +@tindex import +One kind of marker, @samp{import(x)}, takes the place of a whole +rule. Here @cite{x} is the name of a variable containing another +rule set; those rules are ``spliced into'' the rule set that +imports them. For example, if @samp{[f(a+b) := f(a) + f(b), +f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF}, +then the rule set @samp{[f(0) := 0, import(linearF)]} will apply +all three rules. It is possible to modify the imported rules +slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports +the rule set @cite{x} with all occurrences of @c{$v_1$} +@cite{v1}, as either +a variable name or a function name, replaced with @c{$x_1$} +@cite{x1} and +so on. (If @c{$v_1$} +@cite{v1} is used as a function name, then @c{$x_1$} +@cite{x1} +must be either a function name itself or a @w{@samp{< >}} nameless +function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0, +import(linearF, f, g)]} applies the linearity rules to the function +@samp{g} instead of @samp{f}. Imports can be nested, but the +import-with-renaming feature may fail to rename sub-imports properly. + +The special functions allowed in patterns are: + +@table @samp +@item quote(x) +@c @starindex +@tindex quote +This pattern matches exactly @cite{x}; variable names in @cite{x} are +not interpreted as meta-variables. The only flexibility is that +numbers are compared for numeric equality, so that the pattern +@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}. +(Numbers are always treated this way by the rewrite mechanism: +The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}. +The rewrite may produce either @samp{g(12)} or @samp{g(12.0)} +as a result in this case.) + +@item plain(x) +@c @starindex +@tindex plain +Here @cite{x} must be a function call @samp{f(x1,x2,@dots{})}. This +pattern matches a call to function @cite{f} with the specified +argument patterns. No special knowledge of the properties of the +function @cite{f} is used in this case; @samp{+} is not commutative or +associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}} +are treated as patterns. If you wish them to be treated ``plainly'' +as well, you must enclose them with more @code{plain} markers: +@samp{plain(plain(@w{-a}) + plain(b c))}. + +@item opt(x,def) +@c @starindex +@tindex opt +Here @cite{x} must be a variable name. This must appear as an +argument to a function or an element of a vector; it specifies that +the argument or element is optional. +As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||}, +or as the second argument to @samp{/} or @samp{^}, the value @var{def} +may be omitted. The pattern @samp{x + opt(y)} matches a sum by +binding one summand to @cite{x} and the other to @cite{y}, and it +matches anything else by binding the whole expression to @cite{x} and +zero to @cite{y}. The other operators above work similarly.@refill + +For general miscellanous functions, the default value @code{def} +must be specified. Optional arguments are dropped starting with +the rightmost one during matching. For example, the pattern +@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)}, +or @samp{f(a,b,c)}. Default values of zero and @cite{b} are +supplied in this example for the omitted arguments. Note that +the literal variable @cite{b} will be the default in the latter +case, @emph{not} the value that matched the meta-variable @cite{b}. +In other words, the default @var{def} is effectively quoted. + +@item condition(x,c) +@c @starindex +@tindex condition +@tindex :: +This matches the pattern @cite{x}, with the attached condition +@cite{c}. It is the same as @samp{x :: c}. + +@item pand(x,y) +@c @starindex +@tindex pand +@tindex &&& +This matches anything that matches both pattern @cite{x} and +pattern @cite{y}. It is the same as @samp{x &&& y}. +@pxref{Composing Patterns in Rewrite Rules}. + +@item por(x,y) +@c @starindex +@tindex por +@tindex ||| +This matches anything that matches either pattern @cite{x} or +pattern @cite{y}. It is the same as @w{@samp{x ||| y}}. + +@item pnot(x) +@c @starindex +@tindex pnot +@tindex !!! +This matches anything that does not match pattern @cite{x}. +It is the same as @samp{!!! x}. + +@item cons(h,t) +@c @mindex cons +@tindex cons (rewrites) +This matches any vector of one or more elements. The first +element is matched to @cite{h}; a vector of the remaining +elements is matched to @cite{t}. Note that vectors of fixed +length can also be matched as actual vectors: The rule +@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent +to the rule @samp{[a,b] := [a+b]}. + +@item rcons(t,h) +@c @mindex rcons +@tindex rcons (rewrites) +This is like @code{cons}, except that the @emph{last} element +is matched to @cite{h}, with the remaining elements matched +to @cite{t}. + +@item apply(f,args) +@c @mindex apply +@tindex apply (rewrites) +This matches any function call. The name of the function, in +the form of a variable, is matched to @cite{f}. The arguments +of the function, as a vector of zero or more objects, are +matched to @samp{args}. Constants, variables, and vectors +do @emph{not} match an @code{apply} pattern. For example, +@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)} +matches any call to the function @samp{f}, @samp{apply(f,[a,b])} +matches any function call with exactly two arguments, and +@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call +to the function @samp{f} with two or more arguments. Another +way to implement the latter, if the rest of the rule does not +need to refer to the first two arguments of @samp{f} by name, +would be @samp{apply(quote(f), x :: vlen(x) >= 2)}. +Here's a more interesting sample use of @code{apply}: + +@example +apply(f,[x+n]) := n + apply(f,[x]) + :: in(f, [floor,ceil,round,trunc]) :: integer(n) +@end example + +Note, however, that this will be slower to match than a rule +set with four separate rules. The reason is that Calc sorts +the rules of a rule set according to top-level function name; +if the top-level function is @code{apply}, Calc must try the +rule for every single formula and sub-formula. If the top-level +function in the pattern is, say, @code{floor}, then Calc invokes +the rule only for sub-formulas which are calls to @code{floor}. + +Formulas normally written with operators like @code{+} are still +considered function calls: @code{apply(f,x)} matches @samp{a+b} +with @samp{f = add}, @samp{x = [a,b]}. + +You must use @code{apply} for meta-variables with function names +on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)} +is @emph{not} correct, because it rewrites @samp{spam(6)} into +@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}. +Also note that you will have to use no-simplify (@kbd{m O}) +mode when entering this rule so that the @code{apply} isn't +evaluated immediately to get the new rule @samp{f(x) := f(x+1)}. +Or, use @kbd{s e} to enter the rule without going through the stack, +or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}. +@xref{Conditional Rewrite Rules}. + +@item select(x) +@c @starindex +@tindex select +This is used for applying rules to formulas with selections; +@pxref{Selections with Rewrite Rules}. +@end table + +Special functions for the righthand sides of rules are: + +@table @samp +@item quote(x) +The notation @samp{quote(x)} is changed to @samp{x} when the +righthand side is used. As far as the rewrite rule is concerned, +@code{quote} is invisible. However, @code{quote} has the special +property in Calc that its argument is not evaluated. Thus, +while it will not work to put the rule @samp{t(a) := typeof(a)} +on the stack because @samp{typeof(a)} is evaluated immediately +to produce @samp{t(a) := 100}, you can use @code{quote} to +protect the righthand side: @samp{t(a) := quote(typeof(a))}. +(@xref{Conditional Rewrite Rules}, for another trick for +protecting rules from evaluation.) + +@item plain(x) +Special properties of and simplifications for the function call +@cite{x} are not used. One interesting case where @code{plain} +is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a +shorthand notation for the @code{quote} function. This rule will +not work as shown; instead of replacing @samp{q(foo)} with +@samp{quote(foo)}, it will replace it with @samp{foo}! The correct +rule would be @samp{q(x) := plain(quote(x))}. + +@item cons(h,t) +Where @cite{t} is a vector, this is converted into an expanded +vector during rewrite processing. Note that @code{cons} is a regular +Calc function which normally does this anyway; the only way @code{cons} +is treated specially by rewrites is that @code{cons} on the righthand +side of a rule will be evaluated even if default simplifications +have been turned off. + +@item rcons(t,h) +Analogous to @code{cons} except putting @cite{h} at the @emph{end} of +the vector @cite{t}. + +@item apply(f,args) +Where @cite{f} is a variable and @var{args} is a vector, this +is converted to a function call. Once again, note that @code{apply} +is also a regular Calc function. + +@item eval(x) +@c @starindex +@tindex eval +The formula @cite{x} is handled in the usual way, then the +default simplifications are applied to it even if they have +been turned off normally. This allows you to treat any function +similarly to the way @code{cons} and @code{apply} are always +treated. However, there is a slight difference: @samp{cons(2+3, [])} +with default simplifications off will be converted to @samp{[2+3]}, +whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}. + +@item evalsimp(x) +@c @starindex +@tindex evalsimp +The formula @cite{x} has meta-variables substituted in the usual +way, then algebraically simplified as if by the @kbd{a s} command. + +@item evalextsimp(x) +@c @starindex +@tindex evalextsimp +The formula @cite{x} has meta-variables substituted in the normal +way, then ``extendedly'' simplified as if by the @kbd{a e} command. + +@item select(x) +@xref{Selections with Rewrite Rules}. +@end table + +There are also some special functions you can use in conditions. + +@table @samp +@item let(v := x) +@c @starindex +@tindex let +The expression @cite{x} is evaluated with meta-variables substituted. +The @kbd{a s} command's simplifications are @emph{not} applied by +default, but @cite{x} can include calls to @code{evalsimp} or +@code{evalextsimp} as described above to invoke higher levels +of simplification. The +result of @cite{x} is then bound to the meta-variable @cite{v}. As +usual, if this meta-variable has already been matched to something +else the two values must be equal; if the meta-variable is new then +it is bound to the result of the expression. This variable can then +appear in later conditions, and on the righthand side of the rule. +In fact, @cite{v} may be any pattern in which case the result of +evaluating @cite{x} is matched to that pattern, binding any +meta-variables that appear in that pattern. Note that @code{let} +can only appear by itself as a condition, or as one term of an +@samp{&&} which is a whole condition: It cannot be inside +an @samp{||} term or otherwise buried.@refill + +The alternate, equivalent form @samp{let(v, x)} is also recognized. +Note that the use of @samp{:=} by @code{let}, while still being +assignment-like in character, is unrelated to the use of @samp{:=} +in the main part of a rewrite rule. + +As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)} +replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if +that inverse exists and is constant. For example, if @samp{a} is a +singular matrix the operation @samp{1/a} is left unsimplified and +@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix +then the rule succeeds. Without @code{let} there would be no way +to express this rule that didn't have to invert the matrix twice. +Note that, because the meta-variable @samp{ia} is otherwise unbound +in this rule, the @code{let} condition itself always ``succeeds'' +because no matter what @samp{1/a} evaluates to, it can successfully +be bound to @code{ia}.@refill + +Here's another example, for integrating cosines of linear +terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}. +The @code{lin} function returns a 3-vector if its argument is linear, +or leaves itself unevaluated if not. But an unevaluated @code{lin} +call will not match the 3-vector on the lefthand side of the @code{let}, +so this @code{let} both verifies that @code{y} is linear, and binds +the coefficients @code{a} and @code{b} for use elsewhere in the rule. +(It would have been possible to use @samp{sin(a x + b)/b} for the +righthand side instead, but using @samp{sin(y)/b} avoids gratuitous +rearrangement of the argument of the sine.)@refill + +@c @starindex +@tindex ierf +Similarly, here is a rule that implements an inverse-@code{erf} +function. It uses @code{root} to search for a solution. If +@code{root} succeeds, it will return a vector of two numbers +where the first number is the desired solution. If no solution +is found, @code{root} remains in symbolic form. So we use +@code{let} to check that the result was indeed a vector. + +@example +ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5)) +@end example + +@item matches(v,p) +The meta-variable @var{v}, which must already have been matched +to something elsewhere in the rule, is compared against pattern +@var{p}. Since @code{matches} is a standard Calc function, it +can appear anywhere in a condition. But if it appears alone or +as a term of a top-level @samp{&&}, then you get the special +extra feature that meta-variables which are bound to things +inside @var{p} can be used elsewhere in the surrounding rewrite +rule. + +The only real difference between @samp{let(p := v)} and +@samp{matches(v, p)} is that the former evaluates @samp{v} using +the default simplifications, while the latter does not. + +@item remember +@vindex remember +This is actually a variable, not a function. If @code{remember} +appears as a condition in a rule, then when that rule succeeds +the original expression and rewritten expression are added to the +front of the rule set that contained the rule. If the rule set +was not stored in a variable, @code{remember} is ignored. The +lefthand side is enclosed in @code{quote} in the added rule if it +contains any variables. + +For example, the rule @samp{f(n) := n f(n-1) :: remember} applied +to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front +of the rule set. The rule set @code{EvalRules} works slightly +differently: There, the evaluation of @samp{f(6)} will complete before +the result is added to the rule set, in this case as @samp{f(7) := 5040}. +Thus @code{remember} is most useful inside @code{EvalRules}. + +It is up to you to ensure that the optimization performed by +@code{remember} is safe. For example, the rule @samp{foo(n) := n +:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is +the function equivalent of the @kbd{=} command); if the variable +@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will +be added to the rule set and will continue to operate even if +@code{eatfoo} is later changed to 0. + +@item remember(c) +@c @starindex +@tindex remember +Remember the match as described above, but only if condition @cite{c} +is true. For example, @samp{remember(n % 4 = 0)} in the above factorial +rule remembers only every fourth result. Note that @samp{remember(1)} +is equivalent to @samp{remember}, and @samp{remember(0)} has no effect. +@end table + +@node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules +@subsection Composing Patterns in Rewrite Rules + +@noindent +There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!}, +that combine rewrite patterns to make larger patterns. The +combinations are ``and,'' ``or,'' and ``not,'' respectively, and +these operators are the pattern equivalents of @samp{&&}, @samp{||} +and @samp{!} (which operate on zero-or-nonzero logical values). + +Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic +form by all regular Calc features; they have special meaning only in +the context of rewrite rule patterns. + +The pattern @samp{@var{p1} &&& @var{p2}} matches anything that +matches both @var{p1} and @var{p2}. One especially useful case is +when one of @var{p1} or @var{p2} is a meta-variable. For example, +here is a rule that operates on error forms: + +@example +f(x &&& a +/- b, x) := g(x) +@end example + +This does the same thing, but is arguably simpler than, the rule + +@example +f(a +/- b, a +/- b) := g(a +/- b) +@end example + +@c @starindex +@tindex ends +Here's another interesting example: + +@example +ends(cons(a, x) &&& rcons(y, b)) := [a, b] +@end example + +@noindent +which effectively clips out the middle of a vector leaving just +the first and last elements. This rule will change a one-element +vector @samp{[a]} to @samp{[a, a]}. The similar rule + +@example +ends(cons(a, rcons(y, b))) := [a, b] +@end example + +@noindent +would do the same thing except that it would fail to match a +one-element vector. + +@tex +\bigskip +@end tex + +The pattern @samp{@var{p1} ||| @var{p2}} matches anything that +matches either @var{p1} or @var{p2}. Calc first tries matching +against @var{p1}; if that fails, it goes on to try @var{p2}. + +@c @starindex +@tindex curve +A simple example of @samp{|||} is + +@example +curve(inf ||| -inf) := 0 +@end example + +@noindent +which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero. + +Here is a larger example: + +@example +log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b) +@end example + +This matches both generalized and natural logarithms in a single rule. +Note that the @samp{::} term must be enclosed in parentheses because +that operator has lower precedence than @samp{|||} or @samp{:=}. + +(In practice this rule would probably include a third alternative, +omitted here for brevity, to take care of @code{log10}.) + +While Calc generally treats interior conditions exactly the same as +conditions on the outside of a rule, it does guarantee that if all the +variables in the condition are special names like @code{e}, or already +bound in the pattern to which the condition is attached (say, if +@samp{a} had appeared in this condition), then Calc will process this +condition right after matching the pattern to the left of the @samp{::}. +Thus, we know that @samp{b} will be bound to @samp{e} only if the +@code{ln} branch of the @samp{|||} was taken. + +Note that this rule was careful to bind the same set of meta-variables +on both sides of the @samp{|||}. Calc does not check this, but if +you bind a certain meta-variable only in one branch and then use that +meta-variable elsewhere in the rule, results are unpredictable: + +@example +f(a,b) ||| g(b) := h(a,b) +@end example + +Here if the pattern matches @samp{g(17)}, Calc makes no promises about +the value that will be substituted for @samp{a} on the righthand side. + +@tex +\bigskip +@end tex + +The pattern @samp{!!! @var{pat}} matches anything that does not +match @var{pat}. Any meta-variables that are bound while matching +@var{pat} remain unbound outside of @var{pat}. + +For example, + +@example +f(x &&& !!! a +/- b, !!![]) := g(x) +@end example + +@noindent +converts @code{f} whose first argument is anything @emph{except} an +error form, and whose second argument is not the empty vector, into +a similar call to @code{g} (but without the second argument). + +If we know that the second argument will be a vector (empty or not), +then an equivalent rule would be: + +@example +f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0 +@end example + +@noindent +where of course 7 is the @code{typeof} code for error forms. +Another final condition, that works for any kind of @samp{y}, +would be @samp{!istrue(y == [])}. (The @code{istrue} function +returns an explicit 0 if its argument was left in symbolic form; +plain @samp{!(y == [])} or @samp{y != []} would not work to replace +@samp{!!![]} since these would be left unsimplified, and thus cause +the rule to fail, if @samp{y} was something like a variable name.) + +It is possible for a @samp{!!!} to refer to meta-variables bound +elsewhere in the pattern. For example, + +@example +f(a, !!!a) := g(a) +@end example + +@noindent +matches any call to @code{f} with different arguments, changing +this to @code{g} with only the first argument. + +If a function call is to be matched and one of the argument patterns +contains a @samp{!!!} somewhere inside it, that argument will be +matched last. Thus + +@example +f(!!!a, a) := g(a) +@end example + +@noindent +will be careful to bind @samp{a} to the second argument of @code{f} +before testing the first argument. If Calc had tried to match the +first argument of @code{f} first, the results would have been +disasterous: Since @code{a} was unbound so far, the pattern @samp{a} +would have matched anything at all, and the pattern @samp{!!!a} +therefore would @emph{not} have matched anything at all! + +@node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules +@subsection Nested Formulas with Rewrite Rules + +@noindent +When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from +the top of the stack and attempts to match any of the specified rules +to any part of the expression, starting with the whole expression +and then, if that fails, trying deeper and deeper sub-expressions. +For each part of the expression, the rules are tried in the order +they appear in the rules vector. The first rule to match the first +sub-expression wins; it replaces the matched sub-expression according +to the @var{new} part of the rule. + +Often, the rule set will match and change the formula several times. +The top-level formula is first matched and substituted repeatedly until +it no longer matches the pattern; then, sub-formulas are tried, and +so on. Once every part of the formula has gotten its chance, the +rewrite mechanism starts over again with the top-level formula +(in case a substitution of one of its arguments has caused it again +to match). This continues until no further matches can be made +anywhere in the formula. + +It is possible for a rule set to get into an infinite loop. The +most obvious case, replacing a formula with itself, is not a problem +because a rule is not considered to ``succeed'' unless the righthand +side actually comes out to something different than the original +formula or sub-formula that was matched. But if you accidentally +had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse +@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would +run forever switching a formula back and forth between the two +forms. + +To avoid disaster, Calc normally stops after 100 changes have been +made to the formula. This will be enough for most multiple rewrites, +but it will keep an endless loop of rewrites from locking up the +computer forever. (On most systems, you can also type @kbd{C-g} to +halt any Emacs command prematurely.) + +To change this limit, give a positive numeric prefix argument. +In particular, @kbd{M-1 a r} applies only one rewrite at a time, +useful when you are first testing your rule (or just if repeated +rewriting is not what is called for by your application). + +@c @starindex +@c @mindex iter@idots +@tindex iterations +You can also put a ``function call'' @samp{iterations(@var{n})} +in place of a rule anywhere in your rules vector (but usually at +the top). Then, @var{n} will be used instead of 100 as the default +number of iterations for this rule set. You can use +@samp{iterations(inf)} if you want no iteration limit by default. +A prefix argument will override the @code{iterations} limit in the +rule set. + +@example +[ iterations(1), + f(x) := f(x+1) ] +@end example + +More precisely, the limit controls the number of ``iterations,'' +where each iteration is a successful matching of a rule pattern whose +righthand side, after substituting meta-variables and applying the +default simplifications, is different from the original sub-formula +that was matched. + +A prefix argument of zero sets the limit to infinity. Use with caution! + +Given a negative numeric prefix argument, @kbd{a r} will match and +substitute the top-level expression up to that many times, but +will not attempt to match the rules to any sub-expressions. + +In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})} +does a rewriting operation. Here @var{expr} is the expression +being rewritten, @var{rules} is the rule, vector of rules, or +variable containing the rules, and @var{n} is the optional +iteration limit, which may be a positive integer, a negative +integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted +the @code{iterations} value from the rule set is used; if both +are omitted, 100 is used. + +@node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules +@subsection Multi-Phase Rewrite Rules + +@noindent +It is possible to separate a rewrite rule set into several @dfn{phases}. +During each phase, certain rules will be enabled while certain others +will be disabled. A @dfn{phase schedule} controls the order in which +phases occur during the rewriting process. + +@c @starindex +@tindex phase +@vindex all +If a call to the marker function @code{phase} appears in the rules +vector in place of a rule, all rules following that point will be +members of the phase(s) identified in the arguments to @code{phase}. +Phases are given integer numbers. The markers @samp{phase()} and +@samp{phase(all)} both mean the following rules belong to all phases; +this is the default at the start of the rule set. + +If you do not explicitly schedule the phases, Calc sorts all phase +numbers that appear in the rule set and executes the phases in +ascending order. For example, the rule set + +@group +@example +[ f0(x) := g0(x), + phase(1), + f1(x) := g1(x), + phase(2), + f2(x) := g2(x), + phase(3), + f3(x) := g3(x), + phase(1,2), + f4(x) := g4(x) ] +@end example +@end group + +@noindent +has three phases, 1 through 3. Phase 1 consists of the @code{f0}, +@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of +@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0} +and @code{f3}. + +When Calc rewrites a formula using this rule set, it first rewrites +the formula using only the phase 1 rules until no further changes are +possible. Then it switches to the phase 2 rule set and continues +until no further changes occur, then finally rewrites with phase 3. +When no more phase 3 rules apply, rewriting finishes. (This is +assuming @kbd{a r} with a large enough prefix argument to allow the +rewriting to run to completion; the sequence just described stops +early if the number of iterations specified in the prefix argument, +100 by default, is reached.) + +During each phase, Calc descends through the nested levels of the +formula as described previously. (@xref{Nested Formulas with Rewrite +Rules}.) Rewriting starts at the top of the formula, then works its +way down to the parts, then goes back to the top and works down again. +The phase 2 rules do not begin until no phase 1 rules apply anywhere +in the formula. + +@c @starindex +@tindex schedule +A @code{schedule} marker appearing in the rule set (anywhere, but +conventionally at the top) changes the default schedule of phases. +In the simplest case, @code{schedule} has a sequence of phase numbers +for arguments; each phase number is invoked in turn until the +arguments to @code{schedule} are exhausted. Thus adding +@samp{schedule(3,2,1)} at the top of the above rule set would +reverse the order of the phases; @samp{schedule(1,2,3)} would have +no effect since this is the default schedule; and @samp{schedule(1,2,1,3)} +would give phase 1 a second chance after phase 2 has completed, before +moving on to phase 3. + +Any argument to @code{schedule} can instead be a vector of phase +numbers (or even of sub-vectors). Then the sub-sequence of phases +described by the vector are tried repeatedly until no change occurs +in any phase in the sequence. For example, @samp{schedule([1, 2], 3)} +tries phase 1, then phase 2, then, if either phase made any changes +to the formula, repeats these two phases until they can make no +further progress. Finally, it goes on to phase 3 for finishing +touches. + +Also, items in @code{schedule} can be variable names as well as +numbers. A variable name is interpreted as the name of a function +to call on the whole formula. For example, @samp{schedule(1, simplify)} +says to apply the phase-1 rules (presumably, all of them), then to +call @code{simplify} which is the function name equivalent of @kbd{a s}. +Likewise, @samp{schedule([1, simplify])} says to alternate between +phase 1 and @kbd{a s} until no further changes occur. + +Phases can be used purely to improve efficiency; if it is known that +a certain group of rules will apply only at the beginning of rewriting, +and a certain other group will apply only at the end, then rewriting +will be faster if these groups are identified as separate phases. +Once the phase 1 rules are done, Calc can put them aside and no longer +spend any time on them while it works on phase 2. + +There are also some problems that can only be solved with several +rewrite phases. For a real-world example of a multi-phase rule set, +examine the set @code{FitRules}, which is used by the curve-fitting +command to convert a model expression to linear form. +@xref{Curve Fitting Details}. This set is divided into four phases. +The first phase rewrites certain kinds of expressions to be more +easily linearizable, but less computationally efficient. After the +linear components have been picked out, the final phase includes the +opposite rewrites to put each component back into an efficient form. +If both sets of rules were included in one big phase, Calc could get +into an infinite loop going back and forth between the two forms. + +Elsewhere in @code{FitRules}, the components are first isolated, +then recombined where possible to reduce the complexity of the linear +fit, then finally packaged one component at a time into vectors. +If the packaging rules were allowed to begin before the recombining +rules were finished, some components might be put away into vectors +before they had a chance to recombine. By putting these rules in +two separate phases, this problem is neatly avoided. + +@node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules +@subsection Selections with Rewrite Rules + +@noindent +If a sub-formula of the current formula is selected (as by @kbd{j s}; +@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite}) +command applies only to that sub-formula. Together with a negative +prefix argument, you can use this fact to apply a rewrite to one +specific part of a formula without affecting any other parts. + +@kindex j r +@pindex calc-rewrite-selection +The @kbd{j r} (@code{calc-rewrite-selection}) command allows more +sophisticated operations on selections. This command prompts for +the rules in the same way as @kbd{a r}, but it then applies those +rules to the whole formula in question even though a sub-formula +of it has been selected. However, the selected sub-formula will +first have been surrounded by a @samp{select( )} function call. +(Calc's evaluator does not understand the function name @code{select}; +this is only a tag used by the @kbd{j r} command.) + +For example, suppose the formula on the stack is @samp{2 (a + b)^2} +and the sub-formula @samp{a + b} is selected. This formula will +be rewritten to @samp{2 select(a + b)^2} and then the rewrite +rules will be applied in the usual way. The rewrite rules can +include references to @code{select} to tell where in the pattern +the selected sub-formula should appear. + +If there is still exactly one @samp{select( )} function call in +the formula after rewriting is done, it indicates which part of +the formula should be selected afterwards. Otherwise, the +formula will be unselected. + +You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts +of the rewrite rule with @samp{select()}. However, @kbd{j r} +allows you to use the current selection in more flexible ways. +Suppose you wished to make a rule which removed the exponent from +the selected term; the rule @samp{select(a)^x := select(a)} would +work. In the above example, it would rewrite @samp{2 select(a + b)^2} +to @samp{2 select(a + b)}. This would then be returned to the +stack as @samp{2 (a + b)} with the @samp{a + b} selected. + +The @kbd{j r} command uses one iteration by default, unlike +@kbd{a r} which defaults to 100 iterations. A numeric prefix +argument affects @kbd{j r} in the same way as @kbd{a r}. +@xref{Nested Formulas with Rewrite Rules}. + +As with other selection commands, @kbd{j r} operates on the stack +entry that contains the cursor. (If the cursor is on the top-of-stack +@samp{.} marker, it works as if the cursor were on the formula +at stack level 1.) + +If you don't specify a set of rules, the rules are taken from the +top of the stack, just as with @kbd{a r}. In this case, the +cursor must indicate stack entry 2 or above as the formula to be +rewritten (otherwise the same formula would be used as both the +target and the rewrite rules). + +If the indicated formula has no selection, the cursor position within +the formula temporarily selects a sub-formula for the purposes of this +command. If the cursor is not on any sub-formula (e.g., it is in +the line-number area to the left of the formula), the @samp{select( )} +markers are ignored by the rewrite mechanism and the rules are allowed +to apply anywhere in the formula. + +As a special feature, the normal @kbd{a r} command also ignores +@samp{select( )} calls in rewrite rules. For example, if you used the +above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply +the rule as if it were @samp{a^x := a}. Thus, you can write general +purpose rules with @samp{select( )} hints inside them so that they +will ``do the right thing'' in both @kbd{a r} and @kbd{j r}, +both with and without selections. + +@node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules +@subsection Matching Commands + +@noindent +@kindex a m +@pindex calc-match +@tindex match +The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a +vector of formulas and a rewrite-rule-style pattern, and produces +a vector of all formulas which match the pattern. The command +prompts you to enter the pattern; as for @kbd{a r}, you can enter +a single pattern (i.e., a formula with meta-variables), or a +vector of patterns, or a variable which contains patterns, or +you can give a blank response in which case the patterns are taken +from the top of the stack. The pattern set will be compiled once +and saved if it is stored in a variable. If there are several +patterns in the set, vector elements are kept if they match any +of the patterns. + +For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])} +will return @samp{[x+y, x-y, x+y+z]}. + +The @code{import} mechanism is not available for pattern sets. + +The @kbd{a m} command can also be used to extract all vector elements +which satisfy any condition: The pattern @samp{x :: x>0} will select +all the positive vector elements. + +@kindex I a m +@tindex matchnot +With the Inverse flag [@code{matchnot}], this command extracts all +vector elements which do @emph{not} match the given pattern. + +@c @starindex +@tindex matches +There is also a function @samp{matches(@var{x}, @var{p})} which +evaluates to 1 if expression @var{x} matches pattern @var{p}, or +to 0 otherwise. This is sometimes useful for including into the +conditional clauses of other rewrite rules. + +@c @starindex +@tindex vmatches +The function @code{vmatches} is just like @code{matches}, except +that if the match succeeds it returns a vector of assignments to +the meta-variables instead of the number 1. For example, +@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}. +If the match fails, the function returns the number 0. + +@node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules +@subsection Automatic Rewrites + +@noindent +@cindex @code{EvalRules} variable +@vindex EvalRules +It is possible to get Calc to apply a set of rewrite rules on all +results, effectively adding to the built-in set of default +simplifications. To do this, simply store your rule set in the +variable @code{EvalRules}. There is a convenient @kbd{s E} command +for editing @code{EvalRules}; @pxref{Operations on Variables}. + +For example, suppose you want @samp{sin(a + b)} to be expanded out +to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and +similarly for @samp{cos(a + b)}. The corresponding rewrite rule +set would be, + +@group +@smallexample +[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b), + cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ] +@end smallexample +@end group + +To apply these manually, you could put them in a variable called +@code{trigexp} and then use @kbd{a r trigexp} every time you wanted +to expand trig functions. But if instead you store them in the +variable @code{EvalRules}, they will automatically be applied to all +sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on +the stack, typing @kbd{+ S} will (assuming degrees mode) result in +@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically. + +As each level of a formula is evaluated, the rules from +@code{EvalRules} are applied before the default simplifications. +Rewriting continues until no further @code{EvalRules} apply. +Note that this is different from the usual order of application of +rewrite rules: @code{EvalRules} works from the bottom up, simplifying +the arguments to a function before the function itself, while @kbd{a r} +applies rules from the top down. + +Because the @code{EvalRules} are tried first, you can use them to +override the normal behavior of any built-in Calc function. + +It is important not to write a rule that will get into an infinite +loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]} +appears to be a good definition of a factorial function, but it is +unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc +will continue to subtract 1 from this argument forever without reaching +zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}. +Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting +@samp{g(2, 4)}, this would bounce back and forth between that and +@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules} +occurs, Emacs will eventually stop with a ``Computation got stuck +or ran too long'' message. + +Another subtle difference between @code{EvalRules} and regular rewrites +concerns rules that rewrite a formula into an identical formula. For +example, @samp{f(n) := f(floor(n))} ``fails to match'' when @cite{n} is +already an integer. But in @code{EvalRules} this case is detected only +if the righthand side literally becomes the original formula before any +further simplification. This means that @samp{f(n) := f(floor(n))} will +get into an infinite loop if it occurs in @code{EvalRules}. Calc will +replace @samp{f(6)} with @samp{f(floor(6))}, which is different from +@samp{f(6)}, so it will consider the rule to have matched and will +continue simplifying that formula; first the argument is simplified +to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))} +again, ad infinitum. A much safer rule would check its argument first, +say, with @samp{f(n) := f(floor(n)) :: !dint(n)}. + +(What really happens is that the rewrite mechanism substitutes the +meta-variables in the righthand side of a rule, compares to see if the +result is the same as the original formula and fails if so, then uses +the default simplifications to simplify the result and compares again +(and again fails if the formula has simplified back to its original +form). The only special wrinkle for the @code{EvalRules} is that the +same rules will come back into play when the default simplifications +are used. What Calc wants to do is build @samp{f(floor(6))}, see that +this is different from the original formula, simplify to @samp{f(6)}, +see that this is the same as the original formula, and thus halt the +rewriting. But while simplifying, @samp{f(6)} will again trigger +the same @code{EvalRules} rule and Calc will get into a loop inside +the rewrite mechanism itself.) + +The @code{phase}, @code{schedule}, and @code{iterations} markers do +not work in @code{EvalRules}. If the rule set is divided into phases, +only the phase 1 rules are applied, and the schedule is ignored. +The rules are always repeated as many times as possible. + +The @code{EvalRules} are applied to all function calls in a formula, +but not to numbers (and other number-like objects like error forms), +nor to vectors or individual variable names. (Though they will apply +to @emph{components} of vectors and error forms when appropriate.) You +might try to make a variable @code{phihat} which automatically expands +to its definition without the need to press @kbd{=} by writing the +rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule +will not work as part of @code{EvalRules}. + +Finally, another limitation is that Calc sometimes calls its built-in +functions directly rather than going through the default simplifications. +When it does this, @code{EvalRules} will not be able to override those +functions. For example, when you take the absolute value of the complex +number @cite{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling +the multiplication, addition, and square root functions directly rather +than applying the default simplifications to this formula. So an +@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6} +would not apply. (However, if you put Calc into symbolic mode so that +@samp{sqrt(13)} will be left in symbolic form by the built-in square +root function, your rule will be able to apply. But if the complex +number were @cite{(3,4)}, so that @samp{sqrt(25)} must be calculated, +then symbolic mode will not help because @samp{sqrt(25)} can be +evaluated exactly to 5.) + +One subtle restriction that normally only manifests itself with +@code{EvalRules} is that while a given rewrite rule is in the process +of being checked, that same rule cannot be recursively applied. Calc +effectively removes the rule from its rule set while checking the rule, +then puts it back once the match succeeds or fails. (The technical +reason for this is that compiled pattern programs are not reentrant.) +For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0} +attempting to match @samp{foo(8)}. This rule will be inactive while +the condition @samp{foo(4) > 0} is checked, even though it might be +an integral part of evaluating that condition. Note that this is not +a problem for the more usual recursive type of rule, such as +@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and +been reactivated by the time the righthand side is evaluated. + +If @code{EvalRules} has no stored value (its default state), or if +anything but a vector is stored in it, then it is ignored. + +Even though Calc's rewrite mechanism is designed to compare rewrite +rules to formulas as quickly as possible, storing rules in +@code{EvalRules} may make Calc run substantially slower. This is +particularly true of rules where the top-level call is a commonly used +function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will +only activate the rewrite mechanism for calls to the function @code{f}, +but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator. +And @samp{apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: +in(f, [ln, log10])} may seem more ``efficient'' than two separate +rules for @code{ln} and @code{log10}, but actually it is vastly less +efficient because rules with @code{apply} as the top-level pattern +must be tested against @emph{every} function call that is simplified. + +@cindex @code{AlgSimpRules} variable +@vindex AlgSimpRules +Suppose you want @samp{sin(a + b)} to be expanded out not all the time, +but only when @kbd{a s} is used to simplify the formula. The variable +@code{AlgSimpRules} holds rules for this purpose. The @kbd{a s} command +will apply @code{EvalRules} and @code{AlgSimpRules} to the formula, as +well as all of its built-in simplifications. + +Most of the special limitations for @code{EvalRules} don't apply to +@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules} +command with an infinite repeat count as the first step of @kbd{a s}. +It then applies its own built-in simplifications throughout the +formula, and then repeats these two steps (along with applying the +default simplifications) until no further changes are possible. + +@cindex @code{ExtSimpRules} variable +@cindex @code{UnitSimpRules} variable +@vindex ExtSimpRules +@vindex UnitSimpRules +There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables +that are used by @kbd{a e} and @kbd{u s}, respectively; these commands +also apply @code{EvalRules} and @code{AlgSimpRules}. The variable +@code{IntegSimpRules} contains simplification rules that are used +only during integration by @kbd{a i}. + +@node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules +@subsection Debugging Rewrites + +@noindent +If a buffer named @samp{*Trace*} exists, the rewrite mechanism will +record some useful information there as it operates. The original +formula is written there, as is the result of each successful rewrite, +and the final result of the rewriting. All phase changes are also +noted. + +Calc always appends to @samp{*Trace*}. You must empty this buffer +yourself periodically if it is in danger of growing unwieldy. + +Note that the rewriting mechanism is substantially slower when the +@samp{*Trace*} buffer exists, even if the buffer is not visible on +the screen. Once you are done, you will probably want to kill this +buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in +existence and forget about it, all your future rewrite commands will +be needlessly slow. + +@node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules +@subsection Examples of Rewrite Rules + +@noindent +Returning to the example of substituting the pattern +@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule +@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of +finding suitable cases. Another solution would be to use the rule +@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification +if necessary. This rule will be the most effective way to do the job, +but at the expense of making some changes that you might not desire.@refill + +Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}. +To make this work with the @w{@kbd{j r}} command so that it can be +easily targeted to a particular exponential in a large formula, +you might wish to write the rule as @samp{select(exp(x+y)) := +select(exp(x) exp(y))}. The @samp{select} markers will be +ignored by the regular @kbd{a r} command +(@pxref{Selections with Rewrite Rules}).@refill + +A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}. +This will simplify the formula whenever @cite{b} and/or @cite{c} can +be made simpler by squaring. For example, applying this rule to +@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming +Symbolic Mode has been enabled to keep the square root from being +evaulated to a floating-point approximation). This rule is also +useful when working with symbolic complex numbers, e.g., +@samp{(a + b i) / (c + d i)}. + +As another example, we could define our own ``triangular numbers'' function +with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter +this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given +a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules} +to apply these rules repeatedly. After six applications, @kbd{a r} will +stop with 15 on the stack. Once these rules are debugged, it would probably +be most useful to add them to @code{EvalRules} so that Calc will evaluate +the new @code{tri} function automatically. We could then use @kbd{Z K} on +the keyboard macro @kbd{' tri($) RET} to make a command that applies +@code{tri} to the value on the top of the stack. @xref{Programming}. + +@cindex Quaternions +The following rule set, contributed by @c{Fran\c cois} +@asis{Francois} Pinard, implements +@dfn{quaternions}, a generalization of the concept of complex numbers. +Quaternions have four components, and are here represented by function +calls @samp{quat(@var{w}, [@var{x}, @var{y}, @var{z}])} with ``real +part'' @var{w} and the three ``imaginary'' parts collected into a +vector. Various arithmetical operations on quaternions are supported. +To use these rules, either add them to @code{EvalRules}, or create a +command based on @kbd{a r} for simplifying quaternion formulas. +A convenient way to enter quaternions would be a command defined by +a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $]) @key{RET}}. + +@smallexample +[ quat(w, x, y, z) := quat(w, [x, y, z]), + quat(w, [0, 0, 0]) := w, + abs(quat(w, v)) := hypot(w, v), + -quat(w, v) := quat(-w, -v), + r + quat(w, v) := quat(r + w, v) :: real(r), + r - quat(w, v) := quat(r - w, -v) :: real(r), + quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2), + r * quat(w, v) := quat(r * w, r * v) :: real(r), + plain(quat(w1, v1) * quat(w2, v2)) + := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)), + quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r), + z / quat(w, v) := z * quatinv(quat(w, v)), + quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2), + quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v), + quat(w, v)^k := quatsqr(quat(w, v)^(k / 2)) + :: integer(k) :: k > 0 :: k % 2 = 0, + quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v) + :: integer(k) :: k > 2, + quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ] +@end smallexample + +Quaternions, like matrices, have non-commutative multiplication. +In other words, @cite{q1 * q2 = q2 * q1} is not necessarily true if +@cite{q1} and @cite{q2} are @code{quat} forms. The @samp{quat*quat} +rule above uses @code{plain} to prevent Calc from rearranging the +product. It may also be wise to add the line @samp{[quat(), matrix]} +to the @code{Decls} matrix, to ensure that Calc's other algebraic +operations will not rearrange a quaternion product. @xref{Declarations}. + +These rules also accept a four-argument @code{quat} form, converting +it to the preferred form in the first rule. If you would rather see +results in the four-argument form, just append the two items +@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end +of the rule set. (But remember that multi-phase rule sets don't work +in @code{EvalRules}.) + +@node Units, Store and Recall, Algebra, Top +@chapter Operating on Units + +@noindent +One special interpretation of algebraic formulas is as numbers with units. +For example, the formula @samp{5 m / s^2} can be read ``five meters +per second squared.'' The commands in this chapter help you +manipulate units expressions in this form. Units-related commands +begin with the @kbd{u} prefix key. + +@menu +* Basic Operations on Units:: +* The Units Table:: +* Predefined Units:: +* User-Defined Units:: +@end menu + +@node Basic Operations on Units, The Units Table, Units, Units +@section Basic Operations on Units + +@noindent +A @dfn{units expression} is a formula which is basically a number +multiplied and/or divided by one or more @dfn{unit names}, which may +optionally be raised to integer powers. Actually, the value part need not +be a number; any product or quotient involving unit names is a units +expression. Many of the units commands will also accept any formula, +where the command applies to all units expressions which appear in the +formula. + +A unit name is a variable whose name appears in the @dfn{unit table}, +or a variable whose name is a prefix character like @samp{k} (for ``kilo'') +or @samp{u} (for ``micro'') followed by a name in the unit table. +A substantial table of built-in units is provided with Calc; +@pxref{Predefined Units}. You can also define your own unit names; +@pxref{User-Defined Units}.@refill + +Note that if the value part of a units expression is exactly @samp{1}, +it will be removed by the Calculator's automatic algebra routines: The +formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a +display anomaly, however; @samp{mm} will work just fine as a +representation of one millimeter.@refill + +You may find that Algebraic Mode (@pxref{Algebraic Entry}) makes working +with units expressions easier. Otherwise, you will have to remember +to hit the apostrophe key every time you wish to enter units. + +@kindex u s +@pindex calc-simplify-units +@c @mindex usimpl@idots +@tindex usimplify +The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command +simplifies a units +expression. It uses @kbd{a s} (@code{calc-simplify}) to simplify the +expression first as a regular algebraic formula; it then looks for +features that can be further simplified by converting one object's units +to be compatible with another's. For example, @samp{5 m + 23 mm} will +simplify to @samp{5.023 m}. When different but compatible units are +added, the righthand term's units are converted to match those of the +lefthand term. @xref{Simplification Modes}, for a way to have this done +automatically at all times.@refill + +Units simplification also handles quotients of two units with the same +dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional +powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and +@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor}, +@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc}, +@code{float}, @code{frac}, @code{abs}, and @code{clean} +applied to units expressions, in which case +the operation in question is applied only to the numeric part of the +expression. Finally, trigonometric functions of quantities with units +of angle are evaluated, regardless of the current angular mode.@refill + +@kindex u c +@pindex calc-convert-units +The @kbd{u c} (@code{calc-convert-units}) command converts a units +expression to new, compatible units. For example, given the units +expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces +@samp{24.5872 m/s}. If the units you request are inconsistent with +the original units, the number will be converted into your units +times whatever ``remainder'' units are left over. For example, +converting @samp{55 mph} into acres produces @samp{6.08e-3 acre / m s}. +(Recall that multiplication binds more strongly than division in Calc +formulas, so the units here are acres per meter-second.) Remainder +units are expressed in terms of ``fundamental'' units like @samp{m} and +@samp{s}, regardless of the input units. + +One special exception is that if you specify a single unit name, and +a compatible unit appears somewhere in the units expression, then +that compatible unit will be converted to the new unit and the +remaining units in the expression will be left alone. For example, +given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will +change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}. +The ``remainder unit'' @samp{cm} is left alone rather than being +changed to the base unit @samp{m}. + +You can use explicit unit conversion instead of the @kbd{u s} command +to gain more control over the units of the result of an expression. +For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or +@kbd{u c mm} to express the result in either meters or millimeters. +(For that matter, you could type @kbd{u c fath} to express the result +in fathoms, if you preferred!) + +In place of a specific set of units, you can also enter one of the +units system names @code{si}, @code{mks} (equivalent), or @code{cgs}. +For example, @kbd{u c si @key{RET}} converts the expression into +International System of Units (SI) base units. Also, @kbd{u c base} +converts to Calc's base units, which are the same as @code{si} units +except that @code{base} uses @samp{g} as the fundamental unit of mass +whereas @code{si} uses @samp{kg}. + +@cindex Composite units +The @kbd{u c} command also accepts @dfn{composite units}, which +are expressed as the sum of several compatible unit names. For +example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles, +feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first +sorts the unit names into order of decreasing relative size. +It then accounts for as much of the input quantity as it can +using an integer number times the largest unit, then moves on +to the next smaller unit, and so on. Only the smallest unit +may have a non-integer amount attached in the result. A few +standard unit names exist for common combinations, such as +@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}. +Composite units are expanded as if by @kbd{a x}, so that +@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}. + +If the value on the stack does not contain any units, @kbd{u c} will +prompt first for the old units which this value should be considered +to have, then for the new units. Assuming the old and new units you +give are consistent with each other, the result also will not contain +any units. For example, @kbd{@w{u c} cm RET in RET} converts the number +2 on the stack to 5.08. + +@kindex u b +@pindex calc-base-units +The @kbd{u b} (@code{calc-base-units}) command is shorthand for +@kbd{u c base}; it converts the units expression on the top of the +stack into @code{base} units. If @kbd{u s} does not simplify a +units expression as far as you would like, try @kbd{u b}. + +The @kbd{u c} and @kbd{u b} commands treat temperature units (like +@samp{degC} and @samp{K}) as relative temperatures. For example, +@kbd{u c} converts @samp{10 degC} to @samp{18 degF}: A change of 10 +degrees Celsius corresponds to a change of 18 degrees Fahrenheit. + +@kindex u t +@pindex calc-convert-temperature +@cindex Temperature conversion +The @kbd{u t} (@code{calc-convert-temperature}) command converts +absolute temperatures. The value on the stack must be a simple units +expression with units of temperature only. This command would convert +@samp{10 degC} to @samp{50 degF}, the equivalent temperature on the +Fahrenheit scale.@refill + +@kindex u r +@pindex calc-remove-units +@kindex u x +@pindex calc-extract-units +The @kbd{u r} (@code{calc-remove-units}) command removes units from the +formula at the top of the stack. The @kbd{u x} +(@code{calc-extract-units}) command extracts only the units portion of a +formula. These commands essentially replace every term of the formula +that does or doesn't (respectively) look like a unit name by the +constant 1, then resimplify the formula.@refill + +@kindex u a +@pindex calc-autorange-units +The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a +mode in which unit prefixes like @code{k} (``kilo'') are automatically +applied to keep the numeric part of a units expression in a reasonable +range. This mode affects @kbd{u s} and all units conversion commands +except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz} +will be simplified to @samp{12.345 kHz}. Autoranging is useful for +some kinds of units (like @code{Hz} and @code{m}), but is probably +undesirable for non-metric units like @code{ft} and @code{tbsp}. +(Composite units are more appropriate for those; see above.) + +Autoranging always applies the prefix to the leftmost unit name. +Calc chooses the largest prefix that causes the number to be greater +than or equal to 1.0. Thus an increasing sequence of adjusted times +would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}. +Generally the rule of thumb is that the number will be adjusted +to be in the interval @samp{[1 .. 1000)}, although there are several +exceptions to this rule. First, if the unit has a power then this +is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}. +Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters), +but will not apply to other units. The ``deci-,'' ``deka-,'' and +``hecto-'' prefixes are never used. Thus the allowable interval is +@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters. +Finally, a prefix will not be added to a unit if the resulting name +is also the actual name of another unit; @samp{1e-15 t} would normally +be considered a ``femto-ton,'' but it is written as @samp{1000 at} +(1000 atto-tons) instead because @code{ft} would be confused with feet. + +@node The Units Table, Predefined Units, Basic Operations on Units, Units +@section The Units Table + +@noindent +@kindex u v +@pindex calc-enter-units-table +The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table +in another buffer called @code{*Units Table*}. Each entry in this table +gives the unit name as it would appear in an expression, the definition +of the unit in terms of simpler units, and a full name or description of +the unit. Fundamental units are defined as themselves; these are the +units produced by the @kbd{u b} command. The fundamental units are +meters, seconds, grams, kelvins, amperes, candelas, moles, radians, +and steradians. + +The Units Table buffer also displays the Unit Prefix Table. Note that +two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case +prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M} +prefix. Whenever a unit name can be interpreted as either a built-in name +or a prefix followed by another built-in name, the former interpretation +wins. For example, @samp{2 pt} means two pints, not two pico-tons. + +The Units Table buffer, once created, is not rebuilt unless you define +new units. To force the buffer to be rebuilt, give any numeric prefix +argument to @kbd{u v}. + +@kindex u V +@pindex calc-view-units-table +The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except +that the cursor is not moved into the Units Table buffer. You can +type @kbd{u V} again to remove the Units Table from the display. To +return from the Units Table buffer after a @kbd{u v}, type @kbd{M-# c} +again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window}) +command. You can also kill the buffer with @kbd{C-x k} if you wish; +the actual units table is safely stored inside the Calculator. + +@kindex u g +@pindex calc-get-unit-definition +The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's +defining expression and pushes it onto the Calculator stack. For example, +@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the +same definition for the unit that would appear in the Units Table buffer. +Note that this command works only for actual unit names; @kbd{u g km} +will report that no such unit exists, for example, because @code{km} is +really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a +definition of a unit in terms of base units, it is easier to push the +unit name on the stack and then reduce it to base units with @kbd{u b}. + +@kindex u e +@pindex calc-explain-units +The @kbd{u e} (@code{calc-explain-units}) command displays an English +description of the units of the expression on the stack. For example, +for the expression @samp{62 km^2 g / s^2 mol K}, the description is +``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This +command uses the English descriptions that appear in the righthand +column of the Units Table. + +@node Predefined Units, User-Defined Units, The Units Table, Units +@section Predefined Units + +@noindent +Since the exact definitions of many kinds of units have evolved over the +years, and since certain countries sometimes have local differences in +their definitions, it is a good idea to examine Calc's definition of a +unit before depending on its exact value. For example, there are three +different units for gallons, corresponding to the US (@code{gal}), +Canadian (@code{galC}), and British (@code{galUK}) definitions. Also, +note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy +ounce, and @code{ozfl} is a fluid ounce. + +The temperature units corresponding to degrees Kelvin and Centigrade +(Celsius) are the same in this table, since most units commands treat +temperatures as being relative. The @code{calc-convert-temperature} +command has special rules for handling the different absolute magnitudes +of the various temperature scales. + +The unit of volume ``liters'' can be referred to by either the lower-case +@code{l} or the upper-case @code{L}. + +The unit @code{A} stands for Amperes; the name @code{Ang} is used +@tex +for \AA ngstroms. +@end tex +@ifinfo +for Angstroms. +@end ifinfo + +The unit @code{pt} stands for pints; the name @code{point} stands for +a typographical point, defined by @samp{72 point = 1 in}. There is +also @code{tpt}, which stands for a printer's point as defined by the +@TeX{} typesetting system: @samp{72.27 tpt = 1 in}. + +The unit @code{e} stands for the elementary (electron) unit of charge; +because algebra command could mistake this for the special constant +@cite{e}, Calc provides the alternate unit name @code{ech} which is +preferable to @code{e}. + +The name @code{g} stands for one gram of mass; there is also @code{gf}, +one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.) +Meanwhile, one ``@cite{g}'' of acceleration is denoted @code{ga}. + +The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is +a metric ton of @samp{1000 kg}. + +The names @code{s} (or @code{sec}) and @code{min} refer to units of +time; @code{arcsec} and @code{arcmin} are units of angle. + +Some ``units'' are really physical constants; for example, @code{c} +represents the speed of light, and @code{h} represents Planck's +constant. You can use these just like other units: converting +@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in +meters per second. You can also use this merely as a handy reference; +the @kbd{u g} command gets the definition of one of these constants +in its normal terms, and @kbd{u b} expresses the definition in base +units. + +Two units, @code{pi} and @code{fsc} (the fine structure constant, +approximately @i{1/137}) are dimensionless. The units simplification +commands simply treat these names as equivalent to their corresponding +values. However you can, for example, use @kbd{u c} to convert a pure +number into multiples of the fine structure constant, or @kbd{u b} to +convert this back into a pure number. (When @kbd{u c} prompts for the +``old units,'' just enter a blank line to signify that the value +really is unitless.) + +@c Describe angular units, luminosity vs. steradians problem. + +@node User-Defined Units, , Predefined Units, Units +@section User-Defined Units + +@noindent +Calc provides ways to get quick access to your selected ``favorite'' +units, as well as ways to define your own new units. + +@kindex u 0-9 +@pindex calc-quick-units +@vindex Units +@cindex @code{Units} variable +@cindex Quick units +To select your favorite units, store a vector of unit names or +expressions in the Calc variable @code{Units}. The @kbd{u 1} +through @kbd{u 9} commands (@code{calc-quick-units}) provide access +to these units. If the value on the top of the stack is a plain +number (with no units attached), then @kbd{u 1} gives it the +specified units. (Basically, it multiplies the number by the +first item in the @code{Units} vector.) If the number on the +stack @emph{does} have units, then @kbd{u 1} converts that number +to the new units. For example, suppose the vector @samp{[in, ft]} +is stored in @code{Units}. Then @kbd{30 u 1} will create the +expression @samp{30 in}, and @kbd{u 2} will convert that expression +to @samp{2.5 ft}. + +The @kbd{u 0} command accesses the tenth element of @code{Units}. +Only ten quick units may be defined at a time. If the @code{Units} +variable has no stored value (the default), or if its value is not +a vector, then the quick-units commands will not function. The +@kbd{s U} command is a convenient way to edit the @code{Units} +variable; @pxref{Operations on Variables}. + +@kindex u d +@pindex calc-define-unit +@cindex User-defined units +The @kbd{u d} (@code{calc-define-unit}) command records the units +expression on the top of the stack as the definition for a new, +user-defined unit. For example, putting @samp{16.5 ft} on the stack and +typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to +16.5 feet. The unit conversion and simplification commands will now +treat @code{rod} just like any other unit of length. You will also be +prompted for an optional English description of the unit, which will +appear in the Units Table. + +@kindex u u +@pindex calc-undefine-unit +The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined +unit. It is not possible to remove one of the predefined units, +however. + +If you define a unit with an existing unit name, your new definition +will replace the original definition of that unit. If the unit was a +predefined unit, the old definition will not be replaced, only +``shadowed.'' The built-in definition will reappear if you later use +@kbd{u u} to remove the shadowing definition. + +To create a new fundamental unit, use either 1 or the unit name itself +as the defining expression. Otherwise the expression can involve any +other units that you like (except for composite units like @samp{mfi}). +You can create a new composite unit with a sum of other units as the +defining expression. The next unit operation like @kbd{u c} or @kbd{u v} +will rebuild the internal unit table incorporating your modifications. +Note that erroneous definitions (such as two units defined in terms of +each other) will not be detected until the unit table is next rebuilt; +@kbd{u v} is a convenient way to force this to happen. + +Temperature units are treated specially inside the Calculator; it is not +possible to create user-defined temperature units. + +@kindex u p +@pindex calc-permanent-units +@cindex @file{.emacs} file, user-defined units +The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined +units in your @file{.emacs} file, so that the units will still be +available in subsequent Emacs sessions. If there was already a set of +user-defined units in your @file{.emacs} file, it is replaced by the +new set. (@xref{General Mode Commands}, for a way to tell Calc to use +a different file instead of @file{.emacs}.) + +@node Store and Recall, Graphics, Units, Top +@chapter Storing and Recalling + +@noindent +Calculator variables are really just Lisp variables that contain numbers +or formulas in a form that Calc can understand. The commands in this +section allow you to manipulate variables conveniently. Commands related +to variables use the @kbd{s} prefix key. + +@menu +* Storing Variables:: +* Recalling Variables:: +* Operations on Variables:: +* Let Command:: +* Evaluates-To Operator:: +@end menu + +@node Storing Variables, Recalling Variables, Store and Recall, Store and Recall +@section Storing Variables + +@noindent +@kindex s s +@pindex calc-store +@cindex Storing variables +@cindex Quick variables +@vindex q0 +@vindex q9 +The @kbd{s s} (@code{calc-store}) command stores the value at the top of +the stack into a specified variable. It prompts you to enter the +name of the variable. If you press a single digit, the value is stored +immediately in one of the ``quick'' variables @code{var-q0} through +@code{var-q9}. Or you can enter any variable name. The prefix @samp{var-} +is supplied for you; when a name appears in a formula (as in @samp{a+q2}) +the prefix @samp{var-} is also supplied there, so normally you can simply +forget about @samp{var-} everywhere. Its only purpose is to enable you to +use Calc variables without fear of accidentally clobbering some variable in +another Emacs package. If you really want to store in an arbitrary Lisp +variable, just backspace over the @samp{var-}. + +@kindex s t +@pindex calc-store-into +The @kbd{s s} command leaves the stored value on the stack. There is +also an @kbd{s t} (@code{calc-store-into}) command, which removes a +value from the stack and stores it in a variable. + +If the top of stack value is an equation @samp{a = 7} or assignment +@samp{a := 7} with a variable on the lefthand side, then Calc will +assign that variable with that value by default, i.e., if you type +@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the +value 7 would be stored in the variable @samp{a}. (If you do type +a variable name at the prompt, the top-of-stack value is stored in +its entirety, even if it is an equation: @samp{s s b @key{RET}} +with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.) + +In fact, the top of stack value can be a vector of equations or +assignments with different variables on their lefthand sides; the +default will be to store all the variables with their corresponding +righthand sides simultaneously. + +It is also possible to type an equation or assignment directly at +the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}. +In this case the expression to the right of the @kbd{=} or @kbd{:=} +symbol is evaluated as if by the @kbd{=} command, and that value is +stored in the variable. No value is taken from the stack; @kbd{s s} +and @kbd{s t} are equivalent when used in this way. + +@kindex s 0-9 +@kindex t 0-9 +The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a +digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is +equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used +for trail and time/date commands.) + +@kindex s + +@kindex s - +@c @mindex @idots +@kindex s * +@c @mindex @null +@kindex s / +@c @mindex @null +@kindex s ^ +@c @mindex @null +@kindex s | +@c @mindex @null +@kindex s n +@c @mindex @null +@kindex s & +@c @mindex @null +@kindex s [ +@c @mindex @null +@kindex s ] +@pindex calc-store-plus +@pindex calc-store-minus +@pindex calc-store-times +@pindex calc-store-div +@pindex calc-store-power +@pindex calc-store-concat +@pindex calc-store-neg +@pindex calc-store-inv +@pindex calc-store-decr +@pindex calc-store-incr +There are also several ``arithmetic store'' commands. For example, +@kbd{s +} removes a value from the stack and adds it to the specified +variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /}, +@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and +@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}} +and @kbd{s ]} which decrease or increase a variable by one. + +All the arithmetic stores accept the Inverse prefix to reverse the +order of the operands. If @cite{v} represents the contents of the +variable, and @cite{a} is the value drawn from the stack, then regular +@w{@kbd{s -}} assigns @c{$v \coloneq v - a$} +@cite{v := v - a}, but @kbd{I s -} assigns +@c{$v \coloneq a - v$} +@cite{v := a - v}. While @kbd{I s *} might seem pointless, it is +useful if matrix multiplication is involved. Actually, all the +arithmetic stores use formulas designed to behave usefully both +forwards and backwards: + +@group +@example +s + v := v + a v := a + v +s - v := v - a v := a - v +s * v := v * a v := a * v +s / v := v / a v := a / v +s ^ v := v ^ a v := a ^ v +s | v := v | a v := a | v +s n v := v / (-1) v := (-1) / v +s & v := v ^ (-1) v := (-1) ^ v +s [ v := v - 1 v := 1 - v +s ] v := v - (-1) v := (-1) - v +@end example +@end group + +In the last four cases, a numeric prefix argument will be used in +place of the number one. (For example, @kbd{M-2 s ]} increases +a variable by 2, and @kbd{M-2 I s ]} replaces a variable by +minus-two minus the variable. + +The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -}, +etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous +arithmetic stores that don't remove the value @cite{a} from the stack. + +All arithmetic stores report the new value of the variable in the +Trail for your information. They signal an error if the variable +previously had no stored value. If default simplifications have been +turned off, the arithmetic stores temporarily turn them on for numeric +arguments only (i.e., they temporarily do an @kbd{m N} command). +@xref{Simplification Modes}. Large vectors put in the trail by +these commands always use abbreviated (@kbd{t .}) mode. + +@kindex s m +@pindex calc-store-map +The @kbd{s m} command is a general way to adjust a variable's value +using any Calc function. It is a ``mapping'' command analogous to +@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see +how to specify a function for a mapping command. Basically, +all you do is type the Calc command key that would invoke that +function normally. For example, @kbd{s m n} applies the @kbd{n} +key to negate the contents of the variable, so @kbd{s m n} is +equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root +of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to +reverse the vector stored in the variable, and @kbd{s m H I S} +takes the hyperbolic arcsine of the variable contents. + +If the mapping function takes two or more arguments, the additional +arguments are taken from the stack; the old value of the variable +is provided as the first argument. Thus @kbd{s m -} with @cite{a} +on the stack computes @cite{v - a}, just like @kbd{s -}. With the +Inverse prefix, the variable's original value becomes the @emph{last} +argument instead of the first. Thus @kbd{I s m -} is also +equivalent to @kbd{I s -}. + +@kindex s x +@pindex calc-store-exchange +The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value +of a variable with the value on the top of the stack. Naturally, the +variable must already have a stored value for this to work. + +You can type an equation or assignment at the @kbd{s x} prompt. The +command @kbd{s x a=6} takes no values from the stack; instead, it +pushes the old value of @samp{a} on the stack and stores @samp{a = 6}. + +@kindex s u +@pindex calc-unstore +@cindex Void variables +@cindex Un-storing variables +Until you store something in them, variables are ``void,'' that is, they +contain no value at all. If they appear in an algebraic formula they +will be left alone even if you press @kbd{=} (@code{calc-evaluate}). +The @kbd{s u} (@code{calc-unstore}) command returns a variable to the +void state.@refill + +The only variables with predefined values are the ``special constants'' +@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free +to unstore these variables or to store new values into them if you like, +although some of the algebraic-manipulation functions may assume these +variables represent their standard values. Calc displays a warning if +you change the value of one of these variables, or of one of the other +special variables @code{inf}, @code{uinf}, and @code{nan} (which are +normally void). + +Note that @code{var-pi} doesn't actually have 3.14159265359 stored +in it, but rather a special magic value that evaluates to @c{$\pi$} +@cite{pi} +at the current precision. Likewise @code{var-e}, @code{var-i}, and +@code{var-phi} evaluate according to the current precision or polar mode. +If you recall a value from @code{pi} and store it back, this magic +property will be lost. + +@kindex s c +@pindex calc-copy-variable +The @kbd{s c} (@code{calc-copy-variable}) command copies the stored +value of one variable to another. It differs from a simple @kbd{s r} +followed by an @kbd{s t} in two important ways. First, the value never +goes on the stack and thus is never rounded, evaluated, or simplified +in any way; it is not even rounded down to the current precision. +Second, the ``magic'' contents of a variable like @code{var-e} can +be copied into another variable with this command, perhaps because +you need to unstore @code{var-e} right now but you wish to put it +back when you're done. The @kbd{s c} command is the only way to +manipulate these magic values intact. + +@node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall +@section Recalling Variables + +@noindent +@kindex s r +@pindex calc-recall +@cindex Recalling variables +The most straightforward way to extract the stored value from a variable +is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts +for a variable name (similarly to @code{calc-store}), looks up the value +of the specified variable, and pushes that value onto the stack. It is +an error to try to recall a void variable. + +It is also possible to recall the value from a variable by evaluating a +formula containing that variable. For example, @kbd{' a @key{RET} =} is +the same as @kbd{s r a @key{RET}} except that if the variable is void, the +former will simply leave the formula @samp{a} on the stack whereas the +latter will produce an error message. + +@kindex r 0-9 +The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is +equivalent to @kbd{s r 9}. (The @kbd{r} prefix is otherwise unused +in the current version of Calc.) + +@node Operations on Variables, Let Command, Recalling Variables, Store and Recall +@section Other Operations on Variables + +@noindent +@kindex s e +@pindex calc-edit-variable +The @kbd{s e} (@code{calc-edit-variable}) command edits the stored +value of a variable without ever putting that value on the stack +or simplifying or evaluating the value. It prompts for the name of +the variable to edit. If the variable has no stored value, the +editing buffer will start out empty. If the editing buffer is +empty when you press @key{M-# M-#} to finish, the variable will +be made void. @xref{Editing Stack Entries}, for a general +description of editing. + +The @kbd{s e} command is especially useful for creating and editing +rewrite rules which are stored in variables. Sometimes these rules +contain formulas which must not be evaluated until the rules are +actually used. (For example, they may refer to @samp{deriv(x,y)}, +where @code{x} will someday become some expression involving @code{y}; +if you let Calc evaluate the rule while you are defining it, Calc will +replace @samp{deriv(x,y)} with 0 because the formula @code{x} does +not itself refer to @code{y}.) By contrast, recalling the variable, +editing with @kbd{`}, and storing will evaluate the variable's value +as a side effect of putting the value on the stack. + +@kindex s A +@kindex s D +@c @mindex @idots +@kindex s E +@c @mindex @null +@kindex s F +@c @mindex @null +@kindex s G +@c @mindex @null +@kindex s H +@c @mindex @null +@kindex s I +@c @mindex @null +@kindex s L +@c @mindex @null +@kindex s P +@c @mindex @null +@kindex s R +@c @mindex @null +@kindex s T +@c @mindex @null +@kindex s U +@c @mindex @null +@kindex s X +@pindex calc-store-AlgSimpRules +@pindex calc-store-Decls +@pindex calc-store-EvalRules +@pindex calc-store-FitRules +@pindex calc-store-GenCount +@pindex calc-store-Holidays +@pindex calc-store-IntegLimit +@pindex calc-store-LineStyles +@pindex calc-store-PointStyles +@pindex calc-store-PlotRejects +@pindex calc-store-TimeZone +@pindex calc-store-Units +@pindex calc-store-ExtSimpRules +There are several special-purpose variable-editing commands that +use the @kbd{s} prefix followed by a shifted letter: + +@table @kbd +@item s A +Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}. +@item s D +Edit @code{Decls}. @xref{Declarations}. +@item s E +Edit @code{EvalRules}. @xref{Default Simplifications}. +@item s F +Edit @code{FitRules}. @xref{Curve Fitting}. +@item s G +Edit @code{GenCount}. @xref{Solving Equations}. +@item s H +Edit @code{Holidays}. @xref{Business Days}. +@item s I +Edit @code{IntegLimit}. @xref{Calculus}. +@item s L +Edit @code{LineStyles}. @xref{Graphics}. +@item s P +Edit @code{PointStyles}. @xref{Graphics}. +@item s R +Edit @code{PlotRejects}. @xref{Graphics}. +@item s T +Edit @code{TimeZone}. @xref{Time Zones}. +@item s U +Edit @code{Units}. @xref{User-Defined Units}. +@item s X +Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}. +@end table + +These commands are just versions of @kbd{s e} that use fixed variable +names rather than prompting for the variable name. + +@kindex s p +@pindex calc-permanent-variable +@cindex Storing variables +@cindex Permanent variables +@cindex @file{.emacs} file, veriables +The @kbd{s p} (@code{calc-permanent-variable}) command saves a +variable's value permanently in your @file{.emacs} file, so that its +value will still be available in future Emacs sessions. You can +re-execute @w{@kbd{s p}} later on to update the saved value, but the +only way to remove a saved variable is to edit your @file{.emacs} file +by hand. (@xref{General Mode Commands}, for a way to tell Calc to +use a different file instead of @file{.emacs}.) + +If you do not specify the name of a variable to save (i.e., +@kbd{s p @key{RET}}), all @samp{var-} variables with defined values +are saved except for the special constants @code{pi}, @code{e}, +@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone} +and @code{PlotRejects}; +@code{FitRules}, @code{DistribRules}, and other built-in rewrite +rules; and @code{PlotData@var{n}} variables generated +by the graphics commands. (You can still save these variables by +explicitly naming them in an @kbd{s p} command.)@refill + +@kindex s i +@pindex calc-insert-variables +The @kbd{s i} (@code{calc-insert-variables}) command writes +the values of all @samp{var-} variables into a specified buffer. +The variables are written in the form of Lisp @code{setq} commands +which store the values in string form. You can place these commands +in your @file{.emacs} buffer if you wish, though in this case it +would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i} +omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference +is that @kbd{s i} will store the variables in any buffer, and it also +stores in a more human-readable format.) + +@node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall +@section The Let Command + +@noindent +@kindex s l +@pindex calc-let +@cindex Variables, temporary assignment +@cindex Temporary assignment to variables +If you have an expression like @samp{a+b^2} on the stack and you wish to +compute its value where @cite{b=3}, you can simply store 3 in @cite{b} and +then press @kbd{=} to reevaluate the formula. This has the side-effect +of leaving the stored value of 3 in @cite{b} for future operations. + +The @kbd{s l} (@code{calc-let}) command evaluates a formula under a +@emph{temporary} assignment of a variable. It stores the value on the +top of the stack into the specified variable, then evaluates the +second-to-top stack entry, then restores the original value (or lack of one) +in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}}, +the stack will contain the formula @samp{a + 9}. The subsequent command +@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14. +The variables @samp{a} and @samp{b} are not permanently affected in any way +by these commands. + +The value on the top of the stack may be an equation or assignment, or +a vector of equations or assignments, in which case the default will be +analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}. + +Also, you can answer the variable-name prompt with an equation or +assignment: @kbd{s l b=3 RET} is the same as storing 3 on the stack +and typing @kbd{s l b RET}. + +The @kbd{a b} (@code{calc-substitute}) command is another way to substitute +a variable with a value in a formula. It does an actual substitution +rather than temporarily assigning the variable and evaluating. For +example, letting @cite{n=2} in @samp{f(n pi)} with @kbd{a b} will +produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)} +since the evaluation step will also evaluate @code{pi}. + +@node Evaluates-To Operator, , Let Command, Store and Recall +@section The Evaluates-To Operator + +@noindent +@tindex evalto +@tindex => +@cindex Evaluates-to operator +@cindex @samp{=>} operator +The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to +operator}. (It will show up as an @code{evalto} function call in +other language modes like Pascal and @TeX{}.) This is a binary +operator, that is, it has a lefthand and a righthand argument, +although it can be entered with the righthand argument omitted. + +A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as +follows: First, @var{a} is not simplified or modified in any +way. The previous value of argument @var{b} is thrown away; the +formula @var{a} is then copied and evaluated as if by the @kbd{=} +command according to all current modes and stored variable values, +and the result is installed as the new value of @var{b}. + +For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}. +The number 17 is ignored, and the lefthand argument is left in its +unevaluated form; the result is the formula @samp{2 + 3 => 5}. + +@kindex s = +@pindex calc-evalto +You can enter an @samp{=>} formula either directly using algebraic +entry (in which case the righthand side may be omitted since it is +going to be replaced right away anyhow), or by using the @kbd{s =} +(@code{calc-evalto}) command, which takes @var{a} from the stack +and replaces it with @samp{@var{a} => @var{b}}. + +Calc keeps track of all @samp{=>} operators on the stack, and +recomputes them whenever anything changes that might affect their +values, i.e., a mode setting or variable value. This occurs only +if the @samp{=>} operator is at the top level of the formula, or +if it is part of a top-level vector. In other words, pushing +@samp{2 + (a => 17)} will change the 17 to the actual value of +@samp{a} when you enter the formula, but the result will not be +dynamically updated when @samp{a} is changed later because the +@samp{=>} operator is buried inside a sum. However, a vector +of @samp{=>} operators will be recomputed, since it is convenient +to push a vector like @samp{[a =>, b =>, c =>]} on the stack to +make a concise display of all the variables in your problem. +(Another way to do this would be to use @samp{[a, b, c] =>}, +which provides a slightly different format of display. You +can use whichever you find easiest to read.) + +@kindex m C +@pindex calc-auto-recompute +The @kbd{m C} (@code{calc-auto-recompute}) command allows you to +turn this automatic recomputation on or off. If you turn +recomputation off, you must explicitly recompute an @samp{=>} +operator on the stack in one of the usual ways, such as by +pressing @kbd{=}. Turning recomputation off temporarily can save +a lot of time if you will be changing several modes or variables +before you look at the @samp{=>} entries again. + +Most commands are not especially useful with @samp{=>} operators +as arguments. For example, given @samp{x + 2 => 17}, it won't +work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want +to operate on the lefthand side of the @samp{=>} operator on +the top of the stack, type @kbd{j 1} (that's the digit ``one'') +to select the lefthand side, execute your commands, then type +@kbd{j u} to unselect. + +All current modes apply when an @samp{=>} operator is computed, +including the current simplification mode. Recall that the +formula @samp{x + y + x} is not handled by Calc's default +simplifications, but the @kbd{a s} command will reduce it to +the simpler form @samp{y + 2 x}. You can also type @kbd{m A} +to enable an algebraic-simplification mode in which the +equivalent of @kbd{a s} is used on all of Calc's results. +If you enter @samp{x + y + x =>} normally, the result will +be @samp{x + y + x => x + y + x}. If you change to +algebraic-simplification mode, the result will be +@samp{x + y + x => y + 2 x}. However, just pressing @kbd{a s} +once will have no effect on @samp{x + y + x => x + y + x}, +because the righthand side depends only on the lefthand side +and the current mode settings, and the lefthand side is not +affected by commands like @kbd{a s}. + +The ``let'' command (@kbd{s l}) has an interesting interaction +with the @samp{=>} operator. The @kbd{s l} command evaluates the +second-to-top stack entry with the top stack entry supplying +a temporary value for a given variable. As you might expect, +if that stack entry is an @samp{=>} operator its righthand +side will temporarily show this value for the variable. In +fact, all @samp{=>}s on the stack will be updated if they refer +to that variable. But this change is temporary in the sense +that the next command that causes Calc to look at those stack +entries will make them revert to the old variable value. + +@group +@smallexample +2: a => a 2: a => 17 2: a => a +1: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1 + . . . + + 17 s l a RET p 8 RET +@end smallexample +@end group + +Here the @kbd{p 8} command changes the current precision, +thus causing the @samp{=>} forms to be recomputed after the +influence of the ``let'' is gone. The @kbd{d SPC} command +(@code{calc-refresh}) is a handy way to force the @samp{=>} +operators on the stack to be recomputed without any other +side effects. + +@kindex s : +@pindex calc-assign +@tindex assign +@tindex := +Embedded Mode also uses @samp{=>} operators. In embedded mode, +the lefthand side of an @samp{=>} operator can refer to variables +assigned elsewhere in the file by @samp{:=} operators. The +assignment operator @samp{a := 17} does not actually do anything +by itself. But Embedded Mode recognizes it and marks it as a sort +of file-local definition of the variable. You can enter @samp{:=} +operators in algebraic mode, or by using the @kbd{s :} +(@code{calc-assign}) [@code{assign}] command which takes a variable +and value from the stack and replaces them with an assignment. + +@xref{TeX Language Mode}, for the way @samp{=>} appears in +@TeX{} language output. The @dfn{eqn} mode gives similar +treatment to @samp{=>}. + +@node Graphics, Kill and Yank, Store and Recall, Top +@chapter Graphics + +@noindent +The commands for graphing data begin with the @kbd{g} prefix key. Calc +uses GNUPLOT 2.0 or 3.0 to do graphics. These commands will only work +if GNUPLOT is available on your system. (While GNUPLOT sounds like +a relative of GNU Emacs, it is actually completely unrelated. +However, it is free software and can be obtained from the Free +Software Foundation's machine @samp{prep.ai.mit.edu}.) + +@vindex calc-gnuplot-name +If you have GNUPLOT installed on your system but Calc is unable to +find it, you may need to set the @code{calc-gnuplot-name} variable +in your @file{.emacs} file. You may also need to set some Lisp +variables to show Calc how to run GNUPLOT on your system; these +are described under @kbd{g D} and @kbd{g O} below. If you are +using the X window system, Calc will configure GNUPLOT for you +automatically. If you have GNUPLOT 3.0 and you are not using X, +Calc will configure GNUPLOT to display graphs using simple character +graphics that will work on any terminal. + +@menu +* Basic Graphics:: +* Three Dimensional Graphics:: +* Managing Curves:: +* Graphics Options:: +* Devices:: +@end menu + +@node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics +@section Basic Graphics + +@noindent +@kindex g f +@pindex calc-graph-fast +The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}). +This command takes two vectors of equal length from the stack. +The vector at the top of the stack represents the ``y'' values of +the various data points. The vector in the second-to-top position +represents the corresponding ``x'' values. This command runs +GNUPLOT (if it has not already been started by previous graphing +commands) and displays the set of data points. The points will +be connected by lines, and there will also be some kind of symbol +to indicate the points themselves. + +The ``x'' entry may instead be an interval form, in which case suitable +``x'' values are interpolated between the minimum and maximum values of +the interval (whether the interval is open or closed is ignored). + +The ``x'' entry may also be a number, in which case Calc uses the +sequence of ``x'' values @cite{x}, @cite{x+1}, @cite{x+2}, etc. +(Generally the number 0 or 1 would be used for @cite{x} in this case.) + +The ``y'' entry may be any formula instead of a vector. Calc effectively +uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula; +the result of this must be a formula in a single (unassigned) variable. +The formula is plotted with this variable taking on the various ``x'' +values. Graphs of formulas by default use lines without symbols at the +computed data points. Note that if neither ``x'' nor ``y'' is a vector, +Calc guesses at a reasonable number of data points to use. See the +@kbd{g N} command below. (The ``x'' values must be either a vector +or an interval if ``y'' is a formula.) + +@c @starindex +@tindex xy +If ``y'' is (or evaluates to) a formula of the form +@samp{xy(@var{x}, @var{y})} then the result is a +parametric plot. The two arguments of the fictitious @code{xy} function +are used as the ``x'' and ``y'' coordinates of the curve, respectively. +In this case the ``x'' vector or interval you specified is not directly +visible in the graph. For example, if ``x'' is the interval @samp{[0..360]} +and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph +will be a circle.@refill + +Also, ``x'' and ``y'' may each be variable names, in which case Calc +looks for suitable vectors, intervals, or formulas stored in those +variables. + +The ``x'' and ``y'' values for the data points (as pulled from the vectors, +calculated from the formulas, or interpolated from the intervals) should +be real numbers (integers, fractions, or floats). If either the ``x'' +value or the ``y'' value of a given data point is not a real number, that +data point will be omitted from the graph. The points on either side +of the invalid point will @emph{not} be connected by a line. + +See the documentation for @kbd{g a} below for a description of the way +numeric prefix arguments affect @kbd{g f}. + +@cindex @code{PlotRejects} variable +@vindex PlotRejects +If you store an empty vector in the variable @code{PlotRejects} +(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to +this vector for every data point which was rejected because its +``x'' or ``y'' values were not real numbers. The result will be +a matrix where each row holds the curve number, data point number, +``x'' value, and ``y'' value for a rejected data point. +@xref{Evaluates-To Operator}, for a handy way to keep tabs on the +current value of @code{PlotRejects}. @xref{Operations on Variables}, +for the @kbd{s R} command which is another easy way to examine +@code{PlotRejects}. + +@kindex g c +@pindex calc-graph-clear +To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}). +If the GNUPLOT output device is an X window, the window will go away. +Effects on other kinds of output devices will vary. You don't need +to use @kbd{g c} if you don't want to---if you give another @kbd{g f} +or @kbd{g p} command later on, it will reuse the existing graphics +window if there is one. + +@node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics +@section Three-Dimensional Graphics + +@kindex g F +@pindex calc-graph-fast-3d +The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional +graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0, +you will see a GNUPLOT error message if you try this command. + +The @kbd{g F} command takes three values from the stack, called ``x'', +``y'', and ``z'', respectively. As was the case for 2D graphs, there +are several options for these values. + +In the first case, ``x'' and ``y'' are each vectors (not necessarily of +the same length); either or both may instead be interval forms. The +``z'' value must be a matrix with the same number of rows as elements +in ``x'', and the same number of columns as elements in ``y''. The +result is a surface plot where @c{$z_{ij}$} +@cite{z_ij} is the height of the point +at coordinate @cite{(x_i, y_j)} on the surface. The 3D graph will +be displayed from a certain default viewpoint; you can change this +viewpoint by adding a @samp{set view} to the @samp{*Gnuplot Commands*} +buffer as described later. See the GNUPLOT 3.0 documentation for a +description of the @samp{set view} command. + +Each point in the matrix will be displayed as a dot in the graph, +and these points will be connected by a grid of lines (@dfn{isolines}). + +In the second case, ``x'', ``y'', and ``z'' are all vectors of equal +length. The resulting graph displays a 3D line instead of a surface, +where the coordinates of points along the line are successive triplets +of values from the input vectors. + +In the third case, ``x'' and ``y'' are vectors or interval forms, and +``z'' is any formula involving two variables (not counting variables +with assigned values). These variables are sorted into alphabetical +order; the first takes on values from ``x'' and the second takes on +values from ``y'' to form a matrix of results that are graphed as a +3D surface. + +@c @starindex +@tindex xyz +If the ``z'' formula evaluates to a call to the fictitious function +@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a +``parametric surface.'' In this case, the axes of the graph are +taken from the @var{x} and @var{y} values in these calls, and the +``x'' and ``y'' values from the input vectors or intervals are used only +to specify the range of inputs to the formula. For example, plotting +@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))} +will draw a sphere. (Since the default resolution for 3D plots is +5 steps in each of ``x'' and ``y'', this will draw a very crude +sphere. You could use the @kbd{g N} command, described below, to +increase this resolution, or specify the ``x'' and ``y'' values as +vectors with more than 5 elements. + +It is also possible to have a function in a regular @kbd{g f} plot +evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not +a surface, the result will be a 3D parametric line. For example, +@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a +helix (a three-dimensional spiral). + +As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be +variables containing the relevant data. + +@node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics +@section Managing Curves + +@noindent +The @kbd{g f} command is really shorthand for the following commands: +@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for +@kbd{C-u g d g A g p}. You can gain more control over your graph +by using these commands directly. + +@kindex g a +@pindex calc-graph-add +The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve'' +represented by the two values on the top of the stack to the current +graph. You can have any number of curves in the same graph. When +you give the @kbd{g p} command, all the curves will be drawn superimposed +on the same axes. + +The @kbd{g a} command (and many others that affect the current graph) +will cause a special buffer, @samp{*Gnuplot Commands*}, to be displayed +in another window. This buffer is a template of the commands that will +be sent to GNUPLOT when it is time to draw the graph. The first +@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding +@kbd{g a} commands add extra curves onto that @code{plot} command. +Other graph-related commands put other GNUPLOT commands into this +buffer. In normal usage you never need to work with this buffer +directly, but you can if you wish. The only constraint is that there +must be only one @code{plot} command, and it must be the last command +in the buffer. If you want to save and later restore a complete graph +configuration, you can use regular Emacs commands to save and restore +the contents of the @samp{*Gnuplot Commands*} buffer. + +@vindex PlotData1 +@vindex PlotData2 +If the values on the stack are not variable names, @kbd{g a} will invent +variable names for them (of the form @samp{PlotData@var{n}}) and store +the values in those variables. The ``x'' and ``y'' variables are what +go into the @code{plot} command in the template. If you add a curve +that uses a certain variable and then later change that variable, you +can replot the graph without having to delete and re-add the curve. +That's because the variable name, not the vector, interval or formula +itself, is what was added by @kbd{g a}. + +A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way +stack entries are interpreted as curves. With a positive prefix +argument @cite{n}, the top @cite{n} stack entries are ``y'' values +for @cite{n} different curves which share a common ``x'' value in +the @cite{n+1}st stack entry. (Thus @kbd{g a} with no prefix +argument is equivalent to @kbd{C-u 1 g a}.) + +A prefix of zero or plain @kbd{C-u} means to take two stack entries, +``x'' and ``y'' as usual, but to interpret ``y'' as a vector of +``y'' values for several curves that share a common ``x''. + +A negative prefix argument tells Calc to read @cite{n} vectors from +the stack; each vector @cite{[x, y]} describes an independent curve. +This is the only form of @kbd{g a} that creates several curves at once +that don't have common ``x'' values. (Of course, the range of ``x'' +values covered by all the curves ought to be roughly the same if +they are to look nice on the same graph.) + +For example, to plot @c{$\sin n x$} +@cite{sin(n x)} for integers @cite{n} +from 1 to 5, you could use @kbd{v x} to create a vector of integers +(@cite{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)} +across this vector. The resulting vector of formulas is suitable +for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f} +command. + +@kindex g A +@pindex calc-graph-add-3d +The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve +to the graph. It is not legal to intermix 2D and 3D curves in a +single graph. This command takes three arguments, ``x'', ``y'', +and ``z'', from the stack. With a positive prefix @cite{n}, it +takes @cite{n+2} arguments (common ``x'' and ``y'', plus @cite{n} +separate ``z''s). With a zero prefix, it takes three stack entries +but the ``z'' entry is a vector of curve values. With a negative +prefix @cite{-n}, it takes @cite{n} vectors of the form @cite{[x, y, z]}. +The @kbd{g A} command works by adding a @code{splot} (surface-plot) +command to the @samp{*Gnuplot Commands*} buffer. + +(Although @kbd{g a} adds a 2D @code{plot} command to the +@samp{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} +before sending it to GNUPLOT if it notices that the data points are +evaluating to @code{xyz} calls. It will not work to mix 2D and 3D +@kbd{g a} curves in a single graph, although Calc does not currently +check for this.) + +@kindex g d +@pindex calc-graph-delete +The @kbd{g d} (@code{calc-graph-delete}) command deletes the most +recently added curve from the graph. It has no effect if there are +no curves in the graph. With a numeric prefix argument of any kind, +it deletes all of the curves from the graph. + +@kindex g H +@pindex calc-graph-hide +The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides'' +the most recently added curve. A hidden curve will not appear in +the actual plot, but information about it such as its name and line and +point styles will be retained. + +@kindex g j +@pindex calc-graph-juggle +The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve +at the end of the list (the ``most recently added curve'') to the +front of the list. The next-most-recent curve is thus exposed for +@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work +with any curve in the graph even though curve-related commands only +affect the last curve in the list. + +@kindex g p +@pindex calc-graph-plot +The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw +the graph described in the @samp{*Gnuplot Commands*} buffer. Any +GNUPLOT parameters which are not defined by commands in this buffer +are reset to their default values. The variables named in the @code{plot} +command are written to a temporary data file and the variable names +are then replaced by the file name in the template. The resulting +plotting commands are fed to the GNUPLOT program. See the documentation +for the GNUPLOT program for more specific information. All temporary +files are removed when Emacs or GNUPLOT exits. + +If you give a formula for ``y'', Calc will remember all the values that +it calculates for the formula so that later plots can reuse these values. +Calc throws out these saved values when you change any circumstances +that may affect the data, such as switching from Degrees to Radians +mode, or changing the value of a parameter in the formula. You can +force Calc to recompute the data from scratch by giving a negative +numeric prefix argument to @kbd{g p}. + +Calc uses a fairly rough step size when graphing formulas over intervals. +This is to ensure quick response. You can ``refine'' a plot by giving +a positive numeric prefix argument to @kbd{g p}. Calc goes through +the data points it has computed and saved from previous plots of the +function, and computes and inserts a new data point midway between +each of the existing points. You can refine a plot any number of times, +but beware that the amount of calculation involved doubles each time. + +Calc does not remember computed values for 3D graphs. This means the +numerix prefix argument, if any, to @kbd{g p} is effectively ignored if +the current graph is three-dimensional. + +@kindex g P +@pindex calc-graph-print +The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p}, +except that it sends the output to a printer instead of to the +screen. More precisely, @kbd{g p} looks for @samp{set terminal} +or @samp{set output} commands in the @samp{*Gnuplot Commands*} buffer; +lacking these it uses the default settings. However, @kbd{g P} +ignores @samp{set terminal} and @samp{set output} commands and +uses a different set of default values. All of these values are +controlled by the @kbd{g D} and @kbd{g O} commands discussed below. +Provided everything is set up properly, @kbd{g p} will plot to +the screen unless you have specified otherwise and @kbd{g P} will +always plot to the printer. + +@node Graphics Options, Devices, Managing Curves, Graphics +@section Graphics Options + +@noindent +@kindex g g +@pindex calc-graph-grid +The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid'' +on and off. It is off by default; tick marks appear only at the +edges of the graph. With the grid turned on, dotted lines appear +across the graph at each tick mark. Note that this command only +changes the setting in @samp{*Gnuplot Commands*}; to see the effects +of the change you must give another @kbd{g p} command. + +@kindex g b +@pindex calc-graph-border +The @kbd{g b} (@code{calc-graph-border}) command turns the border +(the box that surrounds the graph) on and off. It is on by default. +This command will only work with GNUPLOT 3.0 and later versions. + +@kindex g k +@pindex calc-graph-key +The @kbd{g k} (@code{calc-graph-key}) command turns the ``key'' +on and off. The key is a chart in the corner of the graph that +shows the correspondence between curves and line styles. It is +off by default, and is only really useful if you have several +curves on the same graph. + +@kindex g N +@pindex calc-graph-num-points +The @kbd{g N} (@code{calc-graph-num-points}) command allows you +to select the number of data points in the graph. This only affects +curves where neither ``x'' nor ``y'' is specified as a vector. +Enter a blank line to revert to the default value (initially 15). +With no prefix argument, this command affects only the current graph. +With a positive prefix argument this command changes or, if you enter +a blank line, displays the default number of points used for all +graphs created by @kbd{g a} that don't specify the resolution explicitly. +With a negative prefix argument, this command changes or displays +the default value (initially 5) used for 3D graphs created by @kbd{g A}. +Note that a 3D setting of 5 means that a total of @cite{5^2 = 25} points +will be computed for the surface. + +Data values in the graph of a function are normally computed to a +precision of five digits, regardless of the current precision at the +time. This is usually more than adequate, but there are cases where +it will not be. For example, plotting @cite{1 + x} with @cite{x} in the +interval @samp{[0 ..@: 1e-6]} will round all the data points down +to 1.0! Putting the command @samp{set precision @var{n}} in the +@samp{*Gnuplot Commands*} buffer will cause the data to be computed +at precision @var{n} instead of 5. Since this is such a rare case, +there is no keystroke-based command to set the precision. + +@kindex g h +@pindex calc-graph-header +The @kbd{g h} (@code{calc-graph-header}) command sets the title +for the graph. This will show up centered above the graph. +The default title is blank (no title). + +@kindex g n +@pindex calc-graph-name +The @kbd{g n} (@code{calc-graph-name}) command sets the title of an +individual curve. Like the other curve-manipulating commands, it +affects the most recently added curve, i.e., the last curve on the +list in the @samp{*Gnuplot Commands*} buffer. To set the title of +the other curves you must first juggle them to the end of the list +with @kbd{g j}, or edit the @samp{*Gnuplot Commands*} buffer by hand. +Curve titles appear in the key; if the key is turned off they are +not used. + +@kindex g t +@kindex g T +@pindex calc-graph-title-x +@pindex calc-graph-title-y +The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T} +(@code{calc-graph-title-y}) commands set the titles on the ``x'' +and ``y'' axes, respectively. These titles appear next to the +tick marks on the left and bottom edges of the graph, respectively. +Calc does not have commands to control the tick marks themselves, +but you can edit them into the @samp{*Gnuplot Commands*} buffer if +you wish. See the GNUPLOT documentation for details. + +@kindex g r +@kindex g R +@pindex calc-graph-range-x +@pindex calc-graph-range-y +The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R} +(@code{calc-graph-range-y}) commands set the range of values on the +``x'' and ``y'' axes, respectively. You are prompted to enter a +suitable range. This should be either a pair of numbers of the +form, @samp{@var{min}:@var{max}}, or a blank line to revert to the +default behavior of setting the range based on the range of values +in the data, or @samp{$} to take the range from the top of the stack. +Ranges on the stack can be represented as either interval forms or +vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}. + +@kindex g l +@kindex g L +@pindex calc-graph-log-x +@pindex calc-graph-log-y +The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y}) +commands allow you to set either or both of the axes of the graph to +be logarithmic instead of linear. + +@kindex g C-l +@kindex g C-r +@kindex g C-t +@pindex calc-graph-log-z +@pindex calc-graph-range-z +@pindex calc-graph-title-z +For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are +letters with the Control key held down) are the corresponding commands +for the ``z'' axis. + +@kindex g z +@kindex g Z +@pindex calc-graph-zero-x +@pindex calc-graph-zero-y +The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z} +(@code{calc-graph-zero-y}) commands control whether a dotted line is +drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same +dotted lines that would be drawn there anyway if you used @kbd{g g} to +turn the ``grid'' feature on.) Zero-axis lines are on by default, and +may be turned off only in GNUPLOT 3.0 and later versions. They are +not available for 3D plots. + +@kindex g s +@pindex calc-graph-line-style +The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting +lines on or off for the most recently added curve, and optionally selects +the style of lines to be used for that curve. Plain @kbd{g s} simply +toggles the lines on and off. With a numeric prefix argument, @kbd{g s} +turns lines on and sets a particular line style. Line style numbers +start at one and their meanings vary depending on the output device. +GNUPLOT guarantees that there will be at least six different line styles +available for any device. + +@kindex g S +@pindex calc-graph-point-style +The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns +the symbols at the data points on or off, or sets the point style. +If you turn both lines and points off, the data points will show as +tiny dots. + +@cindex @code{LineStyles} variable +@cindex @code{PointStyles} variable +@vindex LineStyles +@vindex PointStyles +Another way to specify curve styles is with the @code{LineStyles} and +@code{PointStyles} variables. These variables initially have no stored +values, but if you store a vector of integers in one of these variables, +the @kbd{g a} and @kbd{g f} commands will use those style numbers +instead of the defaults for new curves that are added to the graph. +An entry should be a positive integer for a specific style, or 0 to let +the style be chosen automatically, or @i{-1} to turn off lines or points +altogether. If there are more curves than elements in the vector, the +last few curves will continue to have the default styles. Of course, +you can later use @kbd{g s} and @kbd{g S} to change any of these styles. + +For example, @kbd{'[2 -1 3] RET s t LineStyles} causes the first curve +to have lines in style number 2, the second curve to have no connecting +lines, and the third curve to have lines in style 3. Point styles will +still be assigned automatically, but you could store another vector in +@code{PointStyles} to define them, too. + +@node Devices, , Graphics Options, Graphics +@section Graphical Devices + +@noindent +@kindex g D +@pindex calc-graph-device +The @kbd{g D} (@code{calc-graph-device}) command sets the device name +(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands +on this graph. It does not affect the permanent default device name. +If you enter a blank name, the device name reverts to the default. +Enter @samp{?} to see a list of supported devices. + +With a positive numeric prefix argument, @kbd{g D} instead sets +the default device name, used by all plots in the future which do +not override it with a plain @kbd{g D} command. If you enter a +blank line this command shows you the current default. The special +name @code{default} signifies that Calc should choose @code{x11} if +the X window system is in use (as indicated by the presence of a +@code{DISPLAY} environment variable), or otherwise @code{dumb} under +GNUPLOT 3.0 and later, or @code{postscript} under GNUPLOT 2.0. +This is the initial default value. + +The @code{dumb} device is an interface to ``dumb terminals,'' i.e., +terminals with no special graphics facilities. It writes a crude +picture of the graph composed of characters like @code{-} and @code{|} +to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays. +The graph is made the same size as the Emacs screen, which on most +dumb terminals will be @c{$80\times24$} +@asis{80x24} characters. The graph is displayed in +an Emacs ``recursive edit''; type @kbd{q} or @kbd{M-# M-#} to exit +the recursive edit and return to Calc. Note that the @code{dumb} +device is present only in GNUPLOT 3.0 and later versions. + +The word @code{dumb} may be followed by two numbers separated by +spaces. These are the desired width and height of the graph in +characters. Also, the device name @code{big} is like @code{dumb} +but creates a graph four times the width and height of the Emacs +screen. You will then have to scroll around to view the entire +graph. In the @samp{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, +@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each +of the four directions. + +With a negative numeric prefix argument, @kbd{g D} sets or displays +the device name used by @kbd{g P} (@code{calc-graph-print}). This +is initially @code{postscript}. If you don't have a PostScript +printer, you may decide once again to use @code{dumb} to create a +plot on any text-only printer. + +@kindex g O +@pindex calc-graph-output +The @kbd{g O} (@code{calc-graph-output}) command sets the name of +the output file used by GNUPLOT. For some devices, notably @code{x11}, +there is no output file and this information is not used. Many other +``devices'' are really file formats like @code{postscript}; in these +cases the output in the desired format goes into the file you name +with @kbd{g O}. Type @kbd{g O stdout RET} to set GNUPLOT to write +to its standard output stream, i.e., to @samp{*Gnuplot Trail*}. +This is the default setting. + +Another special output name is @code{tty}, which means that GNUPLOT +is going to write graphics commands directly to its standard output, +which you wish Emacs to pass through to your terminal. Tektronix +graphics terminals, among other devices, operate this way. Calc does +this by telling GNUPLOT to write to a temporary file, then running a +sub-shell executing the command @samp{cat tempfile >/dev/tty}. On +typical Unix systems, this will copy the temporary file directly to +the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l} +to Emacs afterwards to refresh the screen. + +Once again, @kbd{g O} with a positive or negative prefix argument +sets the default or printer output file names, respectively. In each +case you can specify @code{auto}, which causes Calc to invent a temporary +file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file +will be deleted once it has been displayed or printed. If the output file +name is not @code{auto}, the file is not automatically deleted. + +The default and printer devices and output files can be saved +permanently by the @kbd{m m} (@code{calc-save-modes}) command. The +default number of data points (see @kbd{g N}) and the X geometry +(see @kbd{g X}) are also saved. Other graph information is @emph{not} +saved; you can save a graph's configuration simply by saving the contents +of the @samp{*Gnuplot Commands*} buffer. + +@vindex calc-gnuplot-plot-command +@vindex calc-gnuplot-default-device +@vindex calc-gnuplot-default-output +@vindex calc-gnuplot-print-command +@vindex calc-gnuplot-print-device +@vindex calc-gnuplot-print-output +If you are installing Calc you may wish to configure the default and +printer devices and output files for the whole system. The relevant +Lisp variables are @code{calc-gnuplot-default-device} and @code{-output}, +and @code{calc-gnuplot-print-device} and @code{-output}. The output +file names must be either strings as described above, or Lisp +expressions which are evaluated on the fly to get the output file names. + +Other important Lisp variables are @code{calc-gnuplot-plot-command} and +@code{calc-gnuplot-print-command}, which give the system commands to +display or print the output of GNUPLOT, respectively. These may be +@code{nil} if no command is necessary, or strings which can include +@samp{%s} to signify the name of the file to be displayed or printed. +Or, these variables may contain Lisp expressions which are evaluated +to display or print the output. + +@kindex g x +@pindex calc-graph-display +The @kbd{g x} (@code{calc-graph-display}) command lets you specify +on which X window system display your graphs should be drawn. Enter +a blank line to see the current display name. This command has no +effect unless the current device is @code{x11}. + +@kindex g X +@pindex calc-graph-geometry +The @kbd{g X} (@code{calc-graph-geometry}) command is a similar +command for specifying the position and size of the X window. +The normal value is @code{default}, which generally means your +window manager will let you place the window interactively. +Entering @samp{800x500+0+0} would create an 800-by-500 pixel +window in the upper-left corner of the screen. + +The buffer called @samp{*Gnuplot Trail*} holds a transcript of the +session with GNUPLOT. This shows the commands Calc has ``typed'' to +GNUPLOT and the responses it has received. Calc tries to notice when an +error message has appeared here and display the buffer for you when +this happens. You can check this buffer yourself if you suspect +something has gone wrong. + +@kindex g C +@pindex calc-graph-command +The @kbd{g C} (@code{calc-graph-command}) command prompts you to +enter any line of text, then simply sends that line to the current +GNUPLOT process. The @samp{*Gnuplot Trail*} buffer looks deceptively +like a Shell buffer but you can't type commands in it yourself. +Instead, you must use @kbd{g C} for this purpose. + +@kindex g v +@kindex g V +@pindex calc-graph-view-commands +@pindex calc-graph-view-trail +The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V} +(@code{calc-graph-view-trail}) commands display the @samp{*Gnuplot Commands*} +and @samp{*Gnuplot Trail*} buffers, respectively, in another window. +This happens automatically when Calc thinks there is something you +will want to see in either of these buffers. If you type @kbd{g v} +or @kbd{g V} when the relevant buffer is already displayed, the +buffer is hidden again. + +One reason to use @kbd{g v} is to add your own commands to the +@samp{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use +@kbd{C-x o} to switch into that window. For example, GNUPLOT has +@samp{set label} and @samp{set arrow} commands that allow you to +annotate your plots. Since Calc doesn't understand these commands, +you have to add them to the @samp{*Gnuplot Commands*} buffer +yourself, then use @w{@kbd{g p}} to replot using these new commands. Note +that your commands must appear @emph{before} the @code{plot} command. +To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}. +You may have to type @kbd{g C RET} a few times to clear the +``press return for more'' or ``subtopic of @dots{}'' requests. +Note that Calc always sends commands (like @samp{set nolabel}) to +reset all plotting parameters to the defaults before each plot, so +to delete a label all you need to do is delete the @samp{set label} +line you added (or comment it out with @samp{#}) and then replot +with @kbd{g p}. + +@kindex g q +@pindex calc-graph-quit +You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT +process that is running. The next graphing command you give will +start a fresh GNUPLOT process. The word @samp{Graph} appears in +the Calc window's mode line whenever a GNUPLOT process is currently +running. The GNUPLOT process is automatically killed when you +exit Emacs if you haven't killed it manually by then. + +@kindex g K +@pindex calc-graph-kill +The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q} +except that it also views the @samp{*Gnuplot Trail*} buffer so that +you can see the process being killed. This is better if you are +killing GNUPLOT because you think it has gotten stuck. + +@node Kill and Yank, Keypad Mode, Graphics, Top +@chapter Kill and Yank Functions + +@noindent +The commands in this chapter move information between the Calculator and +other Emacs editing buffers. + +In many cases Embedded Mode is an easier and more natural way to +work with Calc from a regular editing buffer. @xref{Embedded Mode}. + +@menu +* Killing From Stack:: +* Yanking Into Stack:: +* Grabbing From Buffers:: +* Yanking Into Buffers:: +* X Cut and Paste:: +@end menu + +@node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank +@section Killing from the Stack + +@noindent +@kindex C-k +@pindex calc-kill +@kindex M-k +@pindex calc-copy-as-kill +@kindex C-w +@pindex calc-kill-region +@kindex M-w +@pindex calc-copy-region-as-kill +@cindex Kill ring +@dfn{Kill} commands are Emacs commands that insert text into the +``kill ring,'' from which it can later be ``yanked'' by a @kbd{C-y} +command. Three common kill commands in normal Emacs are @kbd{C-k}, which +kills one line, @kbd{C-w}, which kills the region between mark and point, +and @kbd{M-w}, which puts the region into the kill ring without actually +deleting it. All of these commands work in the Calculator, too. Also, +@kbd{M-k} has been provided to complete the set; it puts the current line +into the kill ring without deleting anything. + +The kill commands are unusual in that they pay attention to the location +of the cursor in the Calculator buffer. If the cursor is on or below the +bottom line, the kill commands operate on the top of the stack. Otherwise, +they operate on whatever stack element the cursor is on. Calc's kill +commands always operate on whole stack entries. (They act the same as their +standard Emacs cousins except they ``round up'' the specified region to +encompass full lines.) The text is copied into the kill ring exactly as +it appears on the screen, including line numbers if they are enabled. + +A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number +of lines killed. A positive argument kills the current line and @cite{n-1} +lines below it. A negative argument kills the @cite{-n} lines above the +current line. Again this mirrors the behavior of the standard Emacs +@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k} +with no argument copies only the number itself into the kill ring, whereas +@kbd{C-k} with a prefix argument of 1 copies the number with its trailing +newline. + +@node Yanking Into Stack, Grabbing From Buffers, Killing From Stack, Kill and Yank +@section Yanking into the Stack + +@noindent +@kindex C-y +@pindex calc-yank +The @kbd{C-y} command yanks the most recently killed text back into the +Calculator. It pushes this value onto the top of the stack regardless of +the cursor position. In general it re-parses the killed text as a number +or formula (or a list of these separated by commas or newlines). However if +the thing being yanked is something that was just killed from the Calculator +itself, its full internal structure is yanked. For example, if you have +set the floating-point display mode to show only four significant digits, +then killing and re-yanking 3.14159 (which displays as 3.142) will yank the +full 3.14159, even though yanking it into any other buffer would yank the +number in its displayed form, 3.142. (Since the default display modes +show all objects to their full precision, this feature normally makes no +difference.) + +@node Grabbing From Buffers, Yanking Into Buffers, Yanking Into Stack, Kill and Yank +@section Grabbing from Other Buffers + +@noindent +@kindex M-# g +@pindex calc-grab-region +The @kbd{M-# g} (@code{calc-grab-region}) command takes the text between +point and mark in the current buffer and attempts to parse it as a +vector of values. Basically, it wraps the text in vector brackets +@samp{[ ]} unless the text already is enclosed in vector brackets, +then reads the text as if it were an algebraic entry. The contents +of the vector may be numbers, formulas, or any other Calc objects. +If the @kbd{M-# g} command works successfully, it does an automatic +@kbd{M-# c} to enter the Calculator buffer. + +A numeric prefix argument grabs the specified number of lines around +point, ignoring the mark. A positive prefix grabs from point to the +@cite{n}th following newline (so that @kbd{M-1 M-# g} grabs from point +to the end of the current line); a negative prefix grabs from point +back to the @cite{n+1}st preceding newline. In these cases the text +that is grabbed is exactly the same as the text that @kbd{C-k} would +delete given that prefix argument. + +A prefix of zero grabs the current line; point may be anywhere on the +line. + +A plain @kbd{C-u} prefix interprets the region between point and mark +as a single number or formula rather than a vector. For example, +@kbd{M-# g} on the text @samp{2 a b} produces the vector of three +values @samp{[2, a, b]}, but @kbd{C-u M-# g} on the same region +reads a formula which is a product of three things: @samp{2 a b}. +(The text @samp{a + b}, on the other hand, will be grabbed as a +vector of one element by plain @kbd{M-# g} because the interpretation +@samp{[a, +, b]} would be a syntax error.) + +If a different language has been specified (@pxref{Language Modes}), +the grabbed text will be interpreted according to that language. + +@kindex M-# r +@pindex calc-grab-rectangle +The @kbd{M-# r} (@code{calc-grab-rectangle}) command takes the text between +point and mark and attempts to parse it as a matrix. If point and mark +are both in the leftmost column, the lines in between are parsed in their +entirety. Otherwise, point and mark define the corners of a rectangle +whose contents are parsed. + +Each line of the grabbed area becomes a row of the matrix. The result +will actually be a vector of vectors, which Calc will treat as a matrix +only if every row contains the same number of values. + +If a line contains a portion surrounded by square brackets (or curly +braces), that portion is interpreted as a vector which becomes a row +of the matrix. Any text surrounding the bracketed portion on the line +is ignored. + +Otherwise, the entire line is interpreted as a row vector as if it +were surrounded by square brackets. Leading line numbers (in the +format used in the Calc stack buffer) are ignored. If you wish to +force this interpretation (even if the line contains bracketed +portions), give a negative numeric prefix argument to the +@kbd{M-# r} command. + +If you give a numeric prefix argument of zero or plain @kbd{C-u}, each +line is instead interpreted as a single formula which is converted into +a one-element vector. Thus the result of @kbd{C-u M-# r} will be a +one-column matrix. For example, suppose one line of the data is the +expression @samp{2 a}. A plain @w{@kbd{M-# r}} will interpret this as +@samp{[2 a]}, which in turn is read as a two-element vector that forms +one row of the matrix. But a @kbd{C-u M-# r} will interpret this row +as @samp{[2*a]}. + +If you give a positive numeric prefix argument @var{n}, then each line +will be split up into columns of width @var{n}; each column is parsed +separately as a matrix element. If a line contained +@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8 +would correctly split the line into two error forms.@refill + +@xref{Matrix Functions}, to see how to pull the matrix apart into its +constituent rows and columns. (If it is a @c{$1\times1$} +@asis{1x1} matrix, just hit @kbd{v u} +(@code{calc-unpack}) twice.) + +@kindex M-# : +@kindex M-# _ +@pindex calc-grab-sum-across +@pindex calc-grab-sum-down +@cindex Summing rows and columns of data +The @kbd{M-# :} (@code{calc-grab-sum-down}) command is a handy way to +grab a rectangle of data and sum its columns. It is equivalent to +typing @kbd{M-# r}, followed by @kbd{V R : +} (the vector reduction +command that sums the columns of a matrix; @pxref{Reducing}). The +result of the command will be a vector of numbers, one for each column +in the input data. The @kbd{M-# _} (@code{calc-grab-sum-across}) command +similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}. + +As well as being more convenient, @kbd{M-# :} and @kbd{M-# _} are also +much faster because they don't actually place the grabbed vector on +the stack. In a @kbd{M-# r V R : +} sequence, formatting the vector +for display on the stack takes a large fraction of the total time +(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes). + +For example, suppose we have a column of numbers in a file which we +wish to sum. Go to one corner of the column and press @kbd{C-@@} to +set the mark; go to the other corner and type @kbd{M-# :}. Since there +is only one column, the result will be a vector of one number, the sum. +(You can type @kbd{v u} to unpack this vector into a plain number if +you want to do further arithmetic with it.) + +To compute the product of the column of numbers, we would have to do +it ``by hand'' since there's no special grab-and-multiply command. +Use @kbd{M-# r} to grab the column of numbers into the calculator in +the form of a column matrix. The statistics command @kbd{u *} is a +handy way to find the product of a vector or matrix of numbers. +@xref{Statistical Operations}. Another approach would be to use +an explicit column reduction command, @kbd{V R : *}. + +@node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank +@section Yanking into Other Buffers + +@noindent +@kindex y +@pindex calc-copy-to-buffer +The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number +at the top of the stack into the most recently used normal editing buffer. +(More specifically, this is the most recently used buffer which is displayed +in a window and whose name does not begin with @samp{*}. If there is no +such buffer, this is the most recently used buffer except for Calculator +and Calc Trail buffers.) The number is inserted exactly as it appears and +without a newline. (If line-numbering is enabled, the line number is +normally not included.) The number is @emph{not} removed from the stack. + +With a prefix argument, @kbd{y} inserts several numbers, one per line. +A positive argument inserts the specified number of values from the top +of the stack. A negative argument inserts the @cite{n}th value from the +top of the stack. An argument of zero inserts the entire stack. Note +that @kbd{y} with an argument of 1 is slightly different from @kbd{y} +with no argument; the former always copies full lines, whereas the +latter strips off the trailing newline. + +With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the +region in the other buffer with the yanked text, then quits the +Calculator, leaving you in that buffer. A typical use would be to use +@kbd{M-# g} to read a region of data into the Calculator, operate on the +data to produce a new matrix, then type @kbd{C-u y} to replace the +original data with the new data. One might wish to alter the matrix +display style (@pxref{Vector and Matrix Formats}) or change the current +display language (@pxref{Language Modes}) before doing this. Also, note +that this command replaces a linear region of text (as grabbed by +@kbd{M-# g}), not a rectangle (as grabbed by @kbd{M-# r}).@refill + +If the editing buffer is in overwrite (as opposed to insert) mode, +and the @kbd{C-u} prefix was not used, then the yanked number will +overwrite the characters following point rather than being inserted +before those characters. The usual conventions of overwrite mode +are observed; for example, characters will be inserted at the end of +a line rather than overflowing onto the next line. Yanking a multi-line +object such as a matrix in overwrite mode overwrites the next @var{n} +lines in the buffer, lengthening or shortening each line as necessary. +Finally, if the thing being yanked is a simple integer or floating-point +number (like @samp{-1.2345e-3}) and the characters following point also +make up such a number, then Calc will replace that number with the new +number, lengthening or shortening as necessary. The concept of +``overwrite mode'' has thus been generalized from overwriting characters +to overwriting one complete number with another. + +@kindex M-# y +The @kbd{M-# y} key sequence is equivalent to @kbd{y} except that +it can be typed anywhere, not just in Calc. This provides an easy +way to guarantee that Calc knows which editing buffer you want to use! + +@node X Cut and Paste, , Yanking Into Buffers, Kill and Yank +@section X Cut and Paste + +@noindent +If you are using Emacs with the X window system, there is an easier +way to move small amounts of data into and out of the calculator: +Use the mouse-oriented cut and paste facilities of X. + +The default bindings for a three-button mouse cause the left button +to move the Emacs cursor to the given place, the right button to +select the text between the cursor and the clicked location, and +the middle button to yank the selection into the buffer at the +clicked location. So, if you have a Calc window and an editing +window on your Emacs screen, you can use left-click/right-click +to select a number, vector, or formula from one window, then +middle-click to paste that value into the other window. When you +paste text into the Calc window, Calc interprets it as an algebraic +entry. It doesn't matter where you click in the Calc window; the +new value is always pushed onto the top of the stack. + +The @code{xterm} program that is typically used for general-purpose +shell windows in X interprets the mouse buttons in the same way. +So you can use the mouse to move data between Calc and any other +Unix program. One nice feature of @code{xterm} is that a double +left-click selects one word, and a triple left-click selects a +whole line. So you can usually transfer a single number into Calc +just by double-clicking on it in the shell, then middle-clicking +in the Calc window. + +@node Keypad Mode, Embedded Mode, Kill and Yank, Introduction +@chapter ``Keypad'' Mode + +@noindent +@kindex M-# k +@pindex calc-keypad +The @kbd{M-# k} (@code{calc-keypad}) command starts the Calculator +and displays a picture of a calculator-style keypad. If you are using +the X window system, you can click on any of the ``keys'' in the +keypad using the left mouse button to operate the calculator. +The original window remains the selected window; in keypad mode +you can type in your file while simultaneously performing +calculations with the mouse. + +@pindex full-calc-keypad +If you have used @kbd{M-# b} first, @kbd{M-# k} instead invokes +the @code{full-calc-keypad} command, which takes over the whole +Emacs screen and displays the keypad, the Calc stack, and the Calc +trail all at once. This mode would normally be used when running +Calc standalone (@pxref{Standalone Operation}). + +If you aren't using the X window system, you must switch into +the @samp{*Calc Keypad*} window, place the cursor on the desired +``key,'' and type @key{SPC} or @key{RET}. If you think this +is easier than using Calc normally, go right ahead. + +Calc commands are more or less the same in keypad mode. Certain +keypad keys differ slightly from the corresponding normal Calc +keystrokes; all such deviations are described below. + +Keypad Mode includes many more commands than will fit on the keypad +at once. Click the right mouse button [@code{calc-keypad-menu}] +to switch to the next menu. The bottom five rows of the keypad +stay the same; the top three rows change to a new set of commands. +To return to earlier menus, click the middle mouse button +[@code{calc-keypad-menu-back}] or simply advance through the menus +until you wrap around. Typing @key{TAB} inside the keypad window +is equivalent to clicking the right mouse button there. + +You can always click the @key{EXEC} button and type any normal +Calc key sequence. This is equivalent to switching into the +Calc buffer, typing the keys, then switching back to your +original buffer. + +@menu +* Keypad Main Menu:: +* Keypad Functions Menu:: +* Keypad Binary Menu:: +* Keypad Vectors Menu:: +* Keypad Modes Menu:: +@end menu + +@node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode +@section Main Menu + +@group +@smallexample +|----+-----Calc 2.00-----+----1 +|FLR |CEIL|RND |TRNC|CLN2|FLT | +|----+----+----+----+----+----| +| LN |EXP | |ABS |IDIV|MOD | +|----+----+----+----+----+----| +|SIN |COS |TAN |SQRT|y^x |1/x | +|----+----+----+----+----+----| +| ENTER |+/- |EEX |UNDO| <- | +|-----+---+-+--+--+-+---++----| +| INV | 7 | 8 | 9 | / | +|-----+-----+-----+-----+-----| +| HYP | 4 | 5 | 6 | * | +|-----+-----+-----+-----+-----| +|EXEC | 1 | 2 | 3 | - | +|-----+-----+-----+-----+-----| +| OFF | 0 | . | PI | + | +|-----+-----+-----+-----+-----+ +@end smallexample +@end group + +@noindent +This is the menu that appears the first time you start Keypad Mode. +It will show up in a vertical window on the right side of your screen. +Above this menu is the traditional Calc stack display. On a 24-line +screen you will be able to see the top three stack entries. + +The ten digit keys, decimal point, and @key{EEX} key are used for +entering numbers in the obvious way. @key{EEX} begins entry of an +exponent in scientific notation. Just as with regular Calc, the +number is pushed onto the stack as soon as you press @key{ENTER} +or any other function key. + +The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During +numeric entry it changes the sign of the number or of the exponent. +At other times it changes the sign of the number on the top of the +stack. + +The @key{INV} and @key{HYP} keys modify other keys. As well as +having the effects described elsewhere in this manual, Keypad Mode +defines several other ``inverse'' operations. These are described +below and in the following sections. + +The @key{ENTER} key finishes the current numeric entry, or otherwise +duplicates the top entry on the stack. + +The @key{UNDO} key undoes the most recent Calc operation. +@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is +``last arguments'' (@kbd{M-RET}). + +The @key{<-} key acts as a ``backspace'' during numeric entry. +At other times it removes the top stack entry. @kbd{INV <-} +clears the entire stack. @kbd{HYP <-} takes an integer from +the stack, then removes that many additional stack elements. + +The @key{EXEC} key prompts you to enter any keystroke sequence +that would normally work in Calc mode. This can include a +numeric prefix if you wish. It is also possible simply to +switch into the Calc window and type commands in it; there is +nothing ``magic'' about this window when Keypad Mode is active. + +The other keys in this display perform their obvious calculator +functions. @key{CLN2} rounds the top-of-stack by temporarily +reducing the precision by 2 digits. @key{FLT} converts an +integer or fraction on the top of the stack to floating-point. + +The @key{INV} and @key{HYP} keys combined with several of these keys +give you access to some common functions even if the appropriate menu +is not displayed. Obviously you don't need to learn these keys +unless you find yourself wasting time switching among the menus. + +@table @kbd +@item INV +/- +is the same as @key{1/x}. +@item INV + +is the same as @key{SQRT}. +@item INV - +is the same as @key{CONJ}. +@item INV * +is the same as @key{y^x}. +@item INV / +is the same as @key{INV y^x} (the @cite{x}th root of @cite{y}). +@item HYP/INV 1 +are the same as @key{SIN} / @kbd{INV SIN}. +@item HYP/INV 2 +are the same as @key{COS} / @kbd{INV COS}. +@item HYP/INV 3 +are the same as @key{TAN} / @kbd{INV TAN}. +@item INV/HYP 4 +are the same as @key{LN} / @kbd{HYP LN}. +@item INV/HYP 5 +are the same as @key{EXP} / @kbd{HYP EXP}. +@item INV 6 +is the same as @key{ABS}. +@item INV 7 +is the same as @key{RND} (@code{calc-round}). +@item INV 8 +is the same as @key{CLN2}. +@item INV 9 +is the same as @key{FLT} (@code{calc-float}). +@item INV 0 +is the same as @key{IMAG}. +@item INV . +is the same as @key{PREC}. +@item INV ENTER +is the same as @key{SWAP}. +@item HYP ENTER +is the same as @key{RLL3}. +@item INV HYP ENTER +is the same as @key{OVER}. +@item HYP +/- +packs the top two stack entries as an error form. +@item HYP EEX +packs the top two stack entries as a modulo form. +@item INV EEX +creates an interval form; this removes an integer which is one +of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed +by the two limits of the interval. +@end table + +The @kbd{OFF} key turns Calc off; typing @kbd{M-# k} or @kbd{M-# M-#} +again has the same effect. This is analogous to typing @kbd{q} or +hitting @kbd{M-# c} again in the normal calculator. If Calc is +running standalone (the @code{full-calc-keypad} command appeared in the +command line that started Emacs), then @kbd{OFF} is replaced with +@kbd{EXIT}; clicking on this actually exits Emacs itself. + +@node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode +@section Functions Menu + +@group +@smallexample +|----+----+----+----+----+----2 +|IGAM|BETA|IBET|ERF |BESJ|BESY| +|----+----+----+----+----+----| +|IMAG|CONJ| RE |ATN2|RAND|RAGN| +|----+----+----+----+----+----| +|GCD |FACT|DFCT|BNOM|PERM|NXTP| +|----+----+----+----+----+----| +@end smallexample +@end group + +@noindent +This menu provides various operations from the @kbd{f} and @kbd{k} +prefix keys. + +@key{IMAG} multiplies the number on the stack by the imaginary +number @cite{i = (0, 1)}. + +@key{RE} extracts the real part a complex number. @kbd{INV RE} +extracts the imaginary part. + +@key{RAND} takes a number from the top of the stack and computes +a random number greater than or equal to zero but less than that +number. (@xref{Random Numbers}.) @key{RAGN} is the ``random +again'' command; it computes another random number using the +same limit as last time. + +@key{INV GCD} computes the LCM (least common multiple) function. + +@key{INV FACT} is the gamma function. @c{$\Gamma(x) = (x-1)!$} +@cite{gamma(x) = (x-1)!}. + +@key{PERM} is the number-of-permutations function, which is on the +@kbd{H k c} key in normal Calc. + +@key{NXTP} finds the next prime after a number. @kbd{INV NXTP} +finds the previous prime. + +@node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode +@section Binary Menu + +@group +@smallexample +|----+----+----+----+----+----3 +|AND | OR |XOR |NOT |LSH |RSH | +|----+----+----+----+----+----| +|DEC |HEX |OCT |BIN |WSIZ|ARSH| +|----+----+----+----+----+----| +| A | B | C | D | E | F | +|----+----+----+----+----+----| +@end smallexample +@end group + +@noindent +The keys in this menu perform operations on binary integers. +Note that both logical and arithmetic right-shifts are provided. +@key{INV LSH} rotates one bit to the left. + +The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}. +The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}. + +The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the +current radix for display and entry of numbers: Decimal, hexadecimal, +octal, or binary. The six letter keys @key{A} through @key{F} are used +for entering hexadecimal numbers. + +The @key{WSIZ} key displays the current word size for binary operations +and allows you to enter a new word size. You can respond to the prompt +using either the keyboard or the digits and @key{ENTER} from the keypad. +The initial word size is 32 bits. + +@node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode +@section Vectors Menu + +@group +@smallexample +|----+----+----+----+----+----4 +|SUM |PROD|MAX |MAP*|MAP^|MAP$| +|----+----+----+----+----+----| +|MINV|MDET|MTRN|IDNT|CRSS|"x" | +|----+----+----+----+----+----| +|PACK|UNPK|INDX|BLD |LEN |... | +|----+----+----+----+----+----| +@end smallexample +@end group + +@noindent +The keys in this menu operate on vectors and matrices. + +@key{PACK} removes an integer @var{n} from the top of the stack; +the next @var{n} stack elements are removed and packed into a vector, +which is replaced onto the stack. Thus the sequence +@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector +@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row +on the stack as a vector, then use a final @key{PACK} to collect the +rows into a matrix. + +@key{UNPK} unpacks the vector on the stack, pushing each of its +components separately. + +@key{INDX} removes an integer @var{n}, then builds a vector of +integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers +from the stack: The vector size @var{n}, the starting number, +and the increment. @kbd{BLD} takes an integer @var{n} and any +value @var{x} and builds a vector of @var{n} copies of @var{x}. + +@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n} +identity matrix. + +@key{LEN} replaces a vector by its length, an integer. + +@key{...} turns on or off ``abbreviated'' display mode for large vectors. + +@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix +inverse, determinant, and transpose, and vector cross product. + +@key{SUM} replaces a vector by the sum of its elements. It is +equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}). +@key{PROD} computes the product of the elements of a vector, and +@key{MAX} computes the maximum of all the elements of a vector. + +@key{INV SUM} computes the alternating sum of the first element +minus the second, plus the third, minus the fourth, and so on. +@key{INV MAX} computes the minimum of the vector elements. + +@key{HYP SUM} computes the mean of the vector elements. +@key{HYP PROD} computes the sample standard deviation. +@key{HYP MAX} computes the median. + +@key{MAP*} multiplies two vectors elementwise. It is equivalent +to the @kbd{V M *} command. @key{MAP^} computes powers elementwise. +The arguments must be vectors of equal length, or one must be a vector +and the other must be a plain number. For example, @kbd{2 MAP^} squares +all the elements of a vector. + +@key{MAP$} maps the formula on the top of the stack across the +vector in the second-to-top position. If the formula contains +several variables, Calc takes that many vectors starting at the +second-to-top position and matches them to the variables in +alphabetical order. The result is a vector of the same size as +the input vectors, whose elements are the formula evaluated with +the variables set to the various sets of numbers in those vectors. +For example, you could simulate @key{MAP^} using @key{MAP$} with +the formula @samp{x^y}. + +The @kbd{"x"} key pushes the variable name @cite{x} onto the +stack. To build the formula @cite{x^2 + 6}, you would use the +key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be +suitable for use with the @key{MAP$} key described above. +With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the +@kbd{"x"} key pushes the variable names @cite{y}, @cite{z}, and +@cite{t}, respectively. + +@node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode +@section Modes Menu + +@group +@smallexample +|----+----+----+----+----+----5 +|FLT |FIX |SCI |ENG |GRP | | +|----+----+----+----+----+----| +|RAD |DEG |FRAC|POLR|SYMB|PREC| +|----+----+----+----+----+----| +|SWAP|RLL3|RLL4|OVER|STO |RCL | +|----+----+----+----+----+----| +@end smallexample +@end group + +@noindent +The keys in this menu manipulate modes, variables, and the stack. + +The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select +floating-point, fixed-point, scientific, or engineering notation. +@key{FIX} displays two digits after the decimal by default; the +others display full precision. With the @key{INV} prefix, these +keys pop a number-of-digits argument from the stack. + +The @key{GRP} key turns grouping of digits with commas on or off. +@kbd{INV GRP} enables grouping to the right of the decimal point as +well as to the left. + +The @key{RAD} and @key{DEG} keys switch between radians and degrees +for trigonometric functions. + +The @key{FRAC} key turns Fraction mode on or off. This affects +whether commands like @kbd{/} with integer arguments produce +fractional or floating-point results. + +The @key{POLR} key turns Polar mode on or off, determining whether +polar or rectangular complex numbers are used by default. + +The @key{SYMB} key turns Symbolic mode on or off, in which +operations that would produce inexact floating-point results +are left unevaluated as algebraic formulas. + +The @key{PREC} key selects the current precision. Answer with +the keyboard or with the keypad digit and @key{ENTER} keys. + +The @key{SWAP} key exchanges the top two stack elements. +The @key{RLL3} key rotates the top three stack elements upwards. +The @key{RLL4} key rotates the top four stack elements upwards. +The @key{OVER} key duplicates the second-to-top stack element. + +The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and +@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the +@key{STO} or @key{RCL} key, then one of the ten digits. (Named +variables are not available in Keypad Mode.) You can also use, +for example, @kbd{STO + 3} to add to register 3. + +@node Embedded Mode, Programming, Keypad Mode, Top +@chapter Embedded Mode + +@noindent +Embedded Mode in Calc provides an alternative to copying numbers +and formulas back and forth between editing buffers and the Calc +stack. In Embedded Mode, your editing buffer becomes temporarily +linked to the stack and this copying is taken care of automatically. + +@menu +* Basic Embedded Mode:: +* More About Embedded Mode:: +* Assignments in Embedded Mode:: +* Mode Settings in Embedded Mode:: +* Customizing Embedded Mode:: +@end menu + +@node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode +@section Basic Embedded Mode + +@noindent +@kindex M-# e +@pindex calc-embedded +To enter Embedded mode, position the Emacs point (cursor) on a +formula in any buffer and press @kbd{M-# e} (@code{calc-embedded}). +Note that @kbd{M-# e} is not to be used in the Calc stack buffer +like most Calc commands, but rather in regular editing buffers that +are visiting your own files. + +Calc normally scans backward and forward in the buffer for the +nearest opening and closing @dfn{formula delimiters}. The simplest +delimiters are blank lines. Other delimiters that Embedded Mode +understands are: + +@enumerate +@item +The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$}, +@samp{\[ \]}, and @samp{\( \)}; +@item +Lines beginning with @samp{\begin} and @samp{\end}; +@item +Lines beginning with @samp{@@} (Texinfo delimiters). +@item +Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); +@item +Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. +@end enumerate + +@xref{Customizing Embedded Mode}, to see how to make Calc recognize +your own favorite delimiters. Delimiters like @samp{$ $} can appear +on their own separate lines or in-line with the formula. + +If you give a positive or negative numeric prefix argument, Calc +instead uses the current point as one end of the formula, and moves +forward or backward (respectively) by that many lines to find the +other end. Explicit delimiters are not necessary in this case. + +With a prefix argument of zero, Calc uses the current region +(delimited by point and mark) instead of formula delimiters. + +@kindex M-# w +@pindex calc-embedded-word +With a prefix argument of @kbd{C-u} only, Calc scans for the first +non-numeric character (i.e., the first character that is not a +digit, sign, decimal point, or upper- or lower-case @samp{e}) +forward and backward to delimit the formula. @kbd{M-# w} +(@code{calc-embedded-word}) is equivalent to @kbd{C-u M-# e}. + +When you enable Embedded mode for a formula, Calc reads the text +between the delimiters and tries to interpret it as a Calc formula. +It's best if the current Calc language mode is correct for the +formula, but Calc can generally identify @TeX{} formulas and +Big-style formulas even if the language mode is wrong. If Calc +can't make sense of the formula, it beeps and refuses to enter +Embedded mode. But if the current language is wrong, Calc can +sometimes parse the formula successfully (but incorrectly); +for example, the C expression @samp{atan(a[1])} can be parsed +in Normal language mode, but the @code{atan} won't correspond to +the built-in @code{arctan} function, and the @samp{a[1]} will be +interpreted as @samp{a} times the vector @samp{[1]}! + +If you press @kbd{M-# e} or @kbd{M-# w} to activate an embedded +formula which is blank, say with the cursor on the space between +the two delimiters @samp{$ $}, Calc will immediately prompt for +an algebraic entry. + +Only one formula in one buffer can be enabled at a time. If you +move to another area of the current buffer and give Calc commands, +Calc turns Embedded mode off for the old formula and then tries +to restart Embedded mode at the new position. Other buffers are +not affected by Embedded mode. + +When Embedded mode begins, Calc pushes the current formula onto +the stack. No Calc stack window is created; however, Calc copies +the top-of-stack position into the original buffer at all times. +You can create a Calc window by hand with @kbd{M-# o} if you +find you need to see the entire stack. + +For example, typing @kbd{M-# e} while somewhere in the formula +@samp{n>2} in the following line enables Embedded mode on that +inequality: + +@example +We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$. +@end example + +@noindent +The formula @cite{n>2} will be pushed onto the Calc stack, and +the top of stack will be copied back into the editing buffer. +This means that spaces will appear around the @samp{>} symbol +to match Calc's usual display style: + +@example +We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$. +@end example + +@noindent +No spaces have appeared around the @samp{+} sign because it's +in a different formula, one which we have not yet touched with +Embedded mode. + +Now that Embedded mode is enabled, keys you type in this buffer +are interpreted as Calc commands. At this point we might use +the ``commute'' command @kbd{j C} to reverse the inequality. +This is a selection-based command for which we first need to +move the cursor onto the operator (@samp{>} in this case) that +needs to be commuted. + +@example +We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$. +@end example + +The @kbd{M-# o} command is a useful way to open a Calc window +without actually selecting that window. Giving this command +verifies that @samp{2 < n} is also on the Calc stack. Typing +@kbd{17 RET} would produce: + +@example +We define $F_n = F_(n-1)+F_(n-2)$ for all $17$. +@end example + +@noindent +with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB} +at this point will exchange the two stack values and restore +@samp{2 < n} to the embedded formula. Even though you can't +normally see the stack in Embedded mode, it is still there and +it still operates in the same way. But, as with old-fashioned +RPN calculators, you can only see the value at the top of the +stack at any given time (unless you use @kbd{M-# o}). + +Typing @kbd{M-# e} again turns Embedded mode off. The Calc +window reveals that the formula @w{@samp{2 < n}} is automatically +removed from the stack, but the @samp{17} is not. Entering +Embedded mode always pushes one thing onto the stack, and +leaving Embedded mode always removes one thing. Anything else +that happens on the stack is entirely your business as far as +Embedded mode is concerned. + +If you press @kbd{M-# e} in the wrong place by accident, it is +possible that Calc will be able to parse the nearby text as a +formula and will mangle that text in an attempt to redisplay it +``properly'' in the current language mode. If this happens, +press @kbd{M-# e} again to exit Embedded mode, then give the +regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put +the text back the way it was before Calc edited it. Note that Calc's +own Undo command (typed before you turn Embedded mode back off) +will not do you any good, because as far as Calc is concerned +you haven't done anything with this formula yet. + +@node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode +@section More About Embedded Mode + +@noindent +When Embedded mode ``activates'' a formula, i.e., when it examines +the formula for the first time since the buffer was created or +loaded, Calc tries to sense the language in which the formula was +written. If the formula contains any @TeX{}-like @samp{\} sequences, +it is parsed (i.e., read) in @TeX{} mode. If the formula appears to +be written in multi-line Big mode, it is parsed in Big mode. Otherwise, +it is parsed according to the current language mode. + +Note that Calc does not change the current language mode according +to what it finds. Even though it can read a @TeX{} formula when +not in @TeX{} mode, it will immediately rewrite this formula using +whatever language mode is in effect. You must then type @kbd{d T} +to switch Calc permanently into @TeX{} mode if that is what you +desire. + +@tex +\bigskip +@end tex + +@kindex d p +@pindex calc-show-plain +Calc's parser is unable to read certain kinds of formulas. For +example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can +specify matrix display styles which the parser is unable to +recognize as matrices. The @kbd{d p} (@code{calc-show-plain}) +command turns on a mode in which a ``plain'' version of a +formula is placed in front of the fully-formatted version. +When Calc reads a formula that has such a plain version in +front, it reads the plain version and ignores the formatted +version. + +Plain formulas are preceded and followed by @samp{%%%} signs +by default. This notation has the advantage that the @samp{%} +character begins a comment in @TeX{}, so if your formula is +embedded in a @TeX{} document its plain version will be +invisible in the final printed copy. @xref{Customizing +Embedded Mode}, to see how to change the ``plain'' formula +delimiters, say to something that @dfn{eqn} or some other +formatter will treat as a comment. + +There are several notations which Calc's parser for ``big'' +formatted formulas can't yet recognize. In particular, it can't +read the large symbols for @code{sum}, @code{prod}, and @code{integ}, +and it can't handle @samp{=>} with the righthand argument omitted. +Also, Calc won't recognize special formats you have defined with +the @kbd{Z C} command (@pxref{User-Defined Compositions}). In +these cases it is important to use ``plain'' mode to make sure +Calc will be able to read your formula later. + +Another example where ``plain'' mode is important is if you have +specified a float mode with few digits of precision. Normally +any digits that are computed but not displayed will simply be +lost when you save and re-load your embedded buffer, but ``plain'' +mode allows you to make sure that the complete number is present +in the file as well as the rounded-down number. + +@tex +\bigskip +@end tex + +Embedded buffers remember active formulas for as long as they +exist in Emacs memory. Suppose you have an embedded formula +which is @c{$\pi$} +@cite{pi} to the normal 12 decimal places, and then +type @w{@kbd{C-u 5 d n}} to display only five decimal places. +If you then type @kbd{d n}, all 12 places reappear because the +full number is still there on the Calc stack. More surprisingly, +even if you exit Embedded mode and later re-enter it for that +formula, typing @kbd{d n} will restore all 12 places because +each buffer remembers all its active formulas. However, if you +save the buffer in a file and reload it in a new Emacs session, +all non-displayed digits will have been lost unless you used +``plain'' mode. + +@tex +\bigskip +@end tex + +In some applications of Embedded mode, you will want to have a +sequence of copies of a formula that show its evolution as you +work on it. For example, you might want to have a sequence +like this in your file (elaborating here on the example from +the ``Getting Started'' chapter): + +@smallexample +The derivative of + + ln(ln(x)) + +is + + @r{(the derivative of }ln(ln(x))@r{)} + +whose value at x = 2 is + + @r{(the value)} + +and at x = 3 is + + @r{(the value)} +@end smallexample + +@kindex M-# d +@pindex calc-embedded-duplicate +The @kbd{M-# d} (@code{calc-embedded-duplicate}) command is a +handy way to make sequences like this. If you type @kbd{M-# d}, +the formula under the cursor (which may or may not have Embedded +mode enabled for it at the time) is copied immediately below and +Embedded mode is then enabled for that copy. + +For this example, you would start with just + +@smallexample +The derivative of + + ln(ln(x)) +@end smallexample + +@noindent +and press @kbd{M-# d} with the cursor on this formula. The result +is + +@smallexample +The derivative of + + ln(ln(x)) + + + ln(ln(x)) +@end smallexample + +@noindent +with the second copy of the formula enabled in Embedded mode. +You can now press @kbd{a d x RET} to take the derivative, and +@kbd{M-# d M-# d} to make two more copies of the derivative. +To complete the computations, type @kbd{3 s l x RET} to evaluate +the last formula, then move up to the second-to-last formula +and type @kbd{2 s l x RET}. + +Finally, you would want to press @kbd{M-# e} to exit Embedded +mode, then go up and insert the necessary text in between the +various formulas and numbers. + +@tex +\bigskip +@end tex + +@kindex M-# f +@kindex M-# ' +@pindex calc-embedded-new-formula +The @kbd{M-# f} (@code{calc-embedded-new-formula}) command +creates a new embedded formula at the current point. It inserts +some default delimiters, which are usually just blank lines, +and then does an algebraic entry to get the formula (which is +then enabled for Embedded mode). This is just shorthand for +typing the delimiters yourself, positioning the cursor between +the new delimiters, and pressing @kbd{M-# e}. The key sequence +@kbd{M-# '} is equivalent to @kbd{M-# f}. + +@kindex M-# n +@kindex M-# p +@pindex calc-embedded-next +@pindex calc-embedded-previous +The @kbd{M-# n} (@code{calc-embedded-next}) and @kbd{M-# p} +(@code{calc-embedded-previous}) commands move the cursor to the +next or previous active embedded formula in the buffer. They +can take positive or negative prefix arguments to move by several +formulas. Note that these commands do not actually examine the +text of the buffer looking for formulas; they only see formulas +which have previously been activated in Embedded mode. In fact, +@kbd{M-# n} and @kbd{M-# p} are a useful way to tell which +embedded formulas are currently active. Also, note that these +commands do not enable Embedded mode on the next or previous +formula, they just move the cursor. (By the way, @kbd{M-# n} is +not as awkward to type as it may seem, because @kbd{M-#} ignores +Shift and Meta on the second keystroke: @kbd{M-# M-N} can be typed +by holding down Shift and Meta and alternately typing two keys.) + +@kindex M-# ` +@pindex calc-embedded-edit +The @kbd{M-# `} (@code{calc-embedded-edit}) command edits the +embedded formula at the current point as if by @kbd{`} (@code{calc-edit}). +Embedded mode does not have to be enabled for this to work. Press +@kbd{M-# M-#} to finish the edit, or @kbd{M-# x} to cancel. + +@node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode +@section Assignments in Embedded Mode + +@noindent +The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators +are especially useful in Embedded mode. They allow you to make +a definition in one formula, then refer to that definition in +other formulas embedded in the same buffer. + +An embedded formula which is an assignment to a variable, as in + +@example +foo := 5 +@end example + +@noindent +records @cite{5} as the stored value of @code{foo} for the +purposes of Embedded mode operations in the current buffer. It +does @emph{not} actually store @cite{5} as the ``global'' value +of @code{foo}, however. Regular Calc operations, and Embedded +formulas in other buffers, will not see this assignment. + +One way to use this assigned value is simply to create an +Embedded formula elsewhere that refers to @code{foo}, and to press +@kbd{=} in that formula. However, this permanently replaces the +@code{foo} in the formula with its current value. More interesting +is to use @samp{=>} elsewhere: + +@example +foo + 7 => 12 +@end example + +@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}. + +If you move back and change the assignment to @code{foo}, any +@samp{=>} formulas which refer to it are automatically updated. + +@example +foo := 17 + +foo + 7 => 24 +@end example + +The obvious question then is, @emph{how} can one easily change the +assignment to @code{foo}? If you simply select the formula in +Embedded mode and type 17, the assignment itself will be replaced +by the 17. The effect on the other formula will be that the +variable @code{foo} becomes unassigned: + +@example +17 + +foo + 7 => foo + 7 +@end example + +The right thing to do is first to use a selection command (@kbd{j 2} +will do the trick) to select the righthand side of the assignment. +Then, @kbd{17 TAB DEL} will swap the 17 into place (@pxref{Selecting +Subformulas}, to see how this works). + +@kindex M-# j +@pindex calc-embedded-select +The @kbd{M-# j} (@code{calc-embedded-select}) command provides an +easy way to operate on assigments. It is just like @kbd{M-# e}, +except that if the enabled formula is an assignment, it uses +@kbd{j 2} to select the righthand side. If the enabled formula +is an evaluates-to, it uses @kbd{j 1} to select the lefthand side. +A formula can also be a combination of both: + +@example +bar := foo + 3 => 20 +@end example + +@noindent +in which case @kbd{M-# j} will select the middle part (@samp{foo + 3}). + +The formula is automatically deselected when you leave Embedded +mode. + +@kindex M-# u +@kindex M-# = +@pindex calc-embedded-update +Another way to change the assignment to @code{foo} would simply be +to edit the number using regular Emacs editing rather than Embedded +mode. Then, we have to find a way to get Embedded mode to notice +the change. The @kbd{M-# u} or @kbd{M-# =} +(@code{calc-embedded-update-formula}) command is a convenient way +to do this.@refill + +@example +foo := 6 + +foo + 7 => 13 +@end example + +Pressing @kbd{M-# u} is much like pressing @kbd{M-# e = M-# e}, that +is, temporarily enabling Embedded mode for the formula under the +cursor and then evaluating it with @kbd{=}. But @kbd{M-# u} does +not actually use @kbd{M-# e}, and in fact another formula somewhere +else can be enabled in Embedded mode while you use @kbd{M-# u} and +that formula will not be disturbed. + +With a numeric prefix argument, @kbd{M-# u} updates all active +@samp{=>} formulas in the buffer. Formulas which have not yet +been activated in Embedded mode, and formulas which do not have +@samp{=>} as their top-level operator, are not affected by this. +(This is useful only if you have used @kbd{m C}; see below.) + +With a plain @kbd{C-u} prefix, @kbd{C-u M-# u} updates only in the +region between mark and point rather than in the whole buffer. + +@kbd{M-# u} is also a handy way to activate a formula, such as an +@samp{=>} formula that has freshly been typed in or loaded from a +file. + +@kindex M-# a +@pindex calc-embedded-activate +The @kbd{M-# a} (@code{calc-embedded-activate}) command scans +through the current buffer and activates all embedded formulas +that contain @samp{:=} or @samp{=>} symbols. This does not mean +that Embedded mode is actually turned on, but only that the +formulas' positions are registered with Embedded mode so that +the @samp{=>} values can be properly updated as assignments are +changed. + +It is a good idea to type @kbd{M-# a} right after loading a file +that uses embedded @samp{=>} operators. Emacs includes a nifty +``buffer-local variables'' feature that you can use to do this +automatically. The idea is to place near the end of your file +a few lines that look like this: + +@example +--- Local Variables: --- +--- eval:(calc-embedded-activate) --- +--- End: --- +@end example + +@noindent +where the leading and trailing @samp{---} can be replaced by +any suitable strings (which must be the same on all three lines) +or omitted altogether; in a @TeX{} file, @samp{%} would be a good +leading string and no trailing string would be necessary. In a +C program, @samp{/*} and @samp{*/} would be good leading and +trailing strings. + +When Emacs loads a file into memory, it checks for a Local Variables +section like this one at the end of the file. If it finds this +section, it does the specified things (in this case, running +@kbd{M-# a} automatically) before editing of the file begins. +The Local Variables section must be within 3000 characters of the +end of the file for Emacs to find it, and it must be in the last +page of the file if the file has any page separators. +@xref{File Variables, , Local Variables in Files, emacs, the +Emacs manual}. + +Note that @kbd{M-# a} does not update the formulas it finds. +To do this, type, say, @kbd{M-1 M-# u} after @w{@kbd{M-# a}}. +Generally this should not be a problem, though, because the +formulas will have been up-to-date already when the file was +saved. + +Normally, @kbd{M-# a} activates all the formulas it finds, but +any previous active formulas remain active as well. With a +positive numeric prefix argument, @kbd{M-# a} first deactivates +all current active formulas, then actives the ones it finds in +its scan of the buffer. With a negative prefix argument, +@kbd{M-# a} simply deactivates all formulas. + +Embedded mode has two symbols, @samp{Active} and @samp{~Active}, +which it puts next to the major mode name in a buffer's mode line. +It puts @samp{Active} if it has reason to believe that all +formulas in the buffer are active, because you have typed @kbd{M-# a} +and Calc has not since had to deactivate any formulas (which can +happen if Calc goes to update an @samp{=>} formula somewhere because +a variable changed, and finds that the formula is no longer there +due to some kind of editing outside of Embedded mode). Calc puts +@samp{~Active} in the mode line if some, but probably not all, +formulas in the buffer are active. This happens if you activate +a few formulas one at a time but never use @kbd{M-# a}, or if you +used @kbd{M-# a} but then Calc had to deactivate a formula +because it lost track of it. If neither of these symbols appears +in the mode line, no embedded formulas are active in the buffer +(e.g., before Embedded mode has been used, or after a @kbd{M-- M-# a}). + +Embedded formulas can refer to assignments both before and after them +in the buffer. If there are several assignments to a variable, the +nearest preceding assignment is used if there is one, otherwise the +following assignment is used. + +@example +x => 1 + +x := 1 + +x => 1 + +x := 2 + +x => 2 +@end example + +As well as simple variables, you can also assign to subscript +expressions of the form @samp{@var{var}_@var{number}} (as in +@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}). +Assignments to other kinds of objects can be represented by Calc, +but the automatic linkage between assignments and references works +only for plain variables and these two kinds of subscript expressions. + +If there are no assignments to a given variable, the global +stored value for the variable is used (@pxref{Storing Variables}), +or, if no value is stored, the variable is left in symbolic form. +Note that global stored values will be lost when the file is saved +and loaded in a later Emacs session, unless you have used the +@kbd{s p} (@code{calc-permanent-variable}) command to save them; +@pxref{Operations on Variables}. + +The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic +recomputation of @samp{=>} forms on and off. If you turn automatic +recomputation off, you will have to use @kbd{M-# u} to update these +formulas manually after an assignment has been changed. If you +plan to change several assignments at once, it may be more efficient +to type @kbd{m C}, change all the assignments, then use @kbd{M-1 M-# u} +to update the entire buffer afterwards. The @kbd{m C} command also +controls @samp{=>} formulas on the stack; @pxref{Evaluates-To +Operator}. When you turn automatic recomputation back on, the +stack will be updated but the Embedded buffer will not; you must +use @kbd{M-# u} to update the buffer by hand. + +@node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode +@section Mode Settings in Embedded Mode + +@noindent +Embedded Mode has a rather complicated mechanism for handling mode +settings in Embedded formulas. It is possible to put annotations +in the file that specify mode settings either global to the entire +file or local to a particular formula or formulas. In the latter +case, different modes can be specified for use when a formula +is the enabled Embedded Mode formula. + +When you give any mode-setting command, like @kbd{m f} (for fraction +mode) or @kbd{d s} (for scientific notation), Embedded Mode adds +a line like the following one to the file just before the opening +delimiter of the formula. + +@example +% [calc-mode: fractions: t] +% [calc-mode: float-format: (sci 0)] +@end example + +When Calc interprets an embedded formula, it scans the text before +the formula for mode-setting annotations like these and sets the +Calc buffer to match these modes. Modes not explicitly described +in the file are not changed. Calc scans all the way to the top of +the file, or up to a line of the form + +@example +% [calc-defaults] +@end example + +@noindent +which you can insert at strategic places in the file if this backward +scan is getting too slow, or just to provide a barrier between one +``zone'' of mode settings and another. + +If the file contains several annotations for the same mode, the +closest one before the formula is used. Annotations after the +formula are never used (except for global annotations, described +below). + +The scan does not look for the leading @samp{% }, only for the +square brackets and the text they enclose. You can edit the mode +annotations to a style that works better in context if you wish. +@xref{Customizing Embedded Mode}, to see how to change the style +that Calc uses when it generates the annotations. You can write +mode annotations into the file yourself if you know the syntax; +the easiest way to find the syntax for a given mode is to let +Calc write the annotation for it once and see what it does. + +If you give a mode-changing command for a mode that already has +a suitable annotation just above the current formula, Calc will +modify that annotation rather than generating a new, conflicting +one. + +Mode annotations have three parts, separated by colons. (Spaces +after the colons are optional.) The first identifies the kind +of mode setting, the second is a name for the mode itself, and +the third is the value in the form of a Lisp symbol, number, +or list. Annotations with unrecognizable text in the first or +second parts are ignored. The third part is not checked to make +sure the value is of a legal type or range; if you write an +annotation by hand, be sure to give a proper value or results +will be unpredictable. Mode-setting annotations are case-sensitive. + +While Embedded Mode is enabled, the word @code{Local} appears in +the mode line. This is to show that mode setting commands generate +annotations that are ``local'' to the current formula or set of +formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command +causes Calc to generate different kinds of annotations. Pressing +@kbd{m R} repeatedly cycles through the possible modes. + +@code{LocEdit} and @code{LocPerm} modes generate annotations +that look like this, respectively: + +@example +% [calc-edit-mode: float-format: (sci 0)] +% [calc-perm-mode: float-format: (sci 5)] +@end example + +The first kind of annotation will be used only while a formula +is enabled in Embedded Mode. The second kind will be used only +when the formula is @emph{not} enabled. (Whether the formula +is ``active'' or not, i.e., whether Calc has seen this formula +yet, is not relevant here.) + +@code{Global} mode generates an annotation like this at the end +of the file: + +@example +% [calc-global-mode: fractions t] +@end example + +Global mode annotations affect all formulas throughout the file, +and may appear anywhere in the file. This allows you to tuck your +mode annotations somewhere out of the way, say, on a new page of +the file, as long as those mode settings are suitable for all +formulas in the file. + +Enabling a formula with @kbd{M-# e} causes a fresh scan for local +mode annotations; you will have to use this after adding annotations +above a formula by hand to get the formula to notice them. Updating +a formula with @kbd{M-# u} will also re-scan the local modes, but +global modes are only re-scanned by @kbd{M-# a}. + +Another way that modes can get out of date is if you add a local +mode annotation to a formula that has another formula after it. +In this example, we have used the @kbd{d s} command while the +first of the two embedded formulas is active. But the second +formula has not changed its style to match, even though by the +rules of reading annotations the @samp{(sci 0)} applies to it, too. + +@example +% [calc-mode: float-format: (sci 0)] +1.23e2 + +456. +@end example + +We would have to go down to the other formula and press @kbd{M-# u} +on it in order to get it to notice the new annotation. + +Two more mode-recording modes selectable by @kbd{m R} are @code{Save} +(which works even outside of Embedded Mode), in which mode settings +are recorded permanently in your Emacs startup file @file{~/.emacs} +rather than by annotating the current document, and no-recording +mode (where there is no symbol like @code{Save} or @code{Local} in +the mode line), in which mode-changing commands do not leave any +annotations at all. + +When Embedded Mode is not enabled, mode-recording modes except +for @code{Save} have no effect. + +@node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode +@section Customizing Embedded Mode + +@noindent +You can modify Embedded Mode's behavior by setting various Lisp +variables described here. Use @kbd{M-x set-variable} or +@kbd{M-x edit-options} to adjust a variable on the fly, or +put a suitable @code{setq} statement in your @file{~/.emacs} +file to set a variable permanently. (Another possibility would +be to use a file-local variable annotation at the end of the +file; @pxref{File Variables, , Local Variables in Files, emacs, the +Emacs manual}.) + +While none of these variables will be buffer-local by default, you +can make any of them local to any embedded-mode buffer. (Their +values in the @samp{*Calculator*} buffer are never used.) + +@vindex calc-embedded-open-formula +The @code{calc-embedded-open-formula} variable holds a regular +expression for the opening delimiter of a formula. @xref{Regexp Search, +, Regular Expression Search, emacs, the Emacs manual}, to see +how regular expressions work. Basically, a regular expression is a +pattern that Calc can search for. A regular expression that considers +blank lines, @samp{$}, and @samp{$$} to be opening delimiters is +@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this +regular expression is not completely plain, let's go through it +in detail. + +The surrounding @samp{" "} marks quote the text between them as a +Lisp string. If you left them off, @code{set-variable} or +@code{edit-options} would try to read the regular expression as a +Lisp program. + +The most obvious property of this regular expression is that it +contains indecently many backslashes. There are actually two levels +of backslash usage going on here. First, when Lisp reads a quoted +string, all pairs of characters beginning with a backslash are +interpreted as special characters. Here, @code{\n} changes to a +new-line character, and @code{\\} changes to a single backslash. +So the actual regular expression seen by Calc is +@samp{\`\|^ @r{(newline)} \|\$\$?}. + +Regular expressions also consider pairs beginning with backslash +to have special meanings. Sometimes the backslash is used to quote +a character that otherwise would have a special meaning in a regular +expression, like @samp{$}, which normally means ``end-of-line,'' +or @samp{?}, which means that the preceding item is optional. So +@samp{\$\$?} matches either one or two dollar signs. + +The other codes in this regular expression are @samp{^}, which matches +``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`}, +which matches ``beginning-of-buffer.'' So the whole pattern means +that a formula begins at the beginning of the buffer, or on a newline +that occurs at the beginning of a line (i.e., a blank line), or at +one or two dollar signs. + +The default value of @code{calc-embedded-open-formula} looks just +like this example, with several more alternatives added on to +recognize various other common kinds of delimiters. + +By the way, the reason to use @samp{^\n} rather than @samp{^$} +or @samp{\n\n}, which also would appear to match blank lines, +is that the former expression actually ``consumes'' only one +newline character as @emph{part of} the delimiter, whereas the +latter expressions consume zero or two newlines, respectively. +The former choice gives the most natural behavior when Calc +must operate on a whole formula including its delimiters. + +See the Emacs manual for complete details on regular expressions. +But just for your convenience, here is a list of all characters +which must be quoted with backslash (like @samp{\$}) to avoid +some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note +the backslash in this list; for example, to match @samp{\[} you +must use @code{"\\\\\\["}. An exercise for the reader is to +account for each of these six backslashes!) + +@vindex calc-embedded-close-formula +The @code{calc-embedded-close-formula} variable holds a regular +expression for the closing delimiter of a formula. A closing +regular expression to match the above example would be +@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the +other one, except it now uses @samp{\'} (``end-of-buffer'') and +@samp{\n$} (newline occurring at end of line, yet another way +of describing a blank line that is more appropriate for this +case). + +@vindex calc-embedded-open-word +@vindex calc-embedded-close-word +The @code{calc-embedded-open-word} and @code{calc-embedded-close-word} +variables are similar expressions used when you type @kbd{M-# w} +instead of @kbd{M-# e} to enable Embedded mode. + +@vindex calc-embedded-open-plain +The @code{calc-embedded-open-plain} variable is a string which +begins a ``plain'' formula written in front of the formatted +formula when @kbd{d p} mode is turned on. Note that this is an +actual string, not a regular expression, because Calc must be able +to write this string into a buffer as well as to recognize it. +The default string is @code{"%%% "} (note the trailing space). + +@vindex calc-embedded-close-plain +The @code{calc-embedded-close-plain} variable is a string which +ends a ``plain'' formula. The default is @code{" %%%\n"}. Without +the trailing newline here, the first line of a ``big'' mode formula +that followed might be shifted over with respect to the other lines. + +@vindex calc-embedded-open-new-formula +The @code{calc-embedded-open-new-formula} variable is a string +which is inserted at the front of a new formula when you type +@kbd{M-# f}. Its default value is @code{"\n\n"}. If this +string begins with a newline character and the @kbd{M-# f} is +typed at the beginning of a line, @kbd{M-# f} will skip this +first newline to avoid introducing unnecessary blank lines in +the file. + +@vindex calc-embedded-close-new-formula +The @code{calc-embedded-close-new-formula} variable is the corresponding +string which is inserted at the end of a new formula. Its default +value is also @code{"\n\n"}. The final newline is omitted by +@w{@kbd{M-# f}} if typed at the end of a line. (It follows that if +@kbd{M-# f} is typed on a blank line, both a leading opening +newline and a trailing closing newline are omitted.) + +@vindex calc-embedded-announce-formula +The @code{calc-embedded-announce-formula} variable is a regular +expression which is sure to be followed by an embedded formula. +The @kbd{M-# a} command searches for this pattern as well as for +@samp{=>} and @samp{:=} operators. Note that @kbd{M-# a} will +not activate just anything surrounded by formula delimiters; after +all, blank lines are considered formula delimiters by default! +But if your language includes a delimiter which can only occur +actually in front of a formula, you can take advantage of it here. +The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which +checks for @samp{%Embed} followed by any number of lines beginning +with @samp{%} and a space. This last is important to make Calc +consider mode annotations part of the pattern, so that the formula's +opening delimiter really is sure to follow the pattern. + +@vindex calc-embedded-open-mode +The @code{calc-embedded-open-mode} variable is a string (not a +regular expression) which should precede a mode annotation. +Calc never scans for this string; Calc always looks for the +annotation itself. But this is the string that is inserted before +the opening bracket when Calc adds an annotation on its own. +The default is @code{"% "}. + +@vindex calc-embedded-close-mode +The @code{calc-embedded-close-mode} variable is a string which +follows a mode annotation written by Calc. Its default value +is simply a newline, @code{"\n"}. If you change this, it is a +good idea still to end with a newline so that mode annotations +will appear on lines by themselves. + +@node Programming, Installation, Embedded Mode, Top +@chapter Programming + +@noindent +There are several ways to ``program'' the Emacs Calculator, depending +on the nature of the problem you need to solve. + +@enumerate +@item +@dfn{Keyboard macros} allow you to record a sequence of keystrokes +and play them back at a later time. This is just the standard Emacs +keyboard macro mechanism, dressed up with a few more features such +as loops and conditionals. + +@item +@dfn{Algebraic definitions} allow you to use any formula to define a +new function. This function can then be used in algebraic formulas or +as an interactive command. + +@item +@dfn{Rewrite rules} are discussed in the section on algebra commands. +@xref{Rewrite Rules}. If you put your rewrite rules in the variable +@code{EvalRules}, they will be applied automatically to all Calc +results in just the same way as an internal ``rule'' is applied to +evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}. + +@item +@dfn{Lisp} is the programming language that Calc (and most of Emacs) +is written in. If the above techniques aren't powerful enough, you +can write Lisp functions to do anything that built-in Calc commands +can do. Lisp code is also somewhat faster than keyboard macros or +rewrite rules. +@end enumerate + +@kindex z +Programming features are available through the @kbd{z} and @kbd{Z} +prefix keys. New commands that you define are two-key sequences +beginning with @kbd{z}. Commands for managing these definitions +use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing}) +command is described elsewhere; @pxref{Troubleshooting Commands}. +The @kbd{Z C} (@code{calc-user-define-composition}) command is also +described elsewhere; @pxref{User-Defined Compositions}.) + +@menu +* Creating User Keys:: +* Keyboard Macros:: +* Invocation Macros:: +* Algebraic Definitions:: +* Lisp Definitions:: +@end menu + +@node Creating User Keys, Keyboard Macros, Programming, Programming +@section Creating User Keys + +@noindent +@kindex Z D +@pindex calc-user-define +Any Calculator command may be bound to a key using the @kbd{Z D} +(@code{calc-user-define}) command. Actually, it is bound to a two-key +sequence beginning with the lower-case @kbd{z} prefix. + +The @kbd{Z D} command first prompts for the key to define. For example, +press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then +prompted for the name of the Calculator command that this key should +run. For example, the @code{calc-sincos} command is not normally +available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the +@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain +in effect for the rest of this Emacs session, or until you redefine +@kbd{z s} to be something else. + +You can actually bind any Emacs command to a @kbd{z} key sequence by +backspacing over the @samp{calc-} when you are prompted for the command name. + +As with any other prefix key, you can type @kbd{z ?} to see a list of +all the two-key sequences you have defined that start with @kbd{z}. +Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined. + +User keys are typically letters, but may in fact be any key. +(@key{META}-keys are not permitted, nor are a terminal's special +function keys which generate multi-character sequences when pressed.) +You can define different commands on the shifted and unshifted versions +of a letter if you wish. + +@kindex Z U +@pindex calc-user-undefine +The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key. +For example, the key sequence @kbd{Z U s} will undefine the @code{sincos} +key we defined above. + +@kindex Z P +@pindex calc-user-define-permanent +@cindex Storing user definitions +@cindex Permanent user definitions +@cindex @file{.emacs} file, user-defined commands +The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key +binding permanent so that it will remain in effect even in future Emacs +sessions. (It does this by adding a suitable bit of Lisp code into +your @file{.emacs} file.) For example, @kbd{Z P s} would register +our @code{sincos} command permanently. If you later wish to unregister +this command you must edit your @file{.emacs} file by hand. +(@xref{General Mode Commands}, for a way to tell Calc to use a +different file instead of @file{.emacs}.) + +The @kbd{Z P} command also saves the user definition, if any, for the +command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user +key could invoke a command, which in turn calls an algebraic function, +which might have one or more special display formats. A single @kbd{Z P} +command will save all of these definitions. + +To save a command or function without its key binding (or if there is +no key binding for the command or function), type @kbd{'} (the apostrophe) +when prompted for a key. Then, type the function name, or backspace +to change the @samp{calcFunc-} prefix to @samp{calc-} and enter a +command name. (If the command you give implies a function, the function +will be saved, and if the function has any display formats, those will +be saved, but not the other way around: Saving a function will not save +any commands or key bindings associated with the function.) + +@kindex Z E +@pindex calc-user-define-edit +@cindex Editing user definitions +The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition +of a user key. This works for keys that have been defined by either +keyboard macros or formulas; further details are contained in the relevant +following sections. + +@node Keyboard Macros, Invocation Macros, Creating User Keys, Programming +@section Programming with Keyboard Macros + +@noindent +@kindex X +@cindex Programming with keyboard macros +@cindex Keyboard macros +The easiest way to ``program'' the Emacs Calculator is to use standard +keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From +this point on, keystrokes you type will be saved away as well as +performing their usual functions. Press @kbd{C-x )} to end recording. +Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to +execute your keyboard macro by replaying the recorded keystrokes. +@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further +information.@refill + +When you use @kbd{X} to invoke a keyboard macro, the entire macro is +treated as a single command by the undo and trail features. The stack +display buffer is not updated during macro execution, but is instead +fixed up once the macro completes. Thus, commands defined with keyboard +macros are convenient and efficient. The @kbd{C-x e} command, on the +other hand, invokes the keyboard macro with no special treatment: Each +command in the macro will record its own undo information and trail entry, +and update the stack buffer accordingly. If your macro uses features +outside of Calc's control to operate on the contents of the Calc stack +buffer, or if it includes Undo, Redo, or last-arguments commands, you +must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date +at all times. You could also consider using @kbd{K} (@code{calc-keep-args}) +instead of @kbd{M-@key{RET}} (@code{calc-last-args}). + +Calc extends the standard Emacs keyboard macros in several ways. +Keyboard macros can be used to create user-defined commands. Keyboard +macros can include conditional and iteration structures, somewhat +analogous to those provided by a traditional programmable calculator. + +@menu +* Naming Keyboard Macros:: +* Conditionals in Macros:: +* Loops in Macros:: +* Local Values in Macros:: +* Queries in Macros:: +@end menu + +@node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros +@subsection Naming Keyboard Macros + +@noindent +@kindex Z K +@pindex calc-user-define-kbd-macro +Once you have defined a keyboard macro, you can bind it to a @kbd{z} +key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command. +This command prompts first for a key, then for a command name. For +example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will +define a keyboard macro which negates the top two numbers on the stack +(@key{TAB} swaps the top two stack elements). Now you can type +@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key +sequence. The default command name (if you answer the second prompt with +just the @key{RET} key as in this example) will be something like +@samp{calc-User-n}. The keyboard macro will now be available as both +@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more +descriptive command name if you wish.@refill + +Macros defined by @kbd{Z K} act like single commands; they are executed +in the same way as by the @kbd{X} key. If you wish to define the macro +as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}), +give a negative prefix argument to @kbd{Z K}. + +Once you have bound your keyboard macro to a key, you can use +@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}. + +@cindex Keyboard macros, editing +The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has +been defined by a keyboard macro tries to use the @code{edit-kbd-macro} +command to edit the macro. This command may be found in the +@file{macedit} package, a copy of which comes with Calc. It decomposes +the macro definition into full Emacs command names, like @code{calc-pop} +and @code{calc-add}. Type @kbd{M-# M-#} to finish editing and update +the definition stored on the key, or, to cancel the edit, type +@kbd{M-# x}.@refill + +If you give a negative numeric prefix argument to @kbd{Z E}, the keyboard +macro is edited in spelled-out keystroke form. For example, the editing +buffer might contain the nine characters @w{@samp{1 RET 2 +}}. When you press +@kbd{M-# M-#}, the @code{read-kbd-macro} feature of the @file{macedit} +package is used to reinterpret these key names. The +notations @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL}, and +@code{NUL} must be written in all uppercase, as must the prefixes @code{C-} +and @code{M-}. Spaces and line breaks are ignored. Other characters are +copied verbatim into the keyboard macro. Basically, the notation is the +same as is used in all of this manual's examples, except that the manual +takes some liberties with spaces: When we say @kbd{' [1 2 3] RET}, we take +it for granted that it is clear we really mean @kbd{' [1 SPC 2 SPC 3] RET}, +which is what @code{read-kbd-macro} wants to see.@refill + +If @file{macedit} is not available, @kbd{Z E} edits the keyboard macro +in ``raw'' form; the editing buffer simply contains characters like +@samp{1^M2+} (here @samp{^M} represents the carriage-return character). +Editing in this mode, you will have to use @kbd{C-q} to enter new +control characters into the buffer.@refill + +@kindex M-# m +@pindex read-kbd-macro +The @kbd{M-# m} (@code{read-kbd-macro}) command reads an Emacs ``region'' +of spelled-out keystrokes and defines it as the current keyboard macro. +It is a convenient way to define a keyboard macro that has been stored +in a file, or to define a macro without executing it at the same time. +The @kbd{M-# m} command works only if @file{macedit} is present. + +@node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros +@subsection Conditionals in Keyboard Macros + +@noindent +@kindex Z [ +@kindex Z ] +@pindex calc-kbd-if +@pindex calc-kbd-else +@pindex calc-kbd-else-if +@pindex calc-kbd-end-if +@cindex Conditional structures +The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if}) +commands allow you to put simple tests in a keyboard macro. When Calc +sees the @kbd{Z [}, it pops an object from the stack and, if the object is +a non-zero value, continues executing keystrokes. But if the object is +zero, or if it is not provably nonzero, Calc skips ahead to the matching +@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for +performing tests which conveniently produce 1 for true and 0 for false. + +For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value +function in the form of a keyboard macro. This macro duplicates the +number on the top of the stack, pushes zero and compares using @kbd{a <} +(@code{calc-less-than}), then, if the number was less than zero, +executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign +command is skipped. + +To program this macro, type @kbd{C-x (}, type the above sequence of +keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be +executed while you are making the definition as well as when you later +re-execute the macro by typing @kbd{X}. Thus you should make sure a +suitable number is on the stack before defining the macro so that you +don't get a stack-underflow error during the definition process. + +Conditionals can be nested arbitrarily. However, there should be exactly +one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro. + +@kindex Z : +The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between +two keystroke sequences. The general format is @kbd{@var{cond} Z [ +@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true +(i.e., if the top of stack contains a non-zero number after @var{cond} +has been executed), the @var{then-part} will be executed and the +@var{else-part} will be skipped. Otherwise, the @var{then-part} will +be skipped and the @var{else-part} will be executed. + +@kindex Z | +The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose +between any number of alternatives. For example, +@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z : +@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true, +otherwise it will execute @var{part2} if @var{cond2} is true, otherwise +it will execute @var{part3}. + +More precisely, @kbd{Z [} pops a number and conditionally skips to the +next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when +actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}. +@kbd{Z |} pops a number and conditionally skips to the next matching +@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally +equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |} +does not. + +Calc's conditional and looping constructs work by scanning the +keyboard macro for occurrences of character sequences like @samp{Z:} +and @samp{Z]}. One side-effect of this is that if you use these +constructs you must be careful that these character pairs do not +occur by accident in other parts of the macros. Since Calc rarely +uses shift-@kbd{Z} for any purpose except as a prefix character, this +is not likely to be a problem. Another side-effect is that it will +not work to define your own custom key bindings for these commands. +Only the standard shift-@kbd{Z} bindings will work correctly. + +@kindex Z C-g +If Calc gets stuck while skipping characters during the definition of a +macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g} +actually adds a @kbd{C-g} keystroke to the macro.) + +@node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros +@subsection Loops in Keyboard Macros + +@noindent +@kindex Z < +@kindex Z > +@pindex calc-kbd-repeat +@pindex calc-kbd-end-repeat +@cindex Looping structures +@cindex Iterative structures +The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >} +(@code{calc-kbd-end-repeat}) commands pop a number from the stack, +which must be an integer, then repeat the keystrokes between the brackets +the specified number of times. If the integer is zero or negative, the +body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >} +computes two to a nonnegative integer power. First, we push 1 on the +stack and then swap the integer argument back to the top. The @kbd{Z <} +pops that argument leaving the 1 back on top of the stack. Then, we +repeat a multiply-by-two step however many times.@refill + +Once again, the keyboard macro is executed as it is being entered. +In this case it is especially important to set up reasonable initial +conditions before making the definition: Suppose the integer 1000 just +happened to be sitting on the stack before we typed the above definition! +Another approach is to enter a harmless dummy definition for the macro, +then go back and edit in the real one with a @kbd{Z E} command. Yet +another approach is to type the macro as written-out keystroke names +in a buffer, then use @kbd{M-# m} (@code{read-kbd-macro}) to read the +macro. + +@kindex Z / +@pindex calc-break +The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out +of a keyboard macro loop prematurely. It pops an object from the stack; +if that object is true (a non-zero number), control jumps out of the +innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues +after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no +effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;} +in the C language.@refill + +@kindex Z ( +@kindex Z ) +@pindex calc-kbd-for +@pindex calc-kbd-end-for +The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for}) +commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the +value of the counter available inside the loop. The general layout is +@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (} +command pops initial and final values from the stack. It then creates +a temporary internal counter and initializes it with the value @var{init}. +The @kbd{Z (} command then repeatedly pushes the counter value onto the +stack and executes @var{body} and @var{step}, adding @var{step} to the +counter each time until the loop finishes.@refill + +@cindex Summations (by keyboard macros) +By default, the loop finishes when the counter becomes greater than (or +less than) @var{final}, assuming @var{initial} is less than (greater +than) @var{final}. If @var{initial} is equal to @var{final}, the body +executes exactly once. The body of the loop always executes at least +once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the +squares of the integers from 1 to 10, in steps of 1. + +If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is +forced to use upward-counting conventions. In this case, if @var{initial} +is greater than @var{final} the body will not be executed at all. +Note that @var{step} may still be negative in this loop; the prefix +argument merely constrains the loop-finished test. Likewise, a prefix +argument of @i{-1} forces downward-counting conventions. + +@kindex Z @{ +@kindex Z @} +@pindex calc-kbd-loop +@pindex calc-kbd-end-loop +The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}} +(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and +@kbd{Z >}, except that they do not pop a count from the stack---they +effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}} +loop ought to include at least one @kbd{Z /} to make sure the loop +doesn't run forever. (If any error message occurs which causes Emacs +to beep, the keyboard macro will also be halted; this is a standard +feature of Emacs. You can also generally press @kbd{C-g} to halt a +running keyboard macro, although not all versions of Unix support +this feature.) + +The conditional and looping constructs are not actually tied to +keyboard macros, but they are most often used in that context. +For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push +ten copies of 23 onto the stack. This can be typed ``live'' just +as easily as in a macro definition. + +@xref{Conditionals in Macros}, for some additional notes about +conditional and looping commands. + +@node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros +@subsection Local Values in Macros + +@noindent +@cindex Local variables +@cindex Restoring saved modes +Keyboard macros sometimes want to operate under known conditions +without affecting surrounding conditions. For example, a keyboard +macro may wish to turn on Fraction Mode, or set a particular +precision, independent of the user's normal setting for those +modes. + +@kindex Z ` +@kindex Z ' +@pindex calc-kbd-push +@pindex calc-kbd-pop +Macros also sometimes need to use local variables. Assignments to +local variables inside the macro should not affect any variables +outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '} +(@code{calc-kbd-pop}) commands give you both of these capabilities. + +When you type @kbd{Z `} (with a backquote or accent grave character), +the values of various mode settings are saved away. The ten ``quick'' +variables @code{q0} through @code{q9} are also saved. When +you type @w{@kbd{Z '}} (with an apostrophe), these values are restored. +Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested. + +If a keyboard macro halts due to an error in between a @kbd{Z `} and +a @kbd{Z '}, the saved values will be restored correctly even though +the macro never reaches the @kbd{Z '} command. Thus you can use +@kbd{Z `} and @kbd{Z '} without having to worry about what happens +in exceptional conditions. + +If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts +you into a ``recursive edit.'' You can tell you are in a recursive +edit because there will be extra square brackets in the mode line, +as in @samp{[(Calculator)]}. These brackets will go away when you +type the matching @kbd{Z '} command. The modes and quick variables +will be saved and restored in just the same way as if actual keyboard +macros were involved. + +The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision +and binary word size, the angular mode (Deg, Rad, or HMS), the +simplification mode, Algebraic mode, Symbolic mode, Infinite mode, +Matrix or Scalar mode, Fraction mode, and the current complex mode +(Polar or Rectangular). The ten ``quick'' variables' values (or lack +thereof) are also saved. + +Most mode-setting commands act as toggles, but with a numeric prefix +they force the mode either on (positive prefix) or off (negative +or zero prefix). Since you don't know what the environment might +be when you invoke your macro, it's best to use prefix arguments +for all mode-setting commands inside the macro. + +In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes +listed above to their default values. As usual, the matching @kbd{Z '} +will restore the modes to their settings from before the @kbd{C-u Z `}. +Also, @w{@kbd{Z `}} with a negative prefix argument resets algebraic mode +to its default (off) but leaves the other modes the same as they were +outside the construct. + +The contents of the stack and trail, values of non-quick variables, and +other settings such as the language mode and the various display modes, +are @emph{not} affected by @kbd{Z `} and @kbd{Z '}. + +@node Queries in Macros, , Local Values in Macros, Keyboard Macros +@subsection Queries in Keyboard Macros + +@noindent +@kindex Z = +@pindex calc-kbd-report +The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative +message including the value on the top of the stack. You are prompted +to enter a string. That string, along with the top-of-stack value, +is displayed unless @kbd{m w} (@code{calc-working}) has been used +to turn such messages off. + +@kindex Z # +@pindex calc-kbd-query +The @kbd{Z #} (@code{calc-kbd-query}) command displays a prompt message +(which you enter during macro definition), then does an algebraic entry +which takes its input from the keyboard, even during macro execution. +This command allows your keyboard macros to accept numbers or formulas +as interactive input. All the normal conventions of algebraic input, +including the use of @kbd{$} characters, are supported. + +@xref{Kbd Macro Query, , , emacs, the Emacs Manual}, for a description of +@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept +keyboard input during a keyboard macro. In particular, you can use +@kbd{C-x q} to enter a recursive edit, which allows the user to perform +any Calculator operations interactively before pressing @kbd{C-M-c} to +return control to the keyboard macro. + +@node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming +@section Invocation Macros + +@kindex M-# z +@kindex Z I +@pindex calc-user-invocation +@pindex calc-user-define-invocation +Calc provides one special keyboard macro, called up by @kbd{M-# z} +(@code{calc-user-invocation}), that is intended to allow you to define +your own special way of starting Calc. To define this ``invocation +macro,'' create the macro in the usual way with @kbd{C-x (} and +@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}). +There is only one invocation macro, so you don't need to type any +additional letters after @kbd{Z I}. From now on, you can type +@kbd{M-# z} at any time to execute your invocation macro. + +For example, suppose you find yourself often grabbing rectangles of +numbers into Calc and multiplying their columns. You can do this +by typing @kbd{M-# r} to grab, and @kbd{V R : *} to multiply columns. +To make this into an invocation macro, just type @kbd{C-x ( M-# r +V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data, +just mark the data in its buffer in the usual way and type @kbd{M-# z}. + +Invocation macros are treated like regular Emacs keyboard macros; +all the special features described above for @kbd{Z K}-style macros +do not apply. @kbd{M-# z} is just like @kbd{C-x e}, except that it +uses the macro that was last stored by @kbd{Z I}. (In fact, the +macro does not even have to have anything to do with Calc!) + +The @kbd{m m} command saves the last invocation macro defined by +@kbd{Z I} along with all the other Calc mode settings. +@xref{General Mode Commands}. + +@node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming +@section Programming with Formulas + +@noindent +@kindex Z F +@pindex calc-user-define-formula +@cindex Programming with algebraic formulas +Another way to create a new Calculator command uses algebraic formulas. +The @kbd{Z F} (@code{calc-user-define-formula}) command stores the +formula at the top of the stack as the definition for a key. This +command prompts for five things: The key, the command name, the function +name, the argument list, and the behavior of the command when given +non-numeric arguments. + +For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula +@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this +formula on the @kbd{z m} key sequence. The next prompt is for a command +name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form +for the new command. If you simply press @key{RET}, a default name like +@code{calc-User-m} will be constructed. In our example, suppose we enter +@kbd{spam @key{RET}} to define the new command as @code{calc-spam}. + +If you want to give the formula a long-style name only, you can press +@key{SPC} or @key{RET} when asked which single key to use. For example +@kbd{Z F @key{RET} spam @key{RET}} defines the new command as +@kbd{M-x calc-spam}, with no keyboard equivalent. + +The third prompt is for a function name. The default is to use the same +name as the command name but with @samp{calcFunc-} in place of +@samp{calc-}. This is the name you will use if you want to enter your +new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}. +Then the new function can be invoked by pushing two numbers on the +stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic +formula @samp{yow(x,y)}.@refill + +The fourth prompt is for the function's argument list. This is used to +associate values on the stack with the variables that appear in the formula. +The default is a list of all variables which appear in the formula, sorted +into alphabetical order. In our case, the default would be @samp{(a b)}. +This means that, when the user types @kbd{z m}, the Calculator will remove +two numbers from the stack, substitute these numbers for @samp{a} and +@samp{b} (respectively) in the formula, then simplify the formula and +push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m} +would replace the 10 and 100 on the stack with the number 210, which is +@cite{a + 2 b} with @cite{a=10} and @cite{b=100}. Likewise, the formula +@samp{yow(10, 100)} will be evaluated by substituting @cite{a=10} and +@cite{b=100} in the definition. + +You can rearrange the order of the names before pressing @key{RET} to +control which stack positions go to which variables in the formula. If +you remove a variable from the argument list, that variable will be left +in symbolic form by the command. Thus using an argument list of @samp{(b)} +for our function would cause @kbd{10 z m} to replace the 10 on the stack +with the formula @samp{a + 20}. If we had used an argument list of +@samp{(b a)}, the result with inputs 10 and 100 would have been 120. + +You can also put a nameless function on the stack instead of just a +formula, as in @samp{<a, b : a + 2 b>}. @xref{Specifying Operators}. +In this example, the command will be defined by the formula @samp{a + 2 b} +using the argument list @samp{(a b)}. + +The final prompt is a y-or-n question concerning what to do if symbolic +arguments are given to your function. If you answer @kbd{y}, then +executing @kbd{z m} (using the original argument list @samp{(a b)}) with +arguments @cite{10} and @cite{x} will leave the function in symbolic +form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n}, +then the formula will always be expanded, even for non-constant +arguments: @samp{10 + 2 x}. If you never plan to feed algebraic +formulas to your new function, it doesn't matter how you answer this +question.@refill + +If you answered @kbd{y} to this question you can still cause a function +call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}). +Also, Calc will expand the function if necessary when you take a +derivative or integral or solve an equation involving the function. + +@kindex Z G +@pindex calc-get-user-defn +Once you have defined a formula on a key, you can retrieve this formula +with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a +key, and this command pushes the formula that was used to define that +key onto the stack. Actually, it pushes a nameless function that +specifies both the argument list and the defining formula. You will get +an error message if the key is undefined, or if the key was not defined +by a @kbd{Z F} command.@refill + +The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has +been defined by a formula uses a variant of the @code{calc-edit} command +to edit the defining formula. Press @kbd{M-# M-#} to finish editing and +store the new formula back in the definition, or @kbd{M-# x} to +cancel the edit. (The argument list and other properties of the +definition are unchanged; to adjust the argument list, you can use +@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and +then re-execute the @kbd{Z F} command.) + +As usual, the @kbd{Z P} command records your definition permanently. +In this case it will permanently record all three of the relevant +definitions: the key, the command, and the function. + +You may find it useful to turn off the default simplifications with +@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be +used as a function definition. For example, the formula @samp{deriv(a^2,v)} +which might be used to define a new function @samp{dsqr(a,v)} will be +``simplified'' to 0 immediately upon entry since @code{deriv} considers +@cite{a} to be constant with respect to @cite{v}. Turning off +default simplifications cures this problem: The definition will be stored +in symbolic form without ever activating the @code{deriv} function. Press +@kbd{m D} to turn the default simplifications back on afterwards. + +@node Lisp Definitions, , Algebraic Definitions, Programming +@section Programming with Lisp + +@noindent +The Calculator can be programmed quite extensively in Lisp. All you +do is write a normal Lisp function definition, but with @code{defmath} +in place of @code{defun}. This has the same form as @code{defun}, but it +automagically replaces calls to standard Lisp functions like @code{+} and +@code{zerop} with calls to the corresponding functions in Calc's own library. +Thus you can write natural-looking Lisp code which operates on all of the +standard Calculator data types. You can then use @kbd{Z D} if you wish to +bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command +will not edit a Lisp-based definition. + +Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section +assumes a familiarity with Lisp programming concepts; if you do not know +Lisp, you may find keyboard macros or rewrite rules to be an easier way +to program the Calculator. + +This section first discusses ways to write commands, functions, or +small programs to be executed inside of Calc. Then it discusses how +your own separate programs are able to call Calc from the outside. +Finally, there is a list of internal Calc functions and data structures +for the true Lisp enthusiast. + +@menu +* Defining Functions:: +* Defining Simple Commands:: +* Defining Stack Commands:: +* Argument Qualifiers:: +* Example Definitions:: + +* Calling Calc from Your Programs:: +* Internals:: +@end menu + +@node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions +@subsection Defining New Functions + +@noindent +@findex defmath +The @code{defmath} function (actually a Lisp macro) is like @code{defun} +except that code in the body of the definition can make use of the full +range of Calculator data types. The prefix @samp{calcFunc-} is added +to the specified name to get the actual Lisp function name. As a simple +example, + +@example +(defmath myfact (n) + (if (> n 0) + (* n (myfact (1- n))) + 1)) +@end example + +@noindent +This actually expands to the code, + +@example +(defun calcFunc-myfact (n) + (if (math-posp n) + (math-mul n (calcFunc-myfact (math-add n -1))) + 1)) +@end example + +@noindent +This function can be used in algebraic expressions, e.g., @samp{myfact(5)}. + +The @samp{myfact} function as it is defined above has the bug that an +expression @samp{myfact(a+b)} will be simplified to 1 because the +formula @samp{a+b} is not considered to be @code{posp}. A robust +factorial function would be written along the following lines: + +@smallexample +(defmath myfact (n) + (if (> n 0) + (* n (myfact (1- n))) + (if (= n 0) + 1 + nil))) ; this could be simplified as: (and (= n 0) 1) +@end smallexample + +If a function returns @code{nil}, it is left unsimplified by the Calculator +(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)} +will be simplified to @samp{myfact(a+3)} but no further. Beware that every +time the Calculator reexamines this formula it will attempt to resimplify +it, so your function ought to detect the returning-@code{nil} case as +efficiently as possible. + +The following standard Lisp functions are treated by @code{defmath}: +@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or +@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=}, +@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor}, +@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for +@code{math-nearly-equal}, which is useful in implementing Taylor series.@refill + +For other functions @var{func}, if a function by the name +@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the +name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself +is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is +used on the assumption that this is a to-be-defined math function. Also, if +the function name is quoted as in @samp{('integerp a)} the function name is +always used exactly as written (but not quoted).@refill + +Variable names have @samp{var-} prepended to them unless they appear in +the function's argument list or in an enclosing @code{let}, @code{let*}, +@code{for}, or @code{foreach} form, +or their names already contain a @samp{-} character. Thus a reference to +@samp{foo} is the same as a reference to @samp{var-foo}.@refill + +A few other Lisp extensions are available in @code{defmath} definitions: + +@itemize @bullet +@item +The @code{elt} function accepts any number of index variables. +Note that Calc vectors are stored as Lisp lists whose first +element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields +the second element of vector @code{v}, and @samp{(elt m i j)} +yields one element of a Calc matrix. + +@item +The @code{setq} function has been extended to act like the Common +Lisp @code{setf} function. (The name @code{setf} is recognized as +a synonym of @code{setq}.) Specifically, the first argument of +@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form, +in which case the effect is to store into the specified +element of a list. Thus, @samp{(setq (elt m i j) x)} stores @cite{x} +into one element of a matrix. + +@item +A @code{for} looping construct is available. For example, +@samp{(for ((i 0 10)) body)} executes @code{body} once for each +binding of @cite{i} from zero to 10. This is like a @code{let} +form in that @cite{i} is temporarily bound to the loop count +without disturbing its value outside the @code{for} construct. +Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)}, +are also available. For each value of @cite{i} from zero to 10, +@cite{j} counts from 0 to @cite{i-1} in steps of two. Note that +@code{for} has the same general outline as @code{let*}, except +that each element of the header is a list of three or four +things, not just two. + +@item +The @code{foreach} construct loops over elements of a list. +For example, @samp{(foreach ((x (cdr v))) body)} executes +@code{body} with @cite{x} bound to each element of Calc vector +@cite{v} in turn. The purpose of @code{cdr} here is to skip over +the initial @code{vec} symbol in the vector. + +@item +The @code{break} function breaks out of the innermost enclosing +@code{while}, @code{for}, or @code{foreach} loop. If given a +value, as in @samp{(break x)}, this value is returned by the +loop. (Lisp loops otherwise always return @code{nil}.) + +@item +The @code{return} function prematurely returns from the enclosing +function. For example, @samp{(return (+ x y))} returns @cite{x+y} +as the value of a function. You can use @code{return} anywhere +inside the body of the function. +@end itemize + +Non-integer numbers (and extremely large integers) cannot be included +directly into a @code{defmath} definition. This is because the Lisp +reader will fail to parse them long before @code{defmath} ever gets control. +Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic +formula can go between the quotes. For example, + +@smallexample +(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5) + (and (numberp x) + (exp :"x * 0.5"))) +@end smallexample + +expands to + +@smallexample +(defun calcFunc-sqexp (x) + (and (math-numberp x) + (calcFunc-exp (math-mul x '(float 5 -1))))) +@end smallexample + +Note the use of @code{numberp} as a guard to ensure that the argument is +a number first, returning @code{nil} if not. The exponential function +could itself have been included in the expression, if we had preferred: +@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion +step of @code{myfact} could have been written + +@example +:"n * myfact(n-1)" +@end example + +If a file named @file{.emacs} exists in your home directory, Emacs reads +and executes the Lisp forms in this file as it starts up. While it may +seem like a good idea to put your favorite @code{defmath} commands here, +this has the unfortunate side-effect that parts of the Calculator must be +loaded in to process the @code{defmath} commands whether or not you will +actually use the Calculator! A better effect can be had by writing + +@example +(put 'calc-define 'thing '(progn + (defmath ... ) + (defmath ... ) +)) +@end example + +@noindent +@vindex calc-define +The @code{put} function adds a @dfn{property} to a symbol. Each Lisp +symbol has a list of properties associated with it. Here we add a +property with a name of @code{thing} and a @samp{(progn ...)} form as +its value. When Calc starts up, and at the start of every Calc command, +the property list for the symbol @code{calc-define} is checked and the +values of any properties found are evaluated as Lisp forms. The +properties are removed as they are evaluated. The property names +(like @code{thing}) are not used; you should choose something like the +name of your project so as not to conflict with other properties. + +The net effect is that you can put the above code in your @file{.emacs} +file and it will not be executed until Calc is loaded. Or, you can put +that same code in another file which you load by hand either before or +after Calc itself is loaded. + +The properties of @code{calc-define} are evaluated in the same order +that they were added. They can assume that the Calc modules @file{calc.el}, +@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and +that the @samp{*Calculator*} buffer will be the current buffer. + +If your @code{calc-define} property only defines algebraic functions, +you can be sure that it will have been evaluated before Calc tries to +call your function, even if the file defining the property is loaded +after Calc is loaded. But if the property defines commands or key +sequences, it may not be evaluated soon enough. (Suppose it defines the +new command @code{tweak-calc}; the user can load your file, then type +@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To +protect against this situation, you can put + +@example +(run-hooks 'calc-check-defines) +@end example + +@findex calc-check-defines +@noindent +at the end of your file. The @code{calc-check-defines} function is what +looks for and evaluates properties on @code{calc-define}; @code{run-hooks} +has the advantage that it is quietly ignored if @code{calc-check-defines} +is not yet defined because Calc has not yet been loaded. + +Examples of things that ought to be enclosed in a @code{calc-define} +property are @code{defmath} calls, @code{define-key} calls that modify +the Calc key map, and any calls that redefine things defined inside Calc. +Ordinary @code{defun}s need not be enclosed with @code{calc-define}. + +@node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions +@subsection Defining New Simple Commands + +@noindent +@findex interactive +If a @code{defmath} form contains an @code{interactive} clause, it defines +a Calculator command. Actually such a @code{defmath} results in @emph{two} +function definitions: One, a @samp{calcFunc-} function as was just described, +with the @code{interactive} clause removed. Two, a @samp{calc-} function +with a suitable @code{interactive} clause and some sort of wrapper to make +the command work in the Calc environment. + +In the simple case, the @code{interactive} clause has the same form as +for normal Emacs Lisp commands: + +@smallexample +(defmath increase-precision (delta) + "Increase precision by DELTA." ; This is the "documentation string" + (interactive "p") ; Register this as a M-x-able command + (setq calc-internal-prec (+ calc-internal-prec delta))) +@end smallexample + +This expands to the pair of definitions, + +@smallexample +(defun calc-increase-precision (delta) + "Increase precision by DELTA." + (interactive "p") + (calc-wrapper + (setq calc-internal-prec (math-add calc-internal-prec delta)))) + +(defun calcFunc-increase-precision (delta) + "Increase precision by DELTA." + (setq calc-internal-prec (math-add calc-internal-prec delta))) +@end smallexample + +@noindent +where in this case the latter function would never really be used! Note +that since the Calculator stores small integers as plain Lisp integers, +the @code{math-add} function will work just as well as the native +@code{+} even when the intent is to operate on native Lisp integers. + +@findex calc-wrapper +The @samp{calc-wrapper} call invokes a macro which surrounds the body of +the function with code that looks roughly like this: + +@smallexample +(let ((calc-command-flags nil)) + (unwind-protect + (save-excursion + (calc-select-buffer) + @emph{body of function} + @emph{renumber stack} + @emph{clear} Working @emph{message}) + @emph{realign cursor and window} + @emph{clear Inverse, Hyperbolic, and Keep Args flags} + @emph{update Emacs mode line})) +@end smallexample + +@findex calc-select-buffer +The @code{calc-select-buffer} function selects the @samp{*Calculator*} +buffer if necessary, say, because the command was invoked from inside +the @samp{*Calc Trail*} window. + +@findex calc-set-command-flag +You can call, for example, @code{(calc-set-command-flag 'no-align)} to set +the above-mentioned command flags. The following command flags are +recognized by Calc routines: + +@table @code +@item renum-stack +Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered +after this command completes. This is set by routines like +@code{calc-push}. + +@item clear-message +Calc should call @samp{(message "")} if this command completes normally +(to clear a ``Working@dots{}'' message out of the echo area). + +@item no-align +Do not move the cursor back to the @samp{.} top-of-stack marker. + +@item position-point +Use the variables @code{calc-position-point-line} and +@code{calc-position-point-column} to position the cursor after +this command finishes. + +@item keep-flags +Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag}, +and @code{calc-keep-args-flag} at the end of this command. + +@item do-edit +Switch to buffer @samp{*Calc Edit*} after this command. + +@item hold-trail +Do not move trail pointer to end of trail when something is recorded +there. +@end table + +@kindex Y +@kindex Y ? +@vindex calc-Y-help-msgs +Calc reserves a special prefix key, shift-@kbd{Y}, for user-written +extensions to Calc. There are no built-in commands that work with +this prefix key; you must call @code{define-key} from Lisp (probably +from inside a @code{calc-define} property) to add to it. Initially only +@kbd{Y ?} is defined; it takes help messages from a list of strings +(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All +other undefined keys except for @kbd{Y} are reserved for use by +future versions of Calc. + +If you are writing a Calc enhancement which you expect to give to +others, it is best to minimize the number of @kbd{Y}-key sequences +you use. In fact, if you have more than one key sequence you should +consider defining three-key sequences with a @kbd{Y}, then a key that +stands for your package, then a third key for the particular command +within your package. + +Users may wish to install several Calc enhancements, and it is possible +that several enhancements will choose to use the same key. In the +example below, a variable @code{inc-prec-base-key} has been defined +to contain the key that identifies the @code{inc-prec} package. Its +value is initially @code{"P"}, but a user can change this variable +if necessary without having to modify the file. + +Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I} +command that increases the precision, and a @kbd{Y P D} command that +decreases the precision. + +@smallexample +;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91. +;;; (Include copyright or copyleft stuff here.) + +(defvar inc-prec-base-key "P" + "Base key for inc-prec.el commands.") + +(put 'calc-define 'inc-prec '(progn + +(define-key calc-mode-map (format "Y%sI" inc-prec-base-key) + 'increase-precision) +(define-key calc-mode-map (format "Y%sD" inc-prec-base-key) + 'decrease-precision) + +(setq calc-Y-help-msgs + (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key) + calc-Y-help-msgs)) + +(defmath increase-precision (delta) + "Increase precision by DELTA." + (interactive "p") + (setq calc-internal-prec (+ calc-internal-prec delta))) + +(defmath decrease-precision (delta) + "Decrease precision by DELTA." + (interactive "p") + (setq calc-internal-prec (- calc-internal-prec delta))) + +)) ; end of calc-define property + +(run-hooks 'calc-check-defines) +@end smallexample + +@node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions +@subsection Defining New Stack-Based Commands + +@noindent +To define a new computational command which takes and/or leaves arguments +on the stack, a special form of @code{interactive} clause is used. + +@example +(interactive @var{num} @var{tag}) +@end example + +@noindent +where @var{num} is an integer, and @var{tag} is a string. The effect is +to pop @var{num} values off the stack, resimplify them by calling +@code{calc-normalize}, and hand them to your function according to the +function's argument list. Your function may include @code{&optional} and +@code{&rest} parameters, so long as calling the function with @var{num} +parameters is legal. + +Your function must return either a number or a formula in a form +acceptable to Calc, or a list of such numbers or formulas. These value(s) +are pushed onto the stack when the function completes. They are also +recorded in the Calc Trail buffer on a line beginning with @var{tag}, +a string of (normally) four characters or less. If you omit @var{tag} +or use @code{nil} as a tag, the result is not recorded in the trail. + +As an example, the definition + +@smallexample +(defmath myfact (n) + "Compute the factorial of the integer at the top of the stack." + (interactive 1 "fact") + (if (> n 0) + (* n (myfact (1- n))) + (and (= n 0) 1))) +@end smallexample + +@noindent +is a version of the factorial function shown previously which can be used +as a command as well as an algebraic function. It expands to + +@smallexample +(defun calc-myfact () + "Compute the factorial of the integer at the top of the stack." + (interactive) + (calc-slow-wrapper + (calc-enter-result 1 "fact" + (cons 'calcFunc-myfact (calc-top-list-n 1))))) + +(defun calcFunc-myfact (n) + "Compute the factorial of the integer at the top of the stack." + (if (math-posp n) + (math-mul n (calcFunc-myfact (math-add n -1))) + (and (math-zerop n) 1))) +@end smallexample + +@findex calc-slow-wrapper +The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper} +that automatically puts up a @samp{Working...} message before the +computation begins. (This message can be turned off by the user +with an @kbd{m w} (@code{calc-working}) command.) + +@findex calc-top-list-n +The @code{calc-top-list-n} function returns a list of the specified number +of values from the top of the stack. It resimplifies each value by +calling @code{calc-normalize}. If its argument is zero it returns an +empty list. It does not actually remove these values from the stack. + +@findex calc-enter-result +The @code{calc-enter-result} function takes an integer @var{num} and string +@var{tag} as described above, plus a third argument which is either a +Calculator data object or a list of such objects. These objects are +resimplified and pushed onto the stack after popping the specified number +of values from the stack. If @var{tag} is non-@code{nil}, the values +being pushed are also recorded in the trail. + +Note that if @code{calcFunc-myfact} returns @code{nil} this represents +``leave the function in symbolic form.'' To return an actual empty list, +in the sense that @code{calc-enter-result} will push zero elements back +onto the stack, you should return the special value @samp{'(nil)}, a list +containing the single symbol @code{nil}. + +The @code{interactive} declaration can actually contain a limited +Emacs-style code string as well which comes just before @var{num} and +@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in + +@example +(defmath foo (a b &optional c) + (interactive "p" 2 "foo") + @var{body}) +@end example + +In this example, the command @code{calc-foo} will evaluate the expression +@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if +executed with a numeric prefix argument of @cite{n}. + +The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"} +code as used with @code{defun}). It uses the numeric prefix argument as the +number of objects to remove from the stack and pass to the function. +In this case, the integer @var{num} serves as a default number of +arguments to be used when no prefix is supplied. + +@node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions +@subsection Argument Qualifiers + +@noindent +Anywhere a parameter name can appear in the parameter list you can also use +an @dfn{argument qualifier}. Thus the general form of a definition is: + +@example +(defmath @var{name} (@var{param} @var{param...} + &optional @var{param} @var{param...} + &rest @var{param}) + @var{body}) +@end example + +@noindent +where each @var{param} is either a symbol or a list of the form + +@example +(@var{qual} @var{param}) +@end example + +The following qualifiers are recognized: + +@table @samp +@item complete +@findex complete +The argument must not be an incomplete vector, interval, or complex number. +(This is rarely needed since the Calculator itself will never call your +function with an incomplete argument. But there is nothing stopping your +own Lisp code from calling your function with an incomplete argument.)@refill + +@item integer +@findex integer +The argument must be an integer. If it is an integer-valued float +it will be accepted but converted to integer form. Non-integers and +formulas are rejected. + +@item natnum +@findex natnum +Like @samp{integer}, but the argument must be non-negative. + +@item fixnum +@findex fixnum +Like @samp{integer}, but the argument must fit into a native Lisp integer, +which on most systems means less than 2^23 in absolute value. The +argument is converted into Lisp-integer form if necessary. + +@item float +@findex float +The argument is converted to floating-point format if it is a number or +vector. If it is a formula it is left alone. (The argument is never +actually rejected by this qualifier.) + +@item @var{pred} +The argument must satisfy predicate @var{pred}, which is one of the +standard Calculator predicates. @xref{Predicates}. + +@item not-@var{pred} +The argument must @emph{not} satisfy predicate @var{pred}. +@end table + +For example, + +@example +(defmath foo (a (constp (not-matrixp b)) &optional (float c) + &rest (integer d)) + @var{body}) +@end example + +@noindent +expands to + +@example +(defun calcFunc-foo (a b &optional c &rest d) + (and (math-matrixp b) + (math-reject-arg b 'not-matrixp)) + (or (math-constp b) + (math-reject-arg b 'constp)) + (and c (setq c (math-check-float c))) + (setq d (mapcar 'math-check-integer d)) + @var{body}) +@end example + +@noindent +which performs the necessary checks and conversions before executing the +body of the function. + +@node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions +@subsection Example Definitions + +@noindent +This section includes some Lisp programming examples on a larger scale. +These programs make use of some of the Calculator's internal functions; +@pxref{Internals}. + +@menu +* Bit Counting Example:: +* Sine Example:: +@end menu + +@node Bit Counting Example, Sine Example, Example Definitions, Example Definitions +@subsubsection Bit-Counting + +@noindent +@c @starindex +@tindex bcount +Calc does not include a built-in function for counting the number of +``one'' bits in a binary integer. It's easy to invent one using @kbd{b u} +to convert the integer to a set, and @kbd{V #} to count the elements of +that set; let's write a function that counts the bits without having to +create an intermediate set. + +@smallexample +(defmath bcount ((natnum n)) + (interactive 1 "bcnt") + (let ((count 0)) + (while (> n 0) + (if (oddp n) + (setq count (1+ count))) + (setq n (lsh n -1))) + count)) +@end smallexample + +@noindent +When this is expanded by @code{defmath}, it will become the following +Emacs Lisp function: + +@smallexample +(defun calcFunc-bcount (n) + (setq n (math-check-natnum n)) + (let ((count 0)) + (while (math-posp n) + (if (math-oddp n) + (setq count (math-add count 1))) + (setq n (calcFunc-lsh n -1))) + count)) +@end smallexample + +If the input numbers are large, this function involves a fair amount +of arithmetic. A binary right shift is essentially a division by two; +recall that Calc stores integers in decimal form so bit shifts must +involve actual division. + +To gain a bit more efficiency, we could divide the integer into +@i{n}-bit chunks, each of which can be handled quickly because +they fit into Lisp integers. It turns out that Calc's arithmetic +routines are especially fast when dividing by an integer less than +1000, so we can set @i{n = 9} bits and use repeated division by 512: + +@smallexample +(defmath bcount ((natnum n)) + (interactive 1 "bcnt") + (let ((count 0)) + (while (not (fixnump n)) + (let ((qr (idivmod n 512))) + (setq count (+ count (bcount-fixnum (cdr qr))) + n (car qr)))) + (+ count (bcount-fixnum n)))) + +(defun bcount-fixnum (n) + (let ((count 0)) + (while (> n 0) + (setq count (+ count (logand n 1)) + n (lsh n -1))) + count)) +@end smallexample + +@noindent +Note that the second function uses @code{defun}, not @code{defmath}. +Because this function deals only with native Lisp integers (``fixnums''), +it can use the actual Emacs @code{+} and related functions rather +than the slower but more general Calc equivalents which @code{defmath} +uses. + +The @code{idivmod} function does an integer division, returning both +the quotient and the remainder at once. Again, note that while it +might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are +more efficient ways to split off the bottom nine bits of @code{n}, +actually they are less efficient because each operation is really +a division by 512 in disguise; @code{idivmod} allows us to do the +same thing with a single division by 512. + +@node Sine Example, , Bit Counting Example, Example Definitions +@subsubsection The Sine Function + +@noindent +@c @starindex +@tindex mysin +A somewhat limited sine function could be defined as follows, using the +well-known Taylor series expansion for @c{$\sin x$} +@samp{sin(x)}: + +@smallexample +(defmath mysin ((float (anglep x))) + (interactive 1 "mysn") + (setq x (to-radians x)) ; Convert from current angular mode. + (let ((sum x) ; Initial term of Taylor expansion of sin. + newsum + (nfact 1) ; "nfact" equals "n" factorial at all times. + (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2. + (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution. + (working "mysin" sum) ; Display "Working" message, if enabled. + (setq nfact (* nfact (1- n) n) + x (* x xnegsqr) + newsum (+ sum (/ x nfact))) + (if (~= newsum sum) ; If newsum is "nearly equal to" sum, + (break)) ; then we are done. + (setq sum newsum)) + sum)) +@end smallexample + +The actual @code{sin} function in Calc works by first reducing the problem +to a sine or cosine of a nonnegative number less than @c{$\pi \over 4$} +@cite{pi/4}. This +ensures that the Taylor series will converge quickly. Also, the calculation +is carried out with two extra digits of precision to guard against cumulative +round-off in @samp{sum}. Finally, complex arguments are allowed and handled +by a separate algorithm. + +@smallexample +(defmath mysin ((float (scalarp x))) + (interactive 1 "mysn") + (setq x (to-radians x)) ; Convert from current angular mode. + (with-extra-prec 2 ; Evaluate with extra precision. + (cond ((complexp x) + (mysin-complex x)) + ((< x 0) + (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0. + (t (mysin-raw x)))))) + +(defmath mysin-raw (x) + (cond ((>= x 7) + (mysin-raw (% x (two-pi)))) ; Now x < 7. + ((> x (pi-over-2)) + (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2. + ((> x (pi-over-4)) + (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4. + ((< x (- (pi-over-4))) + (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4, + (t (mysin-series x)))) ; so the series will be efficient. +@end smallexample + +@noindent +where @code{mysin-complex} is an appropriate function to handle complex +numbers, @code{mysin-series} is the routine to compute the sine Taylor +series as before, and @code{mycos-raw} is a function analogous to +@code{mysin-raw} for cosines. + +The strategy is to ensure that @cite{x} is nonnegative before calling +@code{mysin-raw}. This function then recursively reduces its argument +to a suitable range, namely, plus-or-minus @c{$\pi \over 4$} +@cite{pi/4}. Note that each +test, and particularly the first comparison against 7, is designed so +that small roundoff errors cannnot produce an infinite loop. (Suppose +we compared with @samp{(two-pi)} instead; if due to roundoff problems +the modulo operator ever returned @samp{(two-pi)} exactly, an infinite +recursion could result!) We use modulo only for arguments that will +clearly get reduced, knowing that the next rule will catch any reductions +that this rule misses. + +If a program is being written for general use, it is important to code +it carefully as shown in this second example. For quick-and-dirty programs, +when you know that your own use of the sine function will never encounter +a large argument, a simpler program like the first one shown is fine. + +@node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions +@subsection Calling Calc from Your Lisp Programs + +@noindent +A later section (@pxref{Internals}) gives a full description of +Calc's internal Lisp functions. It's not hard to call Calc from +inside your programs, but the number of these functions can be daunting. +So Calc provides one special ``programmer-friendly'' function called +@code{calc-eval} that can be made to do just about everything you +need. It's not as fast as the low-level Calc functions, but it's +much simpler to use! + +It may seem that @code{calc-eval} itself has a daunting number of +options, but they all stem from one simple operation. + +In its simplest manifestation, @samp{(calc-eval "1+2")} parses the +string @code{"1+2"} as if it were a Calc algebraic entry and returns +the result formatted as a string: @code{"3"}. + +Since @code{calc-eval} is on the list of recommended @code{autoload} +functions, you don't need to make any special preparations to load +Calc before calling @code{calc-eval} the first time. Calc will be +loaded and initialized for you. + +All the Calc modes that are currently in effect will be used when +evaluating the expression and formatting the result. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Additional Arguments to @code{calc-eval} + +@noindent +If the input string parses to a list of expressions, Calc returns +the results separated by @code{", "}. You can specify a different +separator by giving a second string argument to @code{calc-eval}: +@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}. + +The ``separator'' can also be any of several Lisp symbols which +request other behaviors from @code{calc-eval}. These are discussed +one by one below. + +You can give additional arguments to be substituted for +@samp{$}, @samp{$$}, and so on in the main expression. For +example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the +expression @code{"7/(1+1)"} to yield the result @code{"3.5"} +(assuming Fraction mode is not in effect). Note the @code{nil} +used as a placeholder for the item-separator argument. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Error Handling + +@noindent +If @code{calc-eval} encounters an error, it returns a list containing +the character position of the error, plus a suitable message as a +string. Note that @samp{1 / 0} is @emph{not} an error by Calc's +standards; it simply returns the string @code{"1 / 0"} which is the +division left in symbolic form. But @samp{(calc-eval "1/")} will +return the list @samp{(2 "Expected a number")}. + +If you bind the variable @code{calc-eval-error} to @code{t} +using a @code{let} form surrounding the call to @code{calc-eval}, +errors instead call the Emacs @code{error} function which aborts +to the Emacs command loop with a beep and an error message. + +If you bind this variable to the symbol @code{string}, error messages +are returned as strings instead of lists. The character position is +ignored. + +As a courtesy to other Lisp code which may be using Calc, be sure +to bind @code{calc-eval-error} using @code{let} rather than changing +it permanently with @code{setq}. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Numbers Only + +@noindent +Sometimes it is preferable to treat @samp{1 / 0} as an error +rather than returning a symbolic result. If you pass the symbol +@code{num} as the second argument to @code{calc-eval}, results +that are not constants are treated as errors. The error message +reported is the first @code{calc-why} message if there is one, +or otherwise ``Number expected.'' + +A result is ``constant'' if it is a number, vector, or other +object that does not include variables or function calls. If it +is a vector, the components must themselves be constants. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Default Modes + +@noindent +If the first argument to @code{calc-eval} is a list whose first +element is a formula string, then @code{calc-eval} sets all the +various Calc modes to their default values while the formula is +evaluated and formatted. For example, the precision is set to 12 +digits, digit grouping is turned off, and the normal language +mode is used. + +This same principle applies to the other options discussed below. +If the first argument would normally be @var{x}, then it can also +be the list @samp{(@var{x})} to use the default mode settings. + +If there are other elements in the list, they are taken as +variable-name/value pairs which override the default mode +settings. Look at the documentation at the front of the +@file{calc.el} file to find the names of the Lisp variables for +the various modes. The mode settings are restored to their +original values when @code{calc-eval} is done. + +For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)} +computes the sum of two numbers, requiring a numeric result, and +using default mode settings except that the precision is 8 instead +of the default of 12. + +It's usually best to use this form of @code{calc-eval} unless your +program actually considers the interaction with Calc's mode settings +to be a feature. This will avoid all sorts of potential ``gotchas''; +consider what happens with @samp{(calc-eval "sqrt(2)" 'num)} +when the user has left Calc in symbolic mode or no-simplify mode. + +As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")} +checks if the number in string @cite{a} is less than the one in +string @cite{b}. Without using a list, the integer 1 might +come out in a variety of formats which would be hard to test for +conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But +see ``Predicates'' mode, below.) + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Raw Numbers + +@noindent +Normally all input and output for @code{calc-eval} is done with strings. +You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)} +in place of @samp{(+ a b)}, but this is very inefficient since the +numbers must be converted to and from string format as they are passed +from one @code{calc-eval} to the next. + +If the separator is the symbol @code{raw}, the result will be returned +as a raw Calc data structure rather than a string. You can read about +how these objects look in the following sections, but usually you can +treat them as ``black box'' objects with no important internal +structure. + +There is also a @code{rawnum} symbol, which is a combination of +@code{raw} (returning a raw Calc object) and @code{num} (signalling +an error if that object is not a constant). + +You can pass a raw Calc object to @code{calc-eval} in place of a +string, either as the formula itself or as one of the @samp{$} +arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an +addition function that operates on raw Calc objects. Of course +in this case it would be easier to call the low-level @code{math-add} +function in Calc, if you can remember its name. + +In particular, note that a plain Lisp integer is acceptable to Calc +as a raw object. (All Lisp integers are accepted on input, but +integers of more than six decimal digits are converted to ``big-integer'' +form for output. @xref{Data Type Formats}.) + +When it comes time to display the object, just use @samp{(calc-eval a)} +to format it as a string. + +It is an error if the input expression evaluates to a list of +values. The separator symbol @code{list} is like @code{raw} +except that it returns a list of one or more raw Calc objects. + +Note that a Lisp string is not a valid Calc object, nor is a list +containing a string. Thus you can still safely distinguish all the +various kinds of error returns discussed above. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Predicates + +@noindent +If the separator symbol is @code{pred}, the result of the formula is +treated as a true/false value; @code{calc-eval} returns @code{t} or +@code{nil}, respectively. A value is considered ``true'' if it is a +non-zero number, or false if it is zero or if it is not a number. + +For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether +one value is less than another. + +As usual, it is also possible for @code{calc-eval} to return one of +the error indicators described above. Lisp will interpret such an +indicator as ``true'' if you don't check for it explicitly. If you +wish to have an error register as ``false'', use something like +@samp{(eq (calc-eval ...) t)}. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Variable Values + +@noindent +Variables in the formula passed to @code{calc-eval} are not normally +replaced by their values. If you wish this, you can use the +@code{evalv} function (@pxref{Algebraic Manipulation}). For example, +if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable +@code{var-a}), then @samp{(calc-eval "a+pi")} will return the +formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")} +will return @code{"7.14159265359"}. + +To store in a Calc variable, just use @code{setq} to store in the +corresponding Lisp variable. (This is obtained by prepending +@samp{var-} to the Calc variable name.) Calc routines will +understand either string or raw form values stored in variables, +although raw data objects are much more efficient. For example, +to increment the Calc variable @code{a}: + +@example +(setq var-a (calc-eval "evalv(a+1)" 'raw)) +@end example + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Stack Access + +@noindent +If the separator symbol is @code{push}, the formula argument is +evaluated (with possible @samp{$} expansions, as usual). The +result is pushed onto the Calc stack. The return value is @code{nil} +(unless there is an error from evaluating the formula, in which +case the return value depends on @code{calc-eval-error} in the +usual way). + +If the separator symbol is @code{pop}, the first argument to +@code{calc-eval} must be an integer instead of a string. That +many values are popped from the stack and thrown away. A negative +argument deletes the entry at that stack level. The return value +is the number of elements remaining in the stack after popping; +@samp{(calc-eval 0 'pop)} is a good way to measure the size of +the stack. + +If the separator symbol is @code{top}, the first argument to +@code{calc-eval} must again be an integer. The value at that +stack level is formatted as a string and returned. Thus +@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the +integer is out of range, @code{nil} is returned. + +The separator symbol @code{rawtop} is just like @code{top} except +that the stack entry is returned as a raw Calc object instead of +as a string. + +In all of these cases the first argument can be made a list in +order to force the default mode settings, as described above. +Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the +second-to-top stack entry, formatted as a string using the default +instead of current display modes, except that the radix is +hexadecimal instead of decimal. + +It is, of course, polite to put the Calc stack back the way you +found it when you are done, unless the user of your program is +actually expecting it to affect the stack. + +Note that you do not actually have to switch into the @samp{*Calculator*} +buffer in order to use @code{calc-eval}; it temporarily switches into +the stack buffer if necessary. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Keyboard Macros + +@noindent +If the separator symbol is @code{macro}, the first argument must be a +string of characters which Calc can execute as a sequence of keystrokes. +This switches into the Calc buffer for the duration of the macro. +For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the +vector @samp{[1,2,3,4,5]} on the stack and then replaces it +with the sum of those numbers. Note that @samp{\r} is the Lisp +notation for the carriage-return, @key{RET}, character. + +If your keyboard macro wishes to pop the stack, @samp{\C-d} is +safer than @samp{\177} (the @key{DEL} character) because some +installations may have switched the meanings of @key{DEL} and +@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for +``pop-stack'' regardless of key mapping. + +If you provide a third argument to @code{calc-eval}, evaluation +of the keyboard macro will leave a record in the Trail using +that argument as a tag string. Normally the Trail is unaffected. + +The return value in this case is always @code{nil}. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Lisp Evaluation + +@noindent +Finally, if the separator symbol is @code{eval}, then the Lisp +@code{eval} function is called on the first argument, which must +be a Lisp expression rather than a Calc formula. Remember to +quote the expression so that it is not evaluated until inside +@code{calc-eval}. + +The difference from plain @code{eval} is that @code{calc-eval} +switches to the Calc buffer before evaluating the expression. +For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)} +will correctly affect the buffer-local Calc precision variable. + +An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}. +This is evaluating a call to the function that is normally invoked +by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.'' +Note that this function will leave a message in the echo area as +a side effect. Also, all Calc functions switch to the Calc buffer +automatically if not invoked from there, so the above call is +also equivalent to @samp{(calc-precision 17)} by itself. +In all cases, Calc uses @code{save-excursion} to switch back to +your original buffer when it is done. + +As usual the first argument can be a list that begins with a Lisp +expression to use default instead of current mode settings. + +The result of @code{calc-eval} in this usage is just the result +returned by the evaluated Lisp expression. + +@ifinfo +@example + +@end example +@end ifinfo +@subsubsection Example + +@noindent +@findex convert-temp +Here is a sample Emacs command that uses @code{calc-eval}. Suppose +you have a document with lots of references to temperatures on the +Fahrenheit scale, say ``98.6 F'', and you wish to convert these +references to Centigrade. The following command does this conversion. +Place the Emacs cursor right after the letter ``F'' and invoke the +command to change ``98.6 F'' to ``37 C''. Or, if the temperature is +already in Centigrade form, the command changes it back to Fahrenheit. + +@example +(defun convert-temp () + (interactive) + (save-excursion + (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)") + (let* ((top1 (match-beginning 1)) + (bot1 (match-end 1)) + (number (buffer-substring top1 bot1)) + (top2 (match-beginning 2)) + (bot2 (match-end 2)) + (type (buffer-substring top2 bot2))) + (if (equal type "F") + (setq type "C" + number (calc-eval "($ - 32)*5/9" nil number)) + (setq type "F" + number (calc-eval "$*9/5 + 32" nil number))) + (goto-char top2) + (delete-region top2 bot2) + (insert-before-markers type) + (goto-char top1) + (delete-region top1 bot1) + (if (string-match "\\.$" number) ; change "37." to "37" + (setq number (substring number 0 -1))) + (insert number)))) +@end example + +Note the use of @code{insert-before-markers} when changing between +``F'' and ``C'', so that the character winds up before the cursor +instead of after it. + +@node Internals, , Calling Calc from Your Programs, Lisp Definitions +@subsection Calculator Internals + +@noindent +This section describes the Lisp functions defined by the Calculator that +may be of use to user-written Calculator programs (as described in the +rest of this chapter). These functions are shown by their names as they +conventionally appear in @code{defmath}. Their full Lisp names are +generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their +apparent names. (Names that begin with @samp{calc-} are already in +their full Lisp form.) You can use the actual full names instead if you +prefer them, or if you are calling these functions from regular Lisp. + +The functions described here are scattered throughout the various +Calc component files. Note that @file{calc.el} includes @code{autoload}s +for only a few component files; when Calc wants to call an advanced +function it calls @samp{(calc-extensions)} first; this function +autoloads @file{calc-ext.el}, which in turn autoloads all the functions +in the remaining component files. + +Because @code{defmath} itself uses the extensions, user-written code +generally always executes with the extensions already loaded, so +normally you can use any Calc function and be confident that it will +be autoloaded for you when necessary. If you are doing something +special, check carefully to make sure each function you are using is +from @file{calc.el} or its components, and call @samp{(calc-extensions)} +before using any function based in @file{calc-ext.el} if you can't +prove this file will already be loaded. + +@menu +* Data Type Formats:: +* Interactive Lisp Functions:: +* Stack Lisp Functions:: +* Predicates:: +* Computational Lisp Functions:: +* Vector Lisp Functions:: +* Symbolic Lisp Functions:: +* Formatting Lisp Functions:: +* Hooks:: +@end menu + +@node Data Type Formats, Interactive Lisp Functions, Internals, Internals +@subsubsection Data Type Formats + +@noindent +Integers are stored in either of two ways, depending on their magnitude. +Integers less than one million in absolute value are stored as standard +Lisp integers. This is the only storage format for Calc data objects +which is not a Lisp list. + +Large integers are stored as lists of the form @samp{(bigpos @var{d0} +@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or +@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers +@i{-1000000} or less. Each @var{d} is a base-1000 ``digit,'' a Lisp integer +from 0 to 999. The least significant digit is @var{d0}; the last digit, +@var{dn}, which is always nonzero, is the most significant digit. For +example, the integer @i{-12345678} is stored as @samp{(bigneg 678 345 12)}. + +The distinction between small and large integers is entirely hidden from +the user. In @code{defmath} definitions, the Lisp predicate @code{integerp} +returns true for either kind of integer, and in general both big and small +integers are accepted anywhere the word ``integer'' is used in this manual. +If the distinction must be made, native Lisp integers are called @dfn{fixnums} +and large integers are called @dfn{bignums}. + +Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})} +where @var{n} is an integer (big or small) numerator, @var{d} is an +integer denominator greater than one, and @var{n} and @var{d} are relatively +prime. Note that fractions where @var{d} is one are automatically converted +to plain integers by all math routines; fractions where @var{d} is negative +are normalized by negating the numerator and denominator. + +Floating-point numbers are stored in the form, @samp{(float @var{mant} +@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than +@samp{10^@var{p}} in absolute value (@var{p} represents the current +precision), and @var{exp} (the ``exponent'') is a fixnum. The value of +the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number +@i{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints +are that the number 0.0 is always stored as @samp{(float 0 0)}, and, +except for the 0.0 case, the rightmost base-10 digit of @var{mant} is +always nonzero. (If the rightmost digit is zero, the number is +rearranged by dividing @var{mant} by ten and incrementing @var{exp}.)@refill + +Rectangular complex numbers are stored in the form @samp{(cplx @var{re} +@var{im})}, where @var{re} and @var{im} are each real numbers, either +integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}. +The @var{im} part is nonzero; complex numbers with zero imaginary +components are converted to real numbers automatically.@refill + +Polar complex numbers are stored in the form @samp{(polar @var{r} +@var{theta})}, where @var{r} is a positive real value and @var{theta} +is a real value or HMS form representing an angle. This angle is +usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees, +or @samp{(-pi ..@: pi)} radians, according to the current angular mode. +If the angle is 0 the value is converted to a real number automatically. +(If the angle is 180 degrees, the value is usually also converted to a +negative real number.)@refill + +Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m} +@var{s})}, where @var{h} is an integer or an integer-valued float (i.e., +a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued +float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number +in the range @samp{[0 ..@: 60)}.@refill + +Date forms are stored as @samp{(date @var{n})}, where @var{n} is +a real number that counts days since midnight on the morning of +January 1, 1 AD. If @var{n} is an integer, this is a pure date +form. If @var{n} is a fraction or float, this is a date/time form. + +Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a +positive real number or HMS form, and @var{n} is a real number or HMS +form in the range @samp{[0 ..@: @var{m})}. + +Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x} +is the mean value and @var{sigma} is the standard deviation. Each +component is either a number, an HMS form, or a symbolic object +(a variable or function call). If @var{sigma} is zero, the value is +converted to a plain real number. If @var{sigma} is negative or +complex, it is automatically normalized to be a positive real. + +Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})}, +where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and +@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask} +is a binary integer where 1 represents the fact that the interval is +closed on the high end, and 2 represents the fact that it is closed on +the low end. (Thus 3 represents a fully closed interval.) The interval +@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x}; +intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask} +represent empty intervals. If @var{hi} is less than @var{lo}, the interval +is converted to a standard empty interval by replacing @var{hi} with @var{lo}. + +Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1} +is the first element of the vector, @var{v2} is the second, and so on. +An empty vector is stored as @samp{(vec)}. A matrix is simply a vector +where all @var{v}'s are themselves vectors of equal lengths. Note that +Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is +generally unused by Calc data structures. + +Variables are stored as @samp{(var @var{name} @var{sym})}, where +@var{name} is a Lisp symbol whose print name is used as the visible name +of the variable, and @var{sym} is a Lisp symbol in which the variable's +value is actually stored. Thus, @samp{(var pi var-pi)} represents the +special constant @samp{pi}. Almost always, the form is @samp{(var +@var{v} var-@var{v})}. If the variable name was entered with @code{#} +signs (which are converted to hyphens internally), the form is +@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name +contains @code{#} characters, and @var{v} is a symbol that contains +@code{-} characters instead. The value of a variable is the Calc +object stored in its @var{sym} symbol's value cell. If the symbol's +value cell is void or if it contains @code{nil}, the variable has no +value. Special constants have the form @samp{(special-const +@var{value})} stored in their value cell, where @var{value} is a formula +which is evaluated when the constant's value is requested. Variables +which represent units are not stored in any special way; they are units +only because their names appear in the units table. If the value +cell contains a string, it is parsed to get the variable's value when +the variable is used.@refill + +A Lisp list with any other symbol as the first element is a function call. +The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^}, +and @code{|} represent special binary operators; these lists are always +of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the +sub-formula on the lefthand side and @var{rhs} is the sub-formula on the +right. The symbol @code{neg} represents unary negation; this list is always +of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a +function that would be displayed in function-call notation; the symbol +@var{func} is in general always of the form @samp{calcFunc-@var{name}}. +The function cell of the symbol @var{func} should contain a Lisp function +for evaluating a call to @var{func}. This function is passed the remaining +elements of the list (themselves already evaluated) as arguments; such +functions should return @code{nil} or call @code{reject-arg} to signify +that they should be left in symbolic form, or they should return a Calc +object which represents their value, or a list of such objects if they +wish to return multiple values. (The latter case is allowed only for +functions which are the outer-level call in an expression whose value is +about to be pushed on the stack; this feature is considered obsolete +and is not used by any built-in Calc functions.)@refill + +@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals +@subsubsection Interactive Functions + +@noindent +The functions described here are used in implementing interactive Calc +commands. Note that this list is not exhaustive! If there is an +existing command that behaves similarly to the one you want to define, +you may find helpful tricks by checking the source code for that command. + +@defun calc-set-command-flag flag +Set the command flag @var{flag}. This is generally a Lisp symbol, but +may in fact be anything. The effect is to add @var{flag} to the list +stored in the variable @code{calc-command-flags}, unless it is already +there. @xref{Defining Simple Commands}. +@end defun + +@defun calc-clear-command-flag flag +If @var{flag} appears among the list of currently-set command flags, +remove it from that list. +@end defun + +@defun calc-record-undo rec +Add the ``undo record'' @var{rec} to the list of steps to take if the +current operation should need to be undone. Stack push and pop functions +automatically call @code{calc-record-undo}, so the kinds of undo records +you might need to create take the form @samp{(set @var{sym} @var{value})}, +which says that the Lisp variable @var{sym} was changed and had previously +contained @var{value}; @samp{(store @var{var} @var{value})} which says that +the Calc variable @var{var} (a string which is the name of the symbol that +contains the variable's value) was stored and its previous value was +@var{value} (either a Calc data object, or @code{nil} if the variable was +previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})}, +which means that to undo requires calling the function @samp{(@var{undo} +@var{args} @dots{})} and, if the undo is later redone, calling +@samp{(@var{redo} @var{args} @dots{})}.@refill +@end defun + +@defun calc-record-why msg args +Record the error or warning message @var{msg}, which is normally a string. +This message will be replayed if the user types @kbd{w} (@code{calc-why}); +if the message string begins with a @samp{*}, it is considered important +enough to display even if the user doesn't type @kbd{w}. If one or more +@var{args} are present, the displayed message will be of the form, +@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are +formatted on the assumption that they are either strings or Calc objects of +some sort. If @var{msg} is a symbol, it is the name of a Calc predicate +(such as @code{integerp} or @code{numvecp}) which the arguments did not +satisfy; it is expanded to a suitable string such as ``Expected an +integer.'' The @code{reject-arg} function calls @code{calc-record-why} +automatically; @pxref{Predicates}.@refill +@end defun + +@defun calc-is-inverse +This predicate returns true if the current command is inverse, +i.e., if the Inverse (@kbd{I} key) flag was set. +@end defun + +@defun calc-is-hyperbolic +This predicate is the analogous function for the @kbd{H} key. +@end defun + +@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals +@subsubsection Stack-Oriented Functions + +@noindent +The functions described here perform various operations on the Calc +stack and trail. They are to be used in interactive Calc commands. + +@defun calc-push-list vals n +Push the Calc objects in list @var{vals} onto the stack at stack level +@var{n}. If @var{n} is omitted it defaults to 1, so that the elements +are pushed at the top of the stack. If @var{n} is greater than 1, the +elements will be inserted into the stack so that the last element will +end up at level @var{n}, the next-to-last at level @var{n}+1, etc. +The elements of @var{vals} are assumed to be valid Calc objects, and +are not evaluated, rounded, or renormalized in any way. If @var{vals} +is an empty list, nothing happens.@refill + +The stack elements are pushed without any sub-formula selections. +You can give an optional third argument to this function, which must +be a list the same size as @var{vals} of selections. Each selection +must be @code{eq} to some sub-formula of the corresponding formula +in @var{vals}, or @code{nil} if that formula should have no selection. +@end defun + +@defun calc-top-list n m +Return a list of the @var{n} objects starting at level @var{m} of the +stack. If @var{m} is omitted it defaults to 1, so that the elements are +taken from the top of the stack. If @var{n} is omitted, it also +defaults to 1, so that the top stack element (in the form of a +one-element list) is returned. If @var{m} is greater than 1, the +@var{m}th stack element will be at the end of the list, the @var{m}+1st +element will be next-to-last, etc. If @var{n} or @var{m} are out of +range, the command is aborted with a suitable error message. If @var{n} +is zero, the function returns an empty list. The stack elements are not +evaluated, rounded, or renormalized.@refill + +If any stack elements contain selections, and selections have not +been disabled by the @kbd{j e} (@code{calc-enable-selections}) command, +this function returns the selected portions rather than the entire +stack elements. It can be given a third ``selection-mode'' argument +which selects other behaviors. If it is the symbol @code{t}, then +a selection in any of the requested stack elements produces an +``illegal operation on selections'' error. If it is the symbol @code{full}, +the whole stack entry is always returned regardless of selections. +If it is the symbol @code{sel}, the selected portion is always returned, +or @code{nil} if there is no selection. (This mode ignores the @kbd{j e} +command.) If the symbol is @code{entry}, the complete stack entry in +list form is returned; the first element of this list will be the whole +formula, and the third element will be the selection (or @code{nil}). +@end defun + +@defun calc-pop-stack n m +Remove the specified elements from the stack. The parameters @var{n} +and @var{m} are defined the same as for @code{calc-top-list}. The return +value of @code{calc-pop-stack} is uninteresting. + +If there are any selected sub-formulas among the popped elements, and +@kbd{j e} has not been used to disable selections, this produces an +error without changing the stack. If you supply an optional third +argument of @code{t}, the stack elements are popped even if they +contain selections. +@end defun + +@defun calc-record-list vals tag +This function records one or more results in the trail. The @var{vals} +are a list of strings or Calc objects. The @var{tag} is the four-character +tag string to identify the values. If @var{tag} is omitted, a blank tag +will be used. +@end defun + +@defun calc-normalize n +This function takes a Calc object and ``normalizes'' it. At the very +least this involves re-rounding floating-point values according to the +current precision and other similar jobs. Also, unless the user has +selected no-simplify mode (@pxref{Simplification Modes}), this involves +actually evaluating a formula object by executing the function calls +it contains, and possibly also doing algebraic simplification, etc. +@end defun + +@defun calc-top-list-n n m +This function is identical to @code{calc-top-list}, except that it calls +@code{calc-normalize} on the values that it takes from the stack. They +are also passed through @code{check-complete}, so that incomplete +objects will be rejected with an error message. All computational +commands should use this in preference to @code{calc-top-list}; the only +standard Calc commands that operate on the stack without normalizing +are stack management commands like @code{calc-enter} and @code{calc-roll-up}. +This function accepts the same optional selection-mode argument as +@code{calc-top-list}. +@end defun + +@defun calc-top-n m +This function is a convenient form of @code{calc-top-list-n} in which only +a single element of the stack is taken and returned, rather than a list +of elements. This also accepts an optional selection-mode argument. +@end defun + +@defun calc-enter-result n tag vals +This function is a convenient interface to most of the above functions. +The @var{vals} argument should be either a single Calc object, or a list +of Calc objects; the object or objects are normalized, and the top @var{n} +stack entries are replaced by the normalized objects. If @var{tag} is +non-@code{nil}, the normalized objects are also recorded in the trail. +A typical stack-based computational command would take the form, + +@smallexample +(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func} + (calc-top-list-n @var{n}))) +@end smallexample + +If any of the @var{n} stack elements replaced contain sub-formula +selections, and selections have not been disabled by @kbd{j e}, +this function takes one of two courses of action. If @var{n} is +equal to the number of elements in @var{vals}, then each element of +@var{vals} is spliced into the corresponding selection; this is what +happens when you use the @key{TAB} key, or when you use a unary +arithmetic operation like @code{sqrt}. If @var{vals} has only one +element but @var{n} is greater than one, there must be only one +selection among the top @var{n} stack elements; the element from +@var{vals} is spliced into that selection. This is what happens when +you use a binary arithmetic operation like @kbd{+}. Any other +combination of @var{n} and @var{vals} is an error when selections +are present. +@end defun + +@defun calc-unary-op tag func arg +This function implements a unary operator that allows a numeric prefix +argument to apply the operator over many stack entries. If the prefix +argument @var{arg} is @code{nil}, this uses @code{calc-enter-result} +as outlined above. Otherwise, it maps the function over several stack +elements; @pxref{Prefix Arguments}. For example,@refill + +@smallexample +(defun calc-zeta (arg) + (interactive "P") + (calc-unary-op "zeta" 'calcFunc-zeta arg)) +@end smallexample +@end defun + +@defun calc-binary-op tag func arg ident unary +This function implements a binary operator, analogously to +@code{calc-unary-op}. The optional @var{ident} and @var{unary} +arguments specify the behavior when the prefix argument is zero or +one, respectively. If the prefix is zero, the value @var{ident} +is pushed onto the stack, if specified, otherwise an error message +is displayed. If the prefix is one, the unary function @var{unary} +is applied to the top stack element, or, if @var{unary} is not +specified, nothing happens. When the argument is two or more, +the binary function @var{func} is reduced across the top @var{arg} +stack elements; when the argument is negative, the function is +mapped between the next-to-top @i{-@var{arg}} stack elements and the +top element.@refill +@end defun + +@defun calc-stack-size +Return the number of elements on the stack as an integer. This count +does not include elements that have been temporarily hidden by stack +truncation; @pxref{Truncating the Stack}. +@end defun + +@defun calc-cursor-stack-index n +Move the point to the @var{n}th stack entry. If @var{n} is zero, this +will be the @samp{.} line. If @var{n} is from 1 to the current stack size, +this will be the beginning of the first line of that stack entry's display. +If line numbers are enabled, this will move to the first character of the +line number, not the stack entry itself.@refill +@end defun + +@defun calc-substack-height n +Return the number of lines between the beginning of the @var{n}th stack +entry and the bottom of the buffer. If @var{n} is zero, this +will be one (assuming no stack truncation). If all stack entries are +one line long (i.e., no matrices are displayed), the return value will +be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big +mode, the return value includes the blank lines that separate stack +entries.)@refill +@end defun + +@defun calc-refresh +Erase the @code{*Calculator*} buffer and reformat its contents from memory. +This must be called after changing any parameter, such as the current +display radix, which might change the appearance of existing stack +entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing +is suppressed, but a flag is set so that the entire stack will be refreshed +rather than just the top few elements when the macro finishes.)@refill +@end defun + +@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals +@subsubsection Predicates + +@noindent +The functions described here are predicates, that is, they return a +true/false value where @code{nil} means false and anything else means +true. These predicates are expanded by @code{defmath}, for example, +from @code{zerop} to @code{math-zerop}. In many cases they correspond +to native Lisp functions by the same name, but are extended to cover +the full range of Calc data types. + +@defun zerop x +Returns true if @var{x} is numerically zero, in any of the Calc data +types. (Note that for some types, such as error forms and intervals, +it never makes sense to return true.) In @code{defmath}, the expression +@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)}, +and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}. +@end defun + +@defun negp x +Returns true if @var{x} is negative. This accepts negative real numbers +of various types, negative HMS and date forms, and intervals in which +all included values are negative. In @code{defmath}, the expression +@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)}, +and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}. +@end defun + +@defun posp x +Returns true if @var{x} is positive (and non-zero). For complex +numbers, none of these three predicates will return true. +@end defun + +@defun looks-negp x +Returns true if @var{x} is ``negative-looking.'' This returns true if +@var{x} is a negative number, or a formula with a leading minus sign +such as @samp{-a/b}. In other words, this is an object which can be +made simpler by calling @code{(- @var{x})}. +@end defun + +@defun integerp x +Returns true if @var{x} is an integer of any size. +@end defun + +@defun fixnump x +Returns true if @var{x} is a native Lisp integer. +@end defun + +@defun natnump x +Returns true if @var{x} is a nonnegative integer of any size. +@end defun + +@defun fixnatnump x +Returns true if @var{x} is a nonnegative Lisp integer. +@end defun + +@defun num-integerp x +Returns true if @var{x} is numerically an integer, i.e., either a +true integer or a float with no significant digits to the right of +the decimal point. +@end defun + +@defun messy-integerp x +Returns true if @var{x} is numerically, but not literally, an integer. +A value is @code{num-integerp} if it is @code{integerp} or +@code{messy-integerp} (but it is never both at once). +@end defun + +@defun num-natnump x +Returns true if @var{x} is numerically a nonnegative integer. +@end defun + +@defun evenp x +Returns true if @var{x} is an even integer. +@end defun + +@defun looks-evenp x +Returns true if @var{x} is an even integer, or a formula with a leading +multiplicative coefficient which is an even integer. +@end defun + +@defun oddp x +Returns true if @var{x} is an odd integer. +@end defun + +@defun ratp x +Returns true if @var{x} is a rational number, i.e., an integer or a +fraction. +@end defun + +@defun realp x +Returns true if @var{x} is a real number, i.e., an integer, fraction, +or floating-point number. +@end defun + +@defun anglep x +Returns true if @var{x} is a real number or HMS form. +@end defun + +@defun floatp x +Returns true if @var{x} is a float, or a complex number, error form, +interval, date form, or modulo form in which at least one component +is a float. +@end defun + +@defun complexp x +Returns true if @var{x} is a rectangular or polar complex number +(but not a real number). +@end defun + +@defun rect-complexp x +Returns true if @var{x} is a rectangular complex number. +@end defun + +@defun polar-complexp x +Returns true if @var{x} is a polar complex number. +@end defun + +@defun numberp x +Returns true if @var{x} is a real number or a complex number. +@end defun + +@defun scalarp x +Returns true if @var{x} is a real or complex number or an HMS form. +@end defun + +@defun vectorp x +Returns true if @var{x} is a vector (this simply checks if its argument +is a list whose first element is the symbol @code{vec}). +@end defun + +@defun numvecp x +Returns true if @var{x} is a number or vector. +@end defun + +@defun matrixp x +Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors, +all of the same size. +@end defun + +@defun square-matrixp x +Returns true if @var{x} is a square matrix. +@end defun + +@defun objectp x +Returns true if @var{x} is any numeric Calc object, including real and +complex numbers, HMS forms, date forms, error forms, intervals, and +modulo forms. (Note that error forms and intervals may include formulas +as their components; see @code{constp} below.) +@end defun + +@defun objvecp x +Returns true if @var{x} is an object or a vector. This also accepts +incomplete objects, but it rejects variables and formulas (except as +mentioned above for @code{objectp}). +@end defun + +@defun primp x +Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object, +i.e., one whose components cannot be regarded as sub-formulas. This +includes variables, and all @code{objectp} types except error forms +and intervals. +@end defun + +@defun constp x +Returns true if @var{x} is constant, i.e., a real or complex number, +HMS form, date form, or error form, interval, or vector all of whose +components are @code{constp}. +@end defun + +@defun lessp x y +Returns true if @var{x} is numerically less than @var{y}. Returns false +if @var{x} is greater than or equal to @var{y}, or if the order is +undefined or cannot be determined. Generally speaking, this works +by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In +@code{defmath}, the expression @samp{(< x y)} will automatically be +converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=}, +and @code{>=} are similarly converted in terms of @code{lessp}.@refill +@end defun + +@defun beforep x y +Returns true if @var{x} comes before @var{y} in a canonical ordering +of Calc objects. If @var{x} and @var{y} are both real numbers, this +will be the same as @code{lessp}. But whereas @code{lessp} considers +other types of objects to be unordered, @code{beforep} puts any two +objects into a definite, consistent order. The @code{beforep} +function is used by the @kbd{V S} vector-sorting command, and also +by @kbd{a s} to put the terms of a product into canonical order: +This allows @samp{x y + y x} to be simplified easily to @samp{2 x y}. +@end defun + +@defun equal x y +This is the standard Lisp @code{equal} predicate; it returns true if +@var{x} and @var{y} are structurally identical. This is the usual way +to compare numbers for equality, but note that @code{equal} will treat +0 and 0.0 as different. +@end defun + +@defun math-equal x y +Returns true if @var{x} and @var{y} are numerically equal, either because +they are @code{equal}, or because their difference is @code{zerop}. In +@code{defmath}, the expression @samp{(= x y)} will automatically be +converted to @samp{(math-equal x y)}. +@end defun + +@defun equal-int x n +Returns true if @var{x} and @var{n} are numerically equal, where @var{n} +is a fixnum which is not a multiple of 10. This will automatically be +used by @code{defmath} in place of the more general @code{math-equal} +whenever possible.@refill +@end defun + +@defun nearly-equal x y +Returns true if @var{x} and @var{y}, as floating-point numbers, are +equal except possibly in the last decimal place. For example, +314.159 and 314.166 are considered nearly equal if the current +precision is 6 (since they differ by 7 units), but not if the current +precision is 7 (since they differ by 70 units). Most functions which +use series expansions use @code{with-extra-prec} to evaluate the +series with 2 extra digits of precision, then use @code{nearly-equal} +to decide when the series has converged; this guards against cumulative +error in the series evaluation without doing extra work which would be +lost when the result is rounded back down to the current precision. +In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}. +The @var{x} and @var{y} can be numbers of any kind, including complex. +@end defun + +@defun nearly-zerop x y +Returns true if @var{x} is nearly zero, compared to @var{y}. This +checks whether @var{x} plus @var{y} would by be @code{nearly-equal} +to @var{y} itself, to within the current precision, in other words, +if adding @var{x} to @var{y} would have a negligible effect on @var{y} +due to roundoff error. @var{X} may be a real or complex number, but +@var{y} must be real. +@end defun + +@defun is-true x +Return true if the formula @var{x} represents a true value in +Calc, not Lisp, terms. It tests if @var{x} is a non-zero number +or a provably non-zero formula. +@end defun + +@defun reject-arg val pred +Abort the current function evaluation due to unacceptable argument values. +This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a +Lisp error which @code{normalize} will trap. The net effect is that the +function call which led here will be left in symbolic form.@refill +@end defun + +@defun inexact-value +If Symbolic Mode is enabled, this will signal an error that causes +@code{normalize} to leave the formula in symbolic form, with the message +``Inexact result.'' (This function has no effect when not in Symbolic Mode.) +Note that if your function calls @samp{(sin 5)} in Symbolic Mode, the +@code{sin} function will call @code{inexact-value}, which will cause your +function to be left unsimplified. You may instead wish to call +@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic Mode will +return the formula @samp{sin(5)} to your function.@refill +@end defun + +@defun overflow +This signals an error that will be reported as a floating-point overflow. +@end defun + +@defun underflow +This signals a floating-point underflow. +@end defun + +@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals +@subsubsection Computational Functions + +@noindent +The functions described here do the actual computational work of the +Calculator. In addition to these, note that any function described in +the main body of this manual may be called from Lisp; for example, if +the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command, +this means @code{calc-sqrt} is an interactive stack-based square-root +command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt}) +is the actual Lisp function for taking square roots.@refill + +The functions @code{math-add}, @code{math-sub}, @code{math-mul}, +@code{math-div}, @code{math-mod}, and @code{math-neg} are not included +in this list, since @code{defmath} allows you to write native Lisp +@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-}, +respectively, instead.@refill + +@defun normalize val +(Full form: @code{math-normalize}.) +Reduce the value @var{val} to standard form. For example, if @var{val} +is a fixnum, it will be converted to a bignum if it is too large, and +if @var{val} is a bignum it will be normalized by clipping off trailing +(i.e., most-significant) zero digits and converting to a fixnum if it is +small. All the various data types are similarly converted to their standard +forms. Variables are left alone, but function calls are actually evaluated +in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will +return 6.@refill + +If a function call fails, because the function is void or has the wrong +number of parameters, or because it returns @code{nil} or calls +@code{reject-arg} or @code{inexact-result}, @code{normalize} returns +the formula still in symbolic form.@refill + +If the current Simplification Mode is ``none'' or ``numeric arguments +only,'' @code{normalize} will act appropriately. However, the more +powerful simplification modes (like algebraic simplification) are +not handled by @code{normalize}. They are handled by @code{calc-normalize}, +which calls @code{normalize} and possibly some other routines, such +as @code{simplify} or @code{simplify-units}. Programs generally will +never call @code{calc-normalize} except when popping or pushing values +on the stack.@refill +@end defun + +@defun evaluate-expr expr +Replace all variables in @var{expr} that have values with their values, +then use @code{normalize} to simplify the result. This is what happens +when you press the @kbd{=} key interactively.@refill +@end defun + +@defmac with-extra-prec n body +Evaluate the Lisp forms in @var{body} with precision increased by @var{n} +digits. This is a macro which expands to + +@smallexample +(math-normalize + (let ((calc-internal-prec (+ calc-internal-prec @var{n}))) + @var{body})) +@end smallexample + +The surrounding call to @code{math-normalize} causes a floating-point +result to be rounded down to the original precision afterwards. This +is important because some arithmetic operations assume a number's +mantissa contains no more digits than the current precision allows. +@end defmac + +@defun make-frac n d +Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling +@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient. +@end defun + +@defun make-float mant exp +Build a floating-point value out of @var{mant} and @var{exp}, both +of which are arbitrary integers. This function will return a +properly normalized float value, or signal an overflow or underflow +if @var{exp} is out of range. +@end defun + +@defun make-sdev x sigma +Build an error form out of @var{x} and the absolute value of @var{sigma}. +If @var{sigma} is zero, the result is the number @var{x} directly. +If @var{sigma} is negative or complex, its absolute value is used. +If @var{x} or @var{sigma} is not a valid type of object for use in +error forms, this calls @code{reject-arg}. +@end defun + +@defun make-intv mask lo hi +Build an interval form out of @var{mask} (which is assumed to be an +integer from 0 to 3), and the limits @var{lo} and @var{hi}. If +@var{lo} is greater than @var{hi}, an empty interval form is returned. +This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable. +@end defun + +@defun sort-intv mask lo hi +Build an interval form, similar to @code{make-intv}, except that if +@var{lo} is less than @var{hi} they are simply exchanged, and the +bits of @var{mask} are swapped accordingly. +@end defun + +@defun make-mod n m +Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo +forms do not allow formulas as their components, if @var{n} or @var{m} +is not a real number or HMS form the result will be a formula which +is a call to @code{makemod}, the algebraic version of this function. +@end defun + +@defun float x +Convert @var{x} to floating-point form. Integers and fractions are +converted to numerically equivalent floats; components of complex +numbers, vectors, HMS forms, date forms, error forms, intervals, and +modulo forms are recursively floated. If the argument is a variable +or formula, this calls @code{reject-arg}. +@end defun + +@defun compare x y +Compare the numbers @var{x} and @var{y}, and return @i{-1} if +@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})}, +0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is +undefined or cannot be determined.@refill +@end defun + +@defun numdigs n +Return the number of digits of integer @var{n}, effectively +@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is +considered to have zero digits. +@end defun + +@defun scale-int x n +Shift integer @var{x} left @var{n} decimal digits, or right @i{-@var{n}} +digits with truncation toward zero. +@end defun + +@defun scale-rounding x n +Like @code{scale-int}, except that a right shift rounds to the nearest +integer rather than truncating. +@end defun + +@defun fixnum n +Return the integer @var{n} as a fixnum, i.e., a native Lisp integer. +If @var{n} is outside the permissible range for Lisp integers (usually +24 binary bits) the result is undefined. +@end defun + +@defun sqr x +Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}. +@end defun + +@defun quotient x y +Divide integer @var{x} by integer @var{y}; return an integer quotient +and discard the remainder. If @var{x} or @var{y} is negative, the +direction of rounding is undefined. +@end defun + +@defun idiv x y +Perform an integer division; if @var{x} and @var{y} are both nonnegative +integers, this uses the @code{quotient} function, otherwise it computes +@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but +slower than for @code{quotient}. +@end defun + +@defun imod x y +Divide integer @var{x} by integer @var{y}; return the integer remainder +and discard the quotient. Like @code{quotient}, this works only for +integer arguments and is not well-defined for negative arguments. +For a more well-defined result, use @samp{(% @var{x} @var{y})}. +@end defun + +@defun idivmod x y +Divide integer @var{x} by integer @var{y}; return a cons cell whose +@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr} +is @samp{(imod @var{x} @var{y})}.@refill +@end defun + +@defun pow x y +Compute @var{x} to the power @var{y}. In @code{defmath} code, this can +also be written @samp{(^ @var{x} @var{y})} or +@w{@samp{(expt @var{x} @var{y})}}.@refill +@end defun + +@defun abs-approx x +Compute a fast approximation to the absolute value of @var{x}. For +example, for a rectangular complex number the result is the sum of +the absolute values of the components. +@end defun + +@findex two-pi +@findex pi-over-2 +@findex pi-over-4 +@findex pi-over-180 +@findex sqrt-two-pi +@findex sqrt-e +@findex e +@findex ln-2 +@findex ln-10 +@defun pi +The function @samp{(pi)} computes @samp{pi} to the current precision. +Other related constant-generating functions are @code{two-pi}, +@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi}, +@code{e}, @code{sqrt-e}, @code{ln-2}, and @code{ln-10}. Each function +returns a floating-point value in the current precision, and each uses +caching so that all calls after the first are essentially free.@refill +@end defun + +@defmac math-defcache @var{func} @var{initial} @var{form} +This macro, usually used as a top-level call like @code{defun} or +@code{defvar}, defines a new cached constant analogous to @code{pi}, etc. +It defines a function @code{func} which returns the requested value; +if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})} +form which serves as an initial value for the cache. If @var{func} +is called when the cache is empty or does not have enough digits to +satisfy the current precision, the Lisp expression @var{form} is evaluated +with the current precision increased by four, and the result minus its +two least significant digits is stored in the cache. For example, +calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34 +digits, rounds it down to 32 digits for future use, then rounds it +again to 30 digits for use in the present request.@refill +@end defmac + +@findex half-circle +@findex quarter-circle +@defun full-circle symb +If the current angular mode is Degrees or HMS, this function returns the +integer 360. In Radians mode, this function returns either the +corresponding value in radians to the current precision, or the formula +@samp{2*pi}, depending on the Symbolic Mode. There are also similar +function @code{half-circle} and @code{quarter-circle}. +@end defun + +@defun power-of-2 n +Compute two to the integer power @var{n}, as a (potentially very large) +integer. Powers of two are cached, so only the first call for a +particular @var{n} is expensive. +@end defun + +@defun integer-log2 n +Compute the base-2 logarithm of @var{n}, which must be an integer which +is a power of two. If @var{n} is not a power of two, this function will +return @code{nil}. +@end defun + +@defun div-mod a b m +Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if +there is no solution, or if any of the arguments are not integers.@refill +@end defun + +@defun pow-mod a b m +Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a}, +@var{b}, and @var{m} are integers, this uses an especially efficient +algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}. +@end defun + +@defun isqrt n +Compute the integer square root of @var{n}. This is the square root +of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}. +If @var{n} is itself an integer, the computation is especially efficient. +@end defun + +@defun to-hms a ang +Convert the argument @var{a} into an HMS form. If @var{ang} is specified, +it is the angular mode in which to interpret @var{a}, either @code{deg} +or @code{rad}. Otherwise, the current angular mode is used. If @var{a} +is already an HMS form it is returned as-is. +@end defun + +@defun from-hms a ang +Convert the HMS form @var{a} into a real number. If @var{ang} is specified, +it is the angular mode in which to express the result, otherwise the +current angular mode is used. If @var{a} is already a real number, it +is returned as-is. +@end defun + +@defun to-radians a +Convert the number or HMS form @var{a} to radians from the current +angular mode. +@end defun + +@defun from-radians a +Convert the number @var{a} from radians to the current angular mode. +If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}. +@end defun + +@defun to-radians-2 a +Like @code{to-radians}, except that in Symbolic Mode a degrees to +radians conversion yields a formula like @samp{@var{a}*pi/180}. +@end defun + +@defun from-radians-2 a +Like @code{from-radians}, except that in Symbolic Mode a radians to +degrees conversion yields a formula like @samp{@var{a}*180/pi}. +@end defun + +@defun random-digit +Produce a random base-1000 digit in the range 0 to 999. +@end defun + +@defun random-digits n +Produce a random @var{n}-digit integer; this will be an integer +in the interval @samp{[0, 10^@var{n})}. +@end defun + +@defun random-float +Produce a random float in the interval @samp{[0, 1)}. +@end defun + +@defun prime-test n iters +Determine whether the integer @var{n} is prime. Return a list which has +one of these forms: @samp{(nil @var{f})} means the number is non-prime +because it was found to be divisible by @var{f}; @samp{(nil)} means it +was found to be non-prime by table look-up (so no factors are known); +@samp{(nil unknown)} means it is definitely non-prime but no factors +are known because @var{n} was large enough that Fermat's probabilistic +test had to be used; @samp{(t)} means the number is definitely prime; +and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i} +iterations, is @var{p} percent sure that the number is prime. The +@var{iters} parameter is the number of Fermat iterations to use, in the +case that this is necessary. If @code{prime-test} returns ``maybe,'' +you can call it again with the same @var{n} to get a greater certainty; +@code{prime-test} remembers where it left off.@refill +@end defun + +@defun to-simple-fraction f +If @var{f} is a floating-point number which can be represented exactly +as a small rational number. return that number, else return @var{f}. +For example, 0.75 would be converted to 3:4. This function is very +fast. +@end defun + +@defun to-fraction f tol +Find a rational approximation to floating-point number @var{f} to within +a specified tolerance @var{tol}; this corresponds to the algebraic +function @code{frac}, and can be rather slow. +@end defun + +@defun quarter-integer n +If @var{n} is an integer or integer-valued float, this function +returns zero. If @var{n} is a half-integer (i.e., an integer plus +@i{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer, +it returns 1 or 3. If @var{n} is anything else, this function +returns @code{nil}. +@end defun + +@node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals +@subsubsection Vector Functions + +@noindent +The functions described here perform various operations on vectors and +matrices. + +@defun math-concat x y +Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}} +in a symbolic formula. @xref{Building Vectors}. +@end defun + +@defun vec-length v +Return the length of vector @var{v}. If @var{v} is not a vector, the +result is zero. If @var{v} is a matrix, this returns the number of +rows in the matrix. +@end defun + +@defun mat-dimens m +Determine the dimensions of vector or matrix @var{m}. If @var{m} is not +a vector, the result is an empty list. If @var{m} is a plain vector +but not a matrix, the result is a one-element list containing the length +of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns, +the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors +produce lists of more than two dimensions. Note that the object +@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size, +and is treated by this and other Calc routines as a plain vector of two +elements.@refill +@end defun + +@defun dimension-error +Abort the current function with a message of ``Dimension error.'' +The Calculator will leave the function being evaluated in symbolic +form; this is really just a special case of @code{reject-arg}. +@end defun + +@defun build-vector args +Return a Calc vector with the zero-or-more @var{args} as elements. +For example, @samp{(build-vector 1 2 3)} returns the Calc vector +@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}. +@end defun + +@defun make-vec obj dims +Return a Calc vector or matrix all of whose elements are equal to +@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix +filled with 27's. +@end defun + +@defun row-matrix v +If @var{v} is a plain vector, convert it into a row matrix, i.e., +a matrix whose single row is @var{v}. If @var{v} is already a matrix, +leave it alone. +@end defun + +@defun col-matrix v +If @var{v} is a plain vector, convert it into a column matrix, i.e., a +matrix with each element of @var{v} as a separate row. If @var{v} is +already a matrix, leave it alone. +@end defun + +@defun map-vec f v +Map the Lisp function @var{f} over the Calc vector @var{v}. For example, +@samp{(map-vec 'math-floor v)} returns a vector of the floored components +of vector @var{v}. +@end defun + +@defun map-vec-2 f a b +Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}. +If @var{a} and @var{b} are vectors of equal length, the result is a +vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})} +for each pair of elements @var{ai} and @var{bi}. If either @var{a} or +@var{b} is a scalar, it is matched with each value of the other vector. +For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v} +with each element increased by one. Note that using @samp{'+} would not +work here, since @code{defmath} does not expand function names everywhere, +just where they are in the function position of a Lisp expression.@refill +@end defun + +@defun reduce-vec f v +Reduce the function @var{f} over the vector @var{v}. For example, if +@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}. +If @var{v} is a matrix, this reduces over the rows of @var{v}. +@end defun + +@defun reduce-cols f m +Reduce the function @var{f} over the columns of matrix @var{m}. For +example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result +is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}. +@end defun + +@defun mat-row m n +Return the @var{n}th row of matrix @var{m}. This is equivalent to +@samp{(elt m n)}. For a slower but safer version, use @code{mrow}. +(@xref{Extracting Elements}.) +@end defun + +@defun mat-col m n +Return the @var{n}th column of matrix @var{m}, in the form of a vector. +The arguments are not checked for correctness. +@end defun + +@defun mat-less-row m n +Return a copy of matrix @var{m} with its @var{n}th row deleted. The +number @var{n} must be in range from 1 to the number of rows in @var{m}. +@end defun + +@defun mat-less-col m n +Return a copy of matrix @var{m} with its @var{n}th column deleted. +@end defun + +@defun transpose m +Return the transpose of matrix @var{m}. +@end defun + +@defun flatten-vector v +Flatten nested vector @var{v} into a vector of scalars. For example, +if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}. +@end defun + +@defun copy-matrix m +If @var{m} is a matrix, return a copy of @var{m}. This maps +@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each +element of the result matrix will be @code{eq} to the corresponding +element of @var{m}, but none of the @code{cons} cells that make up +the structure of the matrix will be @code{eq}. If @var{m} is a plain +vector, this is the same as @code{copy-sequence}.@refill +@end defun + +@defun swap-rows m r1 r2 +Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In +other words, unlike most of the other functions described here, this +function changes @var{m} itself rather than building up a new result +matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)} +is true, with the side effect of exchanging the first two rows of +@var{m}.@refill +@end defun + +@node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals +@subsubsection Symbolic Functions + +@noindent +The functions described here operate on symbolic formulas in the +Calculator. + +@defun calc-prepare-selection num +Prepare a stack entry for selection operations. If @var{num} is +omitted, the stack entry containing the cursor is used; otherwise, +it is the number of the stack entry to use. This function stores +useful information about the current stack entry into a set of +variables. @code{calc-selection-cache-num} contains the number of +the stack entry involved (equal to @var{num} if you specified it); +@code{calc-selection-cache-entry} contains the stack entry as a +list (such as @code{calc-top-list} would return with @code{entry} +as the selection mode); and @code{calc-selection-cache-comp} contains +a special ``tagged'' composition (@pxref{Formatting Lisp Functions}) +which allows Calc to relate cursor positions in the buffer with +their corresponding sub-formulas. + +A slight complication arises in the selection mechanism because +formulas may contain small integers. For example, in the vector +@samp{[1, 2, 1]} the first and last elements are @code{eq} to each +other; selections are recorded as the actual Lisp object that +appears somewhere in the tree of the whole formula, but storing +@code{1} would falsely select both @code{1}'s in the vector. So +@code{calc-prepare-selection} also checks the stack entry and +replaces any plain integers with ``complex number'' lists of the form +@samp{(cplx @var{n} 0)}. This list will be displayed the same as a +plain @var{n} and the change will be completely invisible to the +user, but it will guarantee that no two sub-formulas of the stack +entry will be @code{eq} to each other. Next time the stack entry +is involved in a computation, @code{calc-normalize} will replace +these lists with plain numbers again, again invisibly to the user. +@end defun + +@defun calc-encase-atoms x +This modifies the formula @var{x} to ensure that each part of the +formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick +described above. This function may use @code{setcar} to modify +the formula in-place. +@end defun + +@defun calc-find-selected-part +Find the smallest sub-formula of the current formula that contains +the cursor. This assumes @code{calc-prepare-selection} has been +called already. If the cursor is not actually on any part of the +formula, this returns @code{nil}. +@end defun + +@defun calc-change-current-selection selection +Change the currently prepared stack element's selection to +@var{selection}, which should be @code{eq} to some sub-formula +of the stack element, or @code{nil} to unselect the formula. +The stack element's appearance in the Calc buffer is adjusted +to reflect the new selection. +@end defun + +@defun calc-find-nth-part expr n +Return the @var{n}th sub-formula of @var{expr}. This function is used +by the selection commands, and (unless @kbd{j b} has been used) treats +sums and products as flat many-element formulas. Thus if @var{expr} +is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with +@var{n} equal to four will return @samp{d}. +@end defun + +@defun calc-find-parent-formula expr part +Return the sub-formula of @var{expr} which immediately contains +@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part} +is @code{eq} to the @samp{c+1} term of @var{expr}, then this function +will return @samp{(c+1)*d}. If @var{part} turns out not to be a +sub-formula of @var{expr}, the function returns @code{nil}. If +@var{part} is @code{eq} to @var{expr}, the function returns @code{t}. +This function does not take associativity into account. +@end defun + +@defun calc-find-assoc-parent-formula expr part +This is the same as @code{calc-find-parent-formula}, except that +(unless @kbd{j b} has been used) it continues widening the selection +to contain a complete level of the formula. Given @samp{a} from +@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will +return @samp{a + b} but @code{calc-find-assoc-parent-formula} will +return the whole expression. +@end defun + +@defun calc-grow-assoc-formula expr part +This expands sub-formula @var{part} of @var{expr} to encompass a +complete level of the formula. If @var{part} and its immediate +parent are not compatible associative operators, or if @kbd{j b} +has been used, this simply returns @var{part}. +@end defun + +@defun calc-find-sub-formula expr part +This finds the immediate sub-formula of @var{expr} which contains +@var{part}. It returns an index @var{n} such that +@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}. +If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}. +If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This +function does not take associativity into account. +@end defun + +@defun calc-replace-sub-formula expr old new +This function returns a copy of formula @var{expr}, with the +sub-formula that is @code{eq} to @var{old} replaced by @var{new}. +@end defun + +@defun simplify expr +Simplify the expression @var{expr} by applying various algebraic rules. +This is what the @w{@kbd{a s}} (@code{calc-simplify}) command uses. This +always returns a copy of the expression; the structure @var{expr} points +to remains unchanged in memory. + +More precisely, here is what @code{simplify} does: The expression is +first normalized and evaluated by calling @code{normalize}. If any +@code{AlgSimpRules} have been defined, they are then applied. Then +the expression is traversed in a depth-first, bottom-up fashion; at +each level, any simplifications that can be made are made until no +further changes are possible. Once the entire formula has been +traversed in this way, it is compared with the original formula (from +before the call to @code{normalize}) and, if it has changed, +the entire procedure is repeated (starting with @code{normalize}) +until no further changes occur. Usually only two iterations are +needed:@: one to simplify the formula, and another to verify that no +further simplifications were possible. +@end defun + +@defun simplify-extended expr +Simplify the expression @var{expr}, with additional rules enabled that +help do a more thorough job, while not being entirely ``safe'' in all +circumstances. (For example, this mode will simplify @samp{sqrt(x^2)} +to @samp{x}, which is only valid when @var{x} is positive.) This is +implemented by temporarily binding the variable @code{math-living-dangerously} +to @code{t} (using a @code{let} form) and calling @code{simplify}. +Dangerous simplification rules are written to check this variable +before taking any action.@refill +@end defun + +@defun simplify-units expr +Simplify the expression @var{expr}, treating variable names as units +whenever possible. This works by binding the variable +@code{math-simplifying-units} to @code{t} while calling @code{simplify}. +@end defun + +@defmac math-defsimplify funcs body +Register a new simplification rule; this is normally called as a top-level +form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol +(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is +applied to the formulas which are calls to the specified function. Or, +@var{funcs} can be a list of such symbols; the rule applies to all +functions on the list. The @var{body} is written like the body of a +function with a single argument called @code{expr}. The body will be +executed with @code{expr} bound to a formula which is a call to one of +the functions @var{funcs}. If the function body returns @code{nil}, or +if it returns a result @code{equal} to the original @code{expr}, it is +ignored and Calc goes on to try the next simplification rule that applies. +If the function body returns something different, that new formula is +substituted for @var{expr} in the original formula.@refill + +At each point in the formula, rules are tried in the order of the +original calls to @code{math-defsimplify}; the search stops after the +first rule that makes a change. Thus later rules for that same +function will not have a chance to trigger until the next iteration +of the main @code{simplify} loop. + +Note that, since @code{defmath} is not being used here, @var{body} must +be written in true Lisp code without the conveniences that @code{defmath} +provides. If you prefer, you can have @var{body} simply call another +function (defined with @code{defmath}) which does the real work. + +The arguments of a function call will already have been simplified +before any rules for the call itself are invoked. Since a new argument +list is consed up when this happens, this means that the rule's body is +allowed to rearrange the function's arguments destructively if that is +convenient. Here is a typical example of a simplification rule: + +@smallexample +(math-defsimplify calcFunc-arcsinh + (or (and (math-looks-negp (nth 1 expr)) + (math-neg (list 'calcFunc-arcsinh + (math-neg (nth 1 expr))))) + (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh) + (or math-living-dangerously + (math-known-realp (nth 1 (nth 1 expr)))) + (nth 1 (nth 1 expr))))) +@end smallexample + +This is really a pair of rules written with one @code{math-defsimplify} +for convenience; the first replaces @samp{arcsinh(-x)} with +@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x}, +replaces @samp{arcsinh(sinh(x))} with @samp{x}.@refill +@end defmac + +@defun common-constant-factor expr +Check @var{expr} to see if it is a sum of terms all multiplied by the +same rational value. If so, return this value. If not, return @code{nil}. +For example, if called on @samp{6x + 9y + 12z}, it would return 3, since +3 is a common factor of all the terms. +@end defun + +@defun cancel-common-factor expr factor +Assuming @var{expr} is a sum with @var{factor} as a common factor, +divide each term of the sum by @var{factor}. This is done by +destructively modifying parts of @var{expr}, on the assumption that +it is being used by a simplification rule (where such things are +allowed; see above). For example, consider this built-in rule for +square roots: + +@smallexample +(math-defsimplify calcFunc-sqrt + (let ((fac (math-common-constant-factor (nth 1 expr)))) + (and fac (not (eq fac 1)) + (math-mul (math-normalize (list 'calcFunc-sqrt fac)) + (math-normalize + (list 'calcFunc-sqrt + (math-cancel-common-factor + (nth 1 expr) fac))))))) +@end smallexample +@end defun + +@defun frac-gcd a b +Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be +rational numbers. This is the fraction composed of the GCD of the +numerators of @var{a} and @var{b}, over the GCD of the denominators. +It is used by @code{common-constant-factor}. Note that the standard +@code{gcd} function uses the LCM to combine the denominators.@refill +@end defun + +@defun map-tree func expr many +Try applying Lisp function @var{func} to various sub-expressions of +@var{expr}. Initially, call @var{func} with @var{expr} itself as an +argument. If this returns an expression which is not @code{equal} to +@var{expr}, apply @var{func} again until eventually it does return +@var{expr} with no changes. Then, if @var{expr} is a function call, +recursively apply @var{func} to each of the arguments. This keeps going +until no changes occur anywhere in the expression; this final expression +is returned by @code{map-tree}. Note that, unlike simplification rules, +@var{func} functions may @emph{not} make destructive changes to +@var{expr}. If a third argument @var{many} is provided, it is an +integer which says how many times @var{func} may be applied; the +default, as described above, is infinitely many times.@refill +@end defun + +@defun compile-rewrites rules +Compile the rewrite rule set specified by @var{rules}, which should +be a formula that is either a vector or a variable name. If the latter, +the compiled rules are saved so that later @code{compile-rules} calls +for that same variable can return immediately. If there are problems +with the rules, this function calls @code{error} with a suitable +message. +@end defun + +@defun apply-rewrites expr crules heads +Apply the compiled rewrite rule set @var{crules} to the expression +@var{expr}. This will make only one rewrite and only checks at the +top level of the expression. The result @code{nil} if no rules +matched, or if the only rules that matched did not actually change +the expression. The @var{heads} argument is optional; if is given, +it should be a list of all function names that (may) appear in +@var{expr}. The rewrite compiler tags each rule with the +rarest-looking function name in the rule; if you specify @var{heads}, +@code{apply-rewrites} can use this information to narrow its search +down to just a few rules in the rule set. +@end defun + +@defun rewrite-heads expr +Compute a @var{heads} list for @var{expr} suitable for use with +@code{apply-rewrites}, as discussed above. +@end defun + +@defun rewrite expr rules many +This is an all-in-one rewrite function. It compiles the rule set +specified by @var{rules}, then uses @code{map-tree} to apply the +rules throughout @var{expr} up to @var{many} (default infinity) +times. +@end defun + +@defun match-patterns pat vec not-flag +Given a Calc vector @var{vec} and an uncompiled pattern set or +pattern set variable @var{pat}, this function returns a new vector +of all elements of @var{vec} which do (or don't, if @var{not-flag} is +non-@code{nil}) match any of the patterns in @var{pat}. +@end defun + +@defun deriv expr var value symb +Compute the derivative of @var{expr} with respect to variable @var{var} +(which may actually be any sub-expression). If @var{value} is specified, +the derivative is evaluated at the value of @var{var}; otherwise, the +derivative is left in terms of @var{var}. If the expression contains +functions for which no derivative formula is known, new derivative +functions are invented by adding primes to the names; @pxref{Calculus}. +However, if @var{symb} is non-@code{nil}, the presence of undifferentiable +functions in @var{expr} instead cancels the whole differentiation, and +@code{deriv} returns @code{nil} instead. + +Derivatives of an @var{n}-argument function can be defined by +adding a @code{math-derivative-@var{n}} property to the property list +of the symbol for the function's derivative, which will be the +function name followed by an apostrophe. The value of the property +should be a Lisp function; it is called with the same arguments as the +original function call that is being differentiated. It should return +a formula for the derivative. For example, the derivative of @code{ln} +is defined by + +@smallexample +(put 'calcFunc-ln\' 'math-derivative-1 + (function (lambda (u) (math-div 1 u)))) +@end smallexample + +The two-argument @code{log} function has two derivatives, +@smallexample +(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx + (function (lambda (x b) ... ))) +(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db + (function (lambda (x b) ... ))) +@end smallexample +@end defun + +@defun tderiv expr var value symb +Compute the total derivative of @var{expr}. This is the same as +@code{deriv}, except that variables other than @var{var} are not +assumed to be constant with respect to @var{var}. +@end defun + +@defun integ expr var low high +Compute the integral of @var{expr} with respect to @var{var}. +@xref{Calculus}, for further details. +@end defun + +@defmac math-defintegral funcs body +Define a rule for integrating a function or functions of one argument; +this macro is very similar in format to @code{math-defsimplify}. +The main difference is that here @var{body} is the body of a function +with a single argument @code{u} which is bound to the argument to the +function being integrated, not the function call itself. Also, the +variable of integration is available as @code{math-integ-var}. If +evaluation of the integral requires doing further integrals, the body +should call @samp{(math-integral @var{x})} to find the integral of +@var{x} with respect to @code{math-integ-var}; this function returns +@code{nil} if the integral could not be done. Some examples: + +@smallexample +(math-defintegral calcFunc-conj + (let ((int (math-integral u))) + (and int + (list 'calcFunc-conj int)))) + +(math-defintegral calcFunc-cos + (and (equal u math-integ-var) + (math-from-radians-2 (list 'calcFunc-sin u)))) +@end smallexample + +In the @code{cos} example, we define only the integral of @samp{cos(x) dx}, +relying on the general integration-by-substitution facility to handle +cosines of more complicated arguments. An integration rule should return +@code{nil} if it can't do the integral; if several rules are defined for +the same function, they are tried in order until one returns a non-@code{nil} +result.@refill +@end defmac + +@defmac math-defintegral-2 funcs body +Define a rule for integrating a function or functions of two arguments. +This is exactly analogous to @code{math-defintegral}, except that @var{body} +is written as the body of a function with two arguments, @var{u} and +@var{v}.@refill +@end defmac + +@defun solve-for lhs rhs var full +Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating +the variable @var{var} on the lefthand side; return the resulting righthand +side, or @code{nil} if the equation cannot be solved. The variable +@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that +the return value is a formula which does not contain @var{var}; this is +different from the user-level @code{solve} and @code{finv} functions, +which return a rearranged equation or a functional inverse, respectively. +If @var{full} is non-@code{nil}, a full solution including dummy signs +and dummy integers will be produced. User-defined inverses are provided +as properties in a manner similar to derivatives:@refill + +@smallexample +(put 'calcFunc-ln 'math-inverse + (function (lambda (x) (list 'calcFunc-exp x)))) +@end smallexample + +This function can call @samp{(math-solve-get-sign @var{x})} to create +a new arbitrary sign variable, returning @var{x} times that sign, and +@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer +variable multiplied by @var{x}. These functions simply return @var{x} +if the caller requested a non-``full'' solution. +@end defun + +@defun solve-eqn expr var full +This version of @code{solve-for} takes an expression which will +typically be an equation or inequality. (If it is not, it will be +interpreted as the equation @samp{@var{expr} = 0}.) It returns an +equation or inequality, or @code{nil} if no solution could be found. +@end defun + +@defun solve-system exprs vars full +This function solves a system of equations. Generally, @var{exprs} +and @var{vars} will be vectors of equal length. +@xref{Solving Systems of Equations}, for other options. +@end defun + +@defun expr-contains expr var +Returns a non-@code{nil} value if @var{var} occurs as a subexpression +of @var{expr}. + +This function might seem at first to be identical to +@code{calc-find-sub-formula}. The key difference is that +@code{expr-contains} uses @code{equal} to test for matches, whereas +@code{calc-find-sub-formula} uses @code{eq}. In the formula +@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not +@code{eq} to each other.@refill +@end defun + +@defun expr-contains-count expr var +Returns the number of occurrences of @var{var} as a subexpression +of @var{expr}, or @code{nil} if there are no occurrences.@refill +@end defun + +@defun expr-depends expr var +Returns true if @var{expr} refers to any variable the occurs in @var{var}. +In other words, it checks if @var{expr} and @var{var} have any variables +in common. +@end defun + +@defun expr-contains-vars expr +Return true if @var{expr} contains any variables, or @code{nil} if @var{expr} +contains only constants and functions with constant arguments. +@end defun + +@defun expr-subst expr old new +Returns a copy of @var{expr}, with all occurrences of @var{old} replaced +by @var{new}. This treats @code{lambda} forms specially with respect +to the dummy argument variables, so that the effect is always to return +@var{expr} evaluated at @var{old} = @var{new}.@refill +@end defun + +@defun multi-subst expr old new +This is like @code{expr-subst}, except that @var{old} and @var{new} +are lists of expressions to be substituted simultaneously. If one +list is shorter than the other, trailing elements of the longer list +are ignored. +@end defun + +@defun expr-weight expr +Returns the ``weight'' of @var{expr}, basically a count of the total +number of objects and function calls that appear in @var{expr}. For +``primitive'' objects, this will be one. +@end defun + +@defun expr-height expr +Returns the ``height'' of @var{expr}, which is the deepest level to +which function calls are nested. (Note that @samp{@var{a} + @var{b}} +counts as a function call.) For primitive objects, this returns zero.@refill +@end defun + +@defun polynomial-p expr var +Check if @var{expr} is a polynomial in variable (or sub-expression) +@var{var}. If so, return the degree of the polynomial, that is, the +highest power of @var{var} that appears in @var{expr}. For example, +for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns +@code{nil} unless @var{expr}, when expanded out by @kbd{a x} +(@code{calc-expand}), would consist of a sum of terms in which @var{var} +appears only raised to nonnegative integer powers. Note that if +@var{var} does not occur in @var{expr}, then @var{expr} is considered +a polynomial of degree 0.@refill +@end defun + +@defun is-polynomial expr var degree loose +Check if @var{expr} is a polynomial in variable or sub-expression +@var{var}, and, if so, return a list representation of the polynomial +where the elements of the list are coefficients of successive powers of +@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the +list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would +produce the list @samp{(1 2 1)}. The highest element of the list will +be non-zero, with the special exception that if @var{expr} is the +constant zero, the returned value will be @samp{(0)}. Return @code{nil} +if @var{expr} is not a polynomial in @var{var}. If @var{degree} is +specified, this will not consider polynomials of degree higher than that +value. This is a good precaution because otherwise an input of +@samp{(x+1)^1000} will cause a huge coefficient list to be built. If +@var{loose} is non-@code{nil}, then a looser definition of a polynomial +is used in which coefficients are no longer required not to depend on +@var{var}, but are only required not to take the form of polynomials +themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose +polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin +x))}. The result will never be @code{nil} in loose mode, since any +expression can be interpreted as a ``constant'' loose polynomial.@refill +@end defun + +@defun polynomial-base expr pred +Check if @var{expr} is a polynomial in any variable that occurs in it; +if so, return that variable. (If @var{expr} is a multivariate polynomial, +this chooses one variable arbitrarily.) If @var{pred} is specified, it should +be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})}, +and which should return true if @code{mpb-top-expr} (a global name for +the original @var{expr}) is a suitable polynomial in @var{subexpr}. +The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})}; +you can use @var{pred} to specify additional conditions. Or, you could +have @var{pred} build up a list of every suitable @var{subexpr} that +is found.@refill +@end defun + +@defun poly-simplify poly +Simplify polynomial coefficient list @var{poly} by (destructively) +clipping off trailing zeros. +@end defun + +@defun poly-mix a ac b bc +Mix two polynomial lists @var{a} and @var{b} (in the form returned by +@code{is-polynomial}) in a linear combination with coefficient expressions +@var{ac} and @var{bc}. The result is a (not necessarily simplified) +polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}.@refill +@end defun + +@defun poly-mul a b +Multiply two polynomial coefficient lists @var{a} and @var{b}. The +result will be in simplified form if the inputs were simplified. +@end defun + +@defun build-polynomial-expr poly var +Construct a Calc formula which represents the polynomial coefficient +list @var{poly} applied to variable @var{var}. The @kbd{a c} +(@code{calc-collect}) command uses @code{is-polynomial} to turn an +expression into a coefficient list, then @code{build-polynomial-expr} +to turn the list back into an expression in regular form.@refill +@end defun + +@defun check-unit-name var +Check if @var{var} is a variable which can be interpreted as a unit +name. If so, return the units table entry for that unit. This +will be a list whose first element is the unit name (not counting +prefix characters) as a symbol and whose second element is the +Calc expression which defines the unit. (Refer to the Calc sources +for details on the remaining elements of this list.) If @var{var} +is not a variable or is not a unit name, return @code{nil}. +@end defun + +@defun units-in-expr-p expr sub-exprs +Return true if @var{expr} contains any variables which can be +interpreted as units. If @var{sub-exprs} is @code{t}, the entire +expression is searched. If @var{sub-exprs} is @code{nil}, this +checks whether @var{expr} is directly a units expression.@refill +@end defun + +@defun single-units-in-expr-p expr +Check whether @var{expr} contains exactly one units variable. If so, +return the units table entry for the variable. If @var{expr} does +not contain any units, return @code{nil}. If @var{expr} contains +two or more units, return the symbol @code{wrong}. +@end defun + +@defun to-standard-units expr which +Convert units expression @var{expr} to base units. If @var{which} +is @code{nil}, use Calc's native base units. Otherwise, @var{which} +can specify a units system, which is a list of two-element lists, +where the first element is a Calc base symbol name and the second +is an expression to substitute for it.@refill +@end defun + +@defun remove-units expr +Return a copy of @var{expr} with all units variables replaced by ones. +This expression is generally normalized before use. +@end defun + +@defun extract-units expr +Return a copy of @var{expr} with everything but units variables replaced +by ones. +@end defun + +@node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals +@subsubsection I/O and Formatting Functions + +@noindent +The functions described here are responsible for parsing and formatting +Calc numbers and formulas. + +@defun calc-eval str sep arg1 arg2 @dots{} +This is the simplest interface to the Calculator from another Lisp program. +@xref{Calling Calc from Your Programs}. +@end defun + +@defun read-number str +If string @var{str} contains a valid Calc number, either integer, +fraction, float, or HMS form, this function parses and returns that +number. Otherwise, it returns @code{nil}. +@end defun + +@defun read-expr str +Read an algebraic expression from string @var{str}. If @var{str} does +not have the form of a valid expression, return a list of the form +@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index +into @var{str} of the general location of the error, and @var{msg} is +a string describing the problem.@refill +@end defun + +@defun read-exprs str +Read a list of expressions separated by commas, and return it as a +Lisp list. If an error occurs in any expressions, an error list as +shown above is returned instead. +@end defun + +@defun calc-do-alg-entry initial prompt no-norm +Read an algebraic formula or formulas using the minibuffer. All +conventions of regular algebraic entry are observed. The return value +is a list of Calc formulas; there will be more than one if the user +entered a list of values separated by commas. The result is @code{nil} +if the user presses Return with a blank line. If @var{initial} is +given, it is a string which the minibuffer will initially contain. +If @var{prompt} is given, it is the prompt string to use; the default +is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will +be returned exactly as parsed; otherwise, they will be passed through +@code{calc-normalize} first.@refill + +To support the use of @kbd{$} characters in the algebraic entry, use +@code{let} to bind @code{calc-dollar-values} to a list of the values +to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind +@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used} +will have been changed to the highest number of consecutive @kbd{$}s +that actually appeared in the input.@refill +@end defun + +@defun format-number a +Convert the real or complex number or HMS form @var{a} to string form. +@end defun + +@defun format-flat-expr a prec +Convert the arbitrary Calc number or formula @var{a} to string form, +in the style used by the trail buffer and the @code{calc-edit} command. +This is a simple format designed +mostly to guarantee the string is of a form that can be re-parsed by +@code{read-expr}. Most formatting modes, such as digit grouping, +complex number format, and point character, are ignored to ensure the +result will be re-readable. The @var{prec} parameter is normally 0; if +you pass a large integer like 1000 instead, the expression will be +surrounded by parentheses unless it is a plain number or variable name.@refill +@end defun + +@defun format-nice-expr a width +This is like @code{format-flat-expr} (with @var{prec} equal to 0), +except that newlines will be inserted to keep lines down to the +specified @var{width}, and vectors that look like matrices or rewrite +rules are written in a pseudo-matrix format. The @code{calc-edit} +command uses this when only one stack entry is being edited. +@end defun + +@defun format-value a width +Convert the Calc number or formula @var{a} to string form, using the +format seen in the stack buffer. Beware the the string returned may +not be re-readable by @code{read-expr}, for example, because of digit +grouping. Multi-line objects like matrices produce strings that +contain newline characters to separate the lines. The @var{w} +parameter, if given, is the target window size for which to format +the expressions. If @var{w} is omitted, the width of the Calculator +window is used.@refill +@end defun + +@defun compose-expr a prec +Format the Calc number or formula @var{a} according to the current +language mode, returning a ``composition.'' To learn about the +structure of compositions, see the comments in the Calc source code. +You can specify the format of a given type of function call by putting +a @code{math-compose-@var{lang}} property on the function's symbol, +whose value is a Lisp function that takes @var{a} and @var{prec} as +arguments and returns a composition. Here @var{lang} is a language +mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal}, +@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}. +In Big mode, Calc actually tries @code{math-compose-big} first, then +tries @code{math-compose-normal}. If this property does not exist, +or if the function returns @code{nil}, the function is written in the +normal function-call notation for that language. +@end defun + +@defun composition-to-string c w +Convert a composition structure returned by @code{compose-expr} into +a string. Multi-line compositions convert to strings containing +newline characters. The target window size is given by @var{w}. +The @code{format-value} function basically calls @code{compose-expr} +followed by @code{composition-to-string}. +@end defun + +@defun comp-width c +Compute the width in characters of composition @var{c}. +@end defun + +@defun comp-height c +Compute the height in lines of composition @var{c}. +@end defun + +@defun comp-ascent c +Compute the portion of the height of composition @var{c} which is on or +above the baseline. For a one-line composition, this will be one. +@end defun + +@defun comp-descent c +Compute the portion of the height of composition @var{c} which is below +the baseline. For a one-line composition, this will be zero. +@end defun + +@defun comp-first-char c +If composition @var{c} is a ``flat'' composition, return the first +(leftmost) character of the composition as an integer. Otherwise, +return @code{nil}.@refill +@end defun + +@defun comp-last-char c +If composition @var{c} is a ``flat'' composition, return the last +(rightmost) character, otherwise return @code{nil}. +@end defun + +@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals +@comment @subsubsection Lisp Variables +@comment +@comment @noindent +@comment (This section is currently unfinished.) + +@node Hooks, , Formatting Lisp Functions, Internals +@subsubsection Hooks + +@noindent +Hooks are variables which contain Lisp functions (or lists of functions) +which are called at various times. Calc defines a number of hooks +that help you to customize it in various ways. Calc uses the Lisp +function @code{run-hooks} to invoke the hooks shown below. Several +other customization-related variables are also described here. + +@defvar calc-load-hook +This hook is called at the end of @file{calc.el}, after the file has +been loaded, before any functions in it have been called, but after +@code{calc-mode-map} and similar variables have been set up. +@end defvar + +@defvar calc-ext-load-hook +This hook is called at the end of @file{calc-ext.el}. +@end defvar + +@defvar calc-start-hook +This hook is called as the last step in a @kbd{M-x calc} command. +At this point, the Calc buffer has been created and initialized if +necessary, the Calc window and trail window have been created, +and the ``Welcome to Calc'' message has been displayed. +@end defvar + +@defvar calc-mode-hook +This hook is called when the Calc buffer is being created. Usually +this will only happen once per Emacs session. The hook is called +after Emacs has switched to the new buffer, the mode-settings file +has been read if necessary, and all other buffer-local variables +have been set up. After this hook returns, Calc will perform a +@code{calc-refresh} operation, set up the mode line display, then +evaluate any deferred @code{calc-define} properties that have not +been evaluated yet. +@end defvar + +@defvar calc-trail-mode-hook +This hook is called when the Calc Trail buffer is being created. +It is called as the very last step of setting up the Trail buffer. +Like @code{calc-mode-hook}, this will normally happen only once +per Emacs session. +@end defvar + +@defvar calc-end-hook +This hook is called by @code{calc-quit}, generally because the user +presses @kbd{q} or @kbd{M-# c} while in Calc. The Calc buffer will +be the current buffer. The hook is called as the very first +step, before the Calc window is destroyed. +@end defvar + +@defvar calc-window-hook +If this hook exists, it is called to create the Calc window. +Upon return, this new Calc window should be the current window. +(The Calc buffer will already be the current buffer when the +hook is called.) If the hook is not defined, Calc will +generally use @code{split-window}, @code{set-window-buffer}, +and @code{select-window} to create the Calc window. +@end defvar + +@defvar calc-trail-window-hook +If this hook exists, it is called to create the Calc Trail window. +The variable @code{calc-trail-buffer} will contain the buffer +which the window should use. Unlike @code{calc-window-hook}, +this hook must @emph{not} switch into the new window. +@end defvar + +@defvar calc-edit-mode-hook +This hook is called by @code{calc-edit} (and the other ``edit'' +commands) when the temporary editing buffer is being created. +The buffer will have been selected and set up to be in +@code{calc-edit-mode}, but will not yet have been filled with +text. (In fact it may still have leftover text from a previous +@code{calc-edit} command.) +@end defvar + +@defvar calc-mode-save-hook +This hook is called by the @code{calc-save-modes} command, +after Calc's own mode features have been inserted into the +@file{.emacs} buffer and just before the ``End of mode settings'' +message is inserted. +@end defvar + +@defvar calc-reset-hook +This hook is called after @kbd{M-# 0} (@code{calc-reset}) has +reset all modes. The Calc buffer will be the current buffer. +@end defvar + +@defvar calc-other-modes +This variable contains a list of strings. The strings are +concatenated at the end of the modes portion of the Calc +mode line (after standard modes such as ``Deg'', ``Inv'' and +``Hyp''). Each string should be a short, single word followed +by a space. The variable is @code{nil} by default. +@end defvar + +@defvar calc-mode-map +This is the keymap that is used by Calc mode. The best time +to adjust it is probably in a @code{calc-mode-hook}. If the +Calc extensions package (@file{calc-ext.el}) has not yet been +loaded, many of these keys will be bound to @code{calc-missing-key}, +which is a command that loads the extensions package and +``retypes'' the key. If your @code{calc-mode-hook} rebinds +one of these keys, it will probably be overridden when the +extensions are loaded. +@end defvar + +@defvar calc-digit-map +This is the keymap that is used during numeric entry. Numeric +entry uses the minibuffer, but this map binds every non-numeric +key to @code{calcDigit-nondigit} which generally calls +@code{exit-minibuffer} and ``retypes'' the key. +@end defvar + +@defvar calc-alg-ent-map +This is the keymap that is used during algebraic entry. This is +mostly a copy of @code{minibuffer-local-map}. +@end defvar + +@defvar calc-store-var-map +This is the keymap that is used during entry of variable names for +commands like @code{calc-store} and @code{calc-recall}. This is +mostly a copy of @code{minibuffer-local-completion-map}. +@end defvar + +@defvar calc-edit-mode-map +This is the (sparse) keymap used by @code{calc-edit} and other +temporary editing commands. It binds @key{RET}, @key{LFD}, +and @kbd{C-c C-c} to @code{calc-edit-finish}. +@end defvar + +@defvar calc-mode-var-list +This is a list of variables which are saved by @code{calc-save-modes}. +Each entry is a list of two items, the variable (as a Lisp symbol) +and its default value. When modes are being saved, each variable +is compared with its default value (using @code{equal}) and any +non-default variables are written out. +@end defvar + +@defvar calc-local-var-list +This is a list of variables which should be buffer-local to the +Calc buffer. Each entry is a variable name (as a Lisp symbol). +These variables also have their default values manipulated by +the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}. +Since @code{calc-mode-hook} is called after this list has been +used the first time, your hook should add a variable to the +list and also call @code{make-local-variable} itself. +@end defvar + +@node Installation, Reporting Bugs, Programming, Top +@appendix Installation + +@noindent +Calc 2.02 comes as a set of GNU Emacs Lisp files, with names like +@file{calc.el} and @file{calc-ext.el}, and also as a @file{calc.texinfo} +file which can be used to generate both on-line and printed +documentation.@refill + +To install Calc, just follow these simple steps. If you want more +information, each step is discussed at length in the sections below. + +@enumerate +@item +Change (@samp{cd}) to the Calc ``home'' directory. This directory was +created when you unbundled the Calc @file{.tar} or @file{.shar} file. + +@item +Type @samp{make} to install Calc privately for your own use, or type +@samp{make install} to install Calc system-wide. This will compile all +the Calc component files, modify your @file{.emacs} or the system-wide +@file{lisp/default} file to install Calc as appropriate, and format +the on-line Calc manual. + +@noindent +Both variants are shorthand for the following three steps: +@itemize @bullet +@item +@pindex calc-compile +@samp{make compile} to run the byte-compiler. + +@item +@samp{make private} or @samp{make public}, corresponding to +@samp{make} and @samp{make install}, respectively. (If @samp{make public} +fails because your system doesn't already have a @file{default} or +@file{default.el} file, use Emacs or the Unix @code{touch} command +to create a zero-sized one first.) + +@item +@samp{make info} to format the on-line Calc manual. This first tries +to use the @file{makeinfo} program; if that program is not present, it +uses the Emacs @code{texinfo-format-buffer} command instead. +@end itemize +@noindent +The Unix @code{make} utility looks in the file @file{Makefile} in the +current directory to see what Unix commands correspond to the various +``targets'' like @code{install} or @code{public}. If your system +doesn't have @code{make}, you will have to examine the @file{Makefile} +and type in the corresponding commands by hand. + +@item +If you ever move Calc to a new home directory, just give the +@samp{make private} or @samp{make public} command again in the new +directory. + +@item +Test your installation as described at the end of these instructions. + +@item +(Optional.) To print a hardcopy of the Calc manual (over 500 pages) +or just the Calc Summary (about 20 pages), follow the instructions under +``Printed Documentation'' below. +@end enumerate + +@noindent +Calc is now installed and ready to go! +@example + +@end example +@iftex +@node Installation 2, foo, bar, spam +@end iftex + +@appendixsec Upgrading from Calc 1.07 + +@noindent +If you have Calc version 1.07 or earlier, you will find that Calc 2.00 +is organized quite differently. For one, Calc 2.00 is now distributed +already split into many parts; formerly this was done as part of the +installation procedure. Also, some new functions must be autoloaded +and the @kbd{M-#} key must be bound to @code{calc-dispatch} instead +of to @code{calc}. + +The easiest way to upgrade is to delete your old Calc files and then +install Calc 2.00 from scratch using the above instructions. You should +then go into your @file{.emacs} or @file{default} file and remove the +old @code{autoload} and @code{global-set-key} commands for Calc, since +@samp{make public}/@samp{make private} has added new, better ones. + +See the @file{README} and @file{README.prev} files in the Calc +distribution for more information about what has changed since version +1.07. (@file{README.prev} describes changes before 2.00, and is +present only in the FTP and tape versions of the distribution.) + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec The @samp{make public} Command + +@noindent +If you are not the regular Emacs administrator on your system, your +account may not be allowed to execute the @samp{make public} command, +since the system-wide @file{default} file may be write-protected. +If this is the case, you will have to ask your Emacs installer to +execute this command. (Just @code{cd} to the Calc home directory +and type @samp{make public}.) + +The @samp{make private} command adds exactly the same set of commands +to your @file{.emacs} file as @samp{make public} adds to @file{default}. +If your Emacs installer is concerned about typing this command out of +the blue, you can ask her/him instead to copy the necessary text from +your @file{.emacs} file. (It will be marked by a comment that says +``Commands added by @code{calc-private-autoloads} on (date and time).'') + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Compilation + +@noindent +Calc is written in a way that maximizes performance when its code has been +byte-compiled; a side effect is that performance is seriously degraded if +it @emph{isn't} compiled. Thus, it is essential to compile the Calculator +before trying to use it. The function @samp{calc-compile} in the file +@file{calc-maint.el} runs the Emacs byte-compiler on all the Calc source +files. (Specifically, it runs @kbd{M-x byte-compile-file} on all files +in the current directory with names of the form @file{calc*.el}, and also +on the file @file{macedit.el}.) + +If @code{calc-compile} finds that certain files have already been +compiled and have not been changed since, then it will not bother to +recompile those files. + +The @code{calc-compile} command also pre-builds certain tables, such as +the units table (@pxref{The Units Table}) and the built-in rewrite rules +(@pxref{Rearranging with Selections}) which Calc would otherwise +need to rebuild every time those features were used. + +The @samp{make compile} shell command is simply a convenient way to +start an Emacs and give it a @code{calc-compile} command. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Auto-loading + +@noindent +To teach Emacs how to load in Calc when you type @kbd{M-#} for the +first time, add these lines to your @file{.emacs} file (if you are +installing Calc just for your own use), or the system's @file{lisp/default} +file (if you are installing Calc publicly). The @samp{make private} +and @samp{make public} commands, respectively, take care of this. +(Note that @samp{make} runs @samp{make private}, and @samp{make install} +runs @samp{make public}.) + +@smallexample +(autoload 'calc-dispatch "calc" "Calculator Options" t) +(autoload 'full-calc "calc" "Full-screen Calculator" t) +(autoload 'full-calc-keypad "calc" "Full-screen X Calculator" t) +(autoload 'calc-eval "calc" "Use Calculator from Lisp") +(autoload 'defmath "calc" nil t t) +(autoload 'calc "calc" "Calculator Mode" t) +(autoload 'quick-calc "calc" "Quick Calculator" t) +(autoload 'calc-keypad "calc" "X windows Calculator" t) +(autoload 'calc-embedded "calc" "Use Calc from any buffer" t) +(autoload 'calc-embedded-activate "calc" "Activate =>'s in buffer" t) +(autoload 'calc-grab-region "calc" "Grab region of Calc data" t) +(autoload 'calc-grab-rectangle "calc" "Grab rectangle of data" t) +@end smallexample + +@vindex load-path +Unless you have installed the Calc files in Emacs' main @file{lisp/} +directory, you will also have to add a command that looks like the +following to tell Emacs where to find them. In this example, we +have put the files in directory @file{/usr/gnu/src/calc-2.00}. + +@smallexample +(setq load-path (append load-path (list "/usr/gnu/src/calc-2.00"))) +@end smallexample + +@noindent +The @samp{make public} and @samp{make private} commands also do this +(they use the then-current directory as the name to add to the path). +If you move Calc to a new location, just repeat the @samp{make public} +or @samp{make private} command to have this new location added to +the @code{load-path}.@refill + +The @code{autoload} command for @code{calc-dispatch} is what loads +@file{calc.elc} when you type @kbd{M-#}. It is the only @code{autoload} +that is absolutely necessary for Calc to work. The others are for +commands and features that you may wish to use before typing +@kbd{M-#} for the first time. In particular, @code{full-calc} and +@code{full-calc-keypad} are autoloaded to support ``standalone'' +operation (@pxref{Standalone Operation}), @code{calc-eval} and +@code{defmath} are autoloaded to allow other Emacs Lisp programs to +use Calc facilities (@pxref{Calling Calc from Your Programs}), and +@code{calc-embedded-activate} is autoloaded because some Embedded +Mode files may call it as soon as they are read into Emacs +(@pxref{Assignments in Embedded Mode}). + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Finding Component Files + +@noindent +There is no need to write @code{autoload} commands that point to all +the various Calc component files like @file{calc-misc.elc} and +@file{calc-alg.elc}. The main file, @file{calc.elc}, contains all +the necessary @code{autoload} commands for these files. + +(Actually, to conserve space @file{calc.elc} only autoloads a few of +the component files, plus @file{calc-ext.elc}, which in turn autoloads +the rest of the components. This allows Calc to load a little faster +in the beginning, but the net effect is the same.) + +This autoloading mechanism assumes that all the component files can +be found on the @code{load-path}. The @samp{make public} and +@samp{make private} commands take care of this, but Calc has a few +other strategies in case you have installed it in an unusual way. + +If, when Calc is loaded, it is unable to find its components on the +@code{load-path} it is given, it checks the file name in the original +@code{autoload} command for @code{calc-dispatch}. If that name +included directory information, Calc adds that directory to the +@code{load-path}: + +@example +(autoload 'calc-dispatch "calc-2.00/calc" "Calculator" t) +@end example + +@noindent +Suppose the directory @file{/usr/gnu/src/emacs/lisp} is on the path, and +the above @code{autoload} allows Emacs to find Calc under the name +@file{/usr/gnu/src/emacs/lisp/calc-2.00/calc.elc}. Then when Calc +starts up it will add @file{/usr/gnu/src/emacs/lisp/calc-2.00} +to the path so that it will later be able to find its component files. + +@vindex calc-autoload-directory +If the above strategy does not locate the component files, Calc +examines the variable @code{calc-autoload-directory}. This is +initially @code{nil}, but you can store the name of Calc's home +directory in it as a sure-fire way of getting Calc to find its +components. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Merging Source Files + +@noindent +If the @code{autoload} mechanism is not managing to load each part +of Calc when it is needed, you can concatenate all the @file{.el} +files into one big file. The order should be @file{calc.el}, then +@file{calc-ext.el}, then all the other files in any order. +Byte-compile the resulting big file. This merged Calculator ought +to work just like Calc normally does, though it will be @emph{substantially} +slower to load.@refill + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Key Bindings + +@noindent +Calc is normally bound to the @kbd{M-#} key. To set up this key +binding, include the following command in your @file{.emacs} or +@file{lisp/default} file. (This is done automatically by +@samp{make private} or @samp{make public}, respectively.) + +@smallexample +(global-set-key "\e#" 'calc-dispatch) +@end smallexample + +Note that @code{calc-dispatch} actually works as a prefix for various +two-key sequences. If you have a convenient unused function key on +your keyboard, you may wish to bind @code{calc-dispatch} to that as +well. You may even wish to bind other specific Calc functions like +@code{calc} or @code{quick-calc} to other handy function keys. + +Even if you bind @code{calc-dispatch} to other keys, it is best to +bind it to @kbd{M-#} as well if you possibly can: There are references +to @kbd{M-#} all throughout the Calc manual which would confuse novice +users if they didn't work as advertised. + +@vindex calc-scan-for-dels +Another key binding issue is the @key{DEL} key. Some installations +use a different key (such as backspace) for this purpose. Calc +normally scans the entire keymap and maps all keys defined like +@key{DEL} to the @code{calc-pop} command. However, this may be +slow. You can set the variable @code{calc-scan-for-dels} to +@code{nil} to cause only the actual @key{DEL} key to be mapped to +@code{calc-pop}; this will speed loading of Calc. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec The @file{macedit} Package + +@noindent +The file @file{macedit.el} contains another useful Emacs extension +called @code{edit-kbd-macro}. It allows you to edit a keyboard macro +in human-readable form. The @kbd{Z E} command in Calc knows how to +use it to edit user commands that have been defined by keyboard macros. +To autoload it, you will want to include the commands, + +@smallexample +(autoload 'edit-kbd-macro "macedit" "Edit Keyboard Macro" t) +(autoload 'edit-last-kbd-macro "macedit" "Edit Keyboard Macro" t) +(autoload 'read-kbd-macro "macedit" "Read Keyboard Macro" t) +@end smallexample + +@noindent +The @samp{make public} and @samp{make private} commands do this. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec The GNUPLOT Program + +@noindent +Calc's graphing commands use the GNUPLOT program. If you have GNUPLOT +but you must type some command other than @file{gnuplot} to get it, +you should add a command to set the Lisp variable @code{calc-gnuplot-name} +to the appropriate file name. You may also need to change the variables +@code{calc-gnuplot-plot-command} and @code{calc-gnuplot-print-command} in +order to get correct displays and hardcopies, respectively, of your +plots.@refill + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec On-Line Documentation + +@noindent +The documentation for Calc (this manual) comes in a file called +@file{calc.texinfo}. To format this for use as an on-line manual, +type @samp{make info} (to use the @code{makeinfo} program), or +@samp{make texinfo} (to use the @code{texinfmt.el} program which runs +inside of Emacs). The former command is recommended if it works +on your system; it is faster and produces nicer-looking output. + +The @code{makeinfo} program will report inconsistencies involving +the nodes ``Copying'' and ``Interactive Tutorial''; these +messages should be ignored. + +The result will be a collection of files whose names begin with +@file{calc.info}. You may wish to add a reference to the first +of these, @file{calc.info} itself, to your Info system's @file{dir} +file. (This is optional since the @kbd{M-# i} command can access +@file{calc.info} whether or not it appears in the @file{dir} file.) + +@vindex calc-info-filename +There is a Lisp variable called @code{calc-info-filename} which holds +the name of the Info file containing Calc's on-line documentation. +Its default value is @code{"calc.info"}, which will work correctly if +the Info files are stored in Emacs' main @file{info/} directory, or if +they are in any of the directories listed in the @code{load-path}. If +you keep them elsewhere, you will want to put a command of the form, + +@smallexample +(setq calc-info-filename ".../calc.info") +@end smallexample + +@noindent +in your @file{.emacs} or @file{lisp/default} file, where @file{...} +represents the directory containing the Info files. This will not +be necessary if you follow the normal installation procedures. + +The @samp{make info} and @samp{make texinfo} commands compare the dates +on the files @file{calc.texinfo} and @file{calc.info}, and run the +appropriate program only if the latter file is older or does not exist. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Printed Documentation + +@noindent +Because the Calc manual is so large, you should only make a printed +copy if you really need it. To print the manual, you will need the +@TeX{} typesetting program (this is a free program by Donald Knuth +at Stanford University) as well as the @file{texindex} program and +@file{texinfo.tex} file, both of which can be obtained from the FSF +as part of the @code{texinfo2} package.@refill + +To print the Calc manual in one huge 550 page tome, type @samp{make tex}. +This will take care of running the manual through @TeX{} twice so that +references to later parts of the manual will have correct page numbers. +(Don't worry if you get some ``overfull box'' warnings.) + +The result will be a device-independent output file called +@file{calc.dvi}, which you must print in whatever way is right +for your system. On many systems, the command is + +@example +lpr -d calc.dvi +@end example + +@cindex Marginal notes, adjusting +Marginal notes for each function and key sequence normally alternate +between the left and right sides of the page, which is correct if the +manual is going to be bound as double-sided pages. Near the top of +the file @file{calc.texinfo} you will find alternate definitions of +the @code{\bumpoddpages} macro that put the marginal notes always on +the same side, best if you plan to be binding single-sided pages. + +@pindex calc-split-manual +Some people find the Calc manual to be too large to handle easily. +In fact, some versions of @TeX{} have too little memory to print it. +So Calc includes a @code{calc-split-manual} command that splits +@file{calc.texinfo} into two volumes, the Calc Tutorial and the +Calc Reference. The easiest way to use it is to type @samp{make tex2} +instead of @samp{make tex}. The result will be two smaller files, +@file{calctut.dvi} and @file{calcref.dvi}. The former contains the +tutorial part of the manual; the latter contains the reference part. +Both volumes include copies of the ``Getting Started'' chapter and +licensing information. + +To save disk space, you may wish to delete @file{calctut.*} and +@file{calcref.*} after you're done. Don't delete @file{calc.texinfo}, +because you will need it to install future patches to Calc. +The @samp{make tex2} command takes care of all of this for you. + +The @samp{make textut} command formats only the Calc Tutorial volume, +producing @file{calctut.dvi} but not @file{calcref.dvi}. Likewise, +@samp{make texref} formats only the Calc Reference volume. + +@pindex calc-split-summary +Finally, there is a @code{calc-split-summary} command that splits off +just the Calc Summary appendix suitable for printing by itself. +Type @samp{make summary} instead of @samp{make tex}. The resulting +@file{calcsum.dvi} file will print in less than 20 pages. If the +Key Index file @file{calc.ky} is present, left over from a previous +@samp{make tex} command, then @samp{make summary} will insert a +column of page numbers into the summary using that information. + +The @samp{make isummary} command is like @samp{make summary}, but it +prints a summary that is designed to be substituted into the regular +manual. (The two summaries will be identical except for the +additional column of page numbers.) To make a complete manual, run +@samp{make tex} and @samp{make isummary}, print the two resulting +@file{.dvi} files, then discard the Summary pages that came from +@file{calc.dvi} and insert the ones from @file{calcsum.dvi} in their +place. Also, remember that the table of contents prints at the end +of the manual but should generally be moved to the front (after the +title and copyright pages). + +If you don't have @TeX{}, you can print the summary as a plain text +file by going to the ``Summary'' node in Calc's Info file, then +typing @kbd{M-x print-buffer} (@pxref{Summary}). + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Settings File + +@noindent +@vindex calc-settings-file +Another variable you might want to set is @code{calc-settings-file}, +which holds the file name in which commands like @kbd{m m} and @kbd{Z P} +store ``permanent'' definitions. The default value for this variable +is @code{"~/.emacs"}. If @code{calc-settings-file} does not contain +@code{".emacs"} as a substring, and if the variable +@code{calc-loaded-settings-file} is @code{nil}, then Calc will +automatically load your settings file (if it exists) the first time +Calc is invoked.@refill + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Testing the Installation + +@noindent +To test your installation of Calc, start a new Emacs and type @kbd{M-# c} +to make sure the autoloads and key bindings work. Type @kbd{M-# i} +to make sure Calc can find its Info documentation. Press @kbd{q} to +exit the Info system and @kbd{M-# c} to re-enter the Calculator. +Type @kbd{20 S} to compute the sine of 20 degrees; this will test the +autoloading of the extensions modules. The result should be +0.342020143326. Finally, press @kbd{M-# c} again to make sure the +Calculator can exit. + +You may also wish to test the GNUPLOT interface; to plot a sine wave, +type @kbd{' [0 ..@: 360], sin(x) RET g f}. Type @kbd{g q} when you +are done viewing the plot. + +Calc is now ready to use. If you wish to go through the Calc Tutorial, +press @kbd{M-# t} to begin. +@example + +@end example + +@noindent +(The above text is included in both the Calc documentation and the +file INSTALL in the Calc distribution directory.) + +@node Reporting Bugs, Summary, Installation, Top +@appendix Reporting Bugs + +@noindent +If you find a bug in Calc, send e-mail to Dave Gillespie, + +@example +daveg@@synaptics.com @r{or} +daveg@@csvax.cs.caltech.edu +@end example + +@noindent +While I cannot guarantee that I will have time to work on your bug, +I do try to fix bugs quickly whenever I can. + +You can obtain a current version of Calc from anonymous FTP on +@samp{csvax.cs.caltech.edu} in @samp{pub/calc-@var{version}.tar.Z}. +Calc is also available on the GNU machine, @samp{prep.ai.mit.edu}. +Patches are posted to the @samp{comp.sources.misc} Usenet group, +and are also available on @code{csvax}. + +There is an automatic @kbd{M-x report-calc-bug} command which helps +you to report bugs. This command prompts you for a brief subject +line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to +send your mail. Make sure your subject line indicates that you are +reporting a Calc bug; this command sends mail to my regular mailbox. + +If you have suggestions for additional features for Calc, I would +love to hear them. Some have dared to suggest that Calc is already +top-heavy with features; I really don't see what they're talking +about, so, if you have ideas, send them right in. (I may even have +time to implement them!) + +At the front of the source file, @file{calc.el}, is a list of ideas for +future work which I have not had time to do. If any enthusiastic souls +wish to take it upon themselves to work on these, I would be delighted. +Please let me know if you plan to contribute to Calc so I can coordinate +your efforts with mine and those of others. I will do my best to help +you in whatever way I can. + +@c [summary] +@node Summary, Key Index, Reporting Bugs, Top +@appendix Calc Summary + +@noindent +This section includes a complete list of Calc 2.02 keystroke commands. +Each line lists the stack entries used by the command (top-of-stack +last), the keystrokes themselves, the prompts asked by the command, +and the result of the command (also with top-of-stack last). +The result is expressed using the equivalent algebraic function. +Commands which put no results on the stack show the full @kbd{M-x} +command name in that position. Numbers preceding the result or +command name refer to notes at the end. + +Algebraic functions and @kbd{M-x} commands that don't have corresponding +keystrokes are not listed in this summary. +@xref{Command Index}. @xref{Function Index}. + +@iftex +@begingroup +@tex +\vskip-2\baselineskip \null +\gdef\sumrow#1{\sumrowx#1\relax}% +\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{% +\leavevmode% +\hbox to5em{\indsl\hss#1}% +\hbox to5em{\ninett#2\hss}% +\hbox to4em{\indsl#3\hss}% +\hbox to5em{\indrm\hss#4}% +\thinspace% +{\ninett#5}% +{\indsl#6}% +}% +\gdef\sumlpar{{\indrm(}}% +\gdef\sumrpar{{\indrm)}}% +\gdef\sumcomma{{\indrm,\thinspace}}% +\gdef\sumexcl{{\indrm!}}% +\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}% +\gdef\minus#1{{\tt-}}% +@end tex +@let@:=@sumsep +@let@r=@sumrow +@catcode`@(=@active @let(=@sumlpar +@catcode`@)=@active @let)=@sumrpar +@catcode`@,=@active @let,=@sumcomma +@catcode`@!=@active @let!=@sumexcl +@end iftex +@format +@iftex +@advance@baselineskip-2.5pt +@let@tt@ninett +@let@c@sumbreak +@end iftex +@r{ @: M-# a @: @: 33 @:calc-embedded-activate@:} +@r{ @: M-# b @: @: @:calc-big-or-small@:} +@r{ @: M-# c @: @: @:calc@:} +@r{ @: M-# d @: @: @:calc-embedded-duplicate@:} +@r{ @: M-# e @: @: 34 @:calc-embedded@:} +@r{ @: M-# f @:formula @: @:calc-embedded-new-formula@:} +@r{ @: M-# g @: @: 35 @:calc-grab-region@:} +@r{ @: M-# i @: @: @:calc-info@:} +@r{ @: M-# j @: @: @:calc-embedded-select@:} +@r{ @: M-# k @: @: @:calc-keypad@:} +@r{ @: M-# l @: @: @:calc-load-everything@:} +@r{ @: M-# m @: @: @:read-kbd-macro@:} +@r{ @: M-# n @: @: 4 @:calc-embedded-next@:} +@r{ @: M-# o @: @: @:calc-other-window@:} +@r{ @: M-# p @: @: 4 @:calc-embedded-previous@:} +@r{ @: M-# q @:formula @: @:quick-calc@:} +@r{ @: M-# r @: @: 36 @:calc-grab-rectangle@:} +@r{ @: M-# s @: @: @:calc-info-summary@:} +@r{ @: M-# t @: @: @:calc-tutorial@:} +@r{ @: M-# u @: @: @:calc-embedded-update@:} +@r{ @: M-# w @: @: @:calc-embedded-word@:} +@r{ @: M-# x @: @: @:calc-quit@:} +@r{ @: M-# y @: @:1,28,49 @:calc-copy-to-buffer@:} +@r{ @: M-# z @: @: @:calc-user-invocation@:} +@r{ @: M-# : @: @: 36 @:calc-grab-sum-down@:} +@r{ @: M-# _ @: @: 36 @:calc-grab-sum-across@:} +@r{ @: M-# ` @:editing @: 30 @:calc-embedded-edit@:} +@r{ @: M-# 0 @:(zero) @: @:calc-reset@:} + +@c +@r{ @: 0-9 @:number @: @:@:number} +@r{ @: . @:number @: @:@:0.number} +@r{ @: _ @:number @: @:-@:number} +@r{ @: e @:number @: @:@:1e number} +@r{ @: # @:number @: @:@:current-radix@t{#}number} +@r{ @: P @:(in number) @: @:+/-@:} +@r{ @: M @:(in number) @: @:mod@:} +@r{ @: @@ ' " @: (in number)@: @:@:HMS form} +@r{ @: h m s @: (in number)@: @:@:HMS form} + +@c +@r{ @: ' @:formula @: 37,46 @:@:formula} +@r{ @: $ @:formula @: 37,46 @:$@:formula} +@r{ @: " @:string @: 37,46 @:@:string} + +@c +@r{ a b@: + @: @: 2 @:add@:(a,b) a+b} +@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b} +@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b} +@r{ a b@: / @: @: 2 @:div@:(a,b) a/b} +@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b} +@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)} +@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b} +@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b} +@r{ a b@: : @: @: 2 @:fdiv@:(a,b)} +@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b} +@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a} +@r{ a b@: H | @: @: 2 @:append@:(a,b)} +@r{ a b@: I H | @: @: @:append@:(b,a)} +@r{ a@: & @: @: 1 @:inv@:(a) 1/a} +@r{ a@: ! @: @: 1 @:fact@:(a) a!} +@r{ a@: = @: @: 1 @:evalv@:(a)} +@r{ a@: M-% @: @: @:percent@:(a) a%} + +@c +@r{ ... a@: RET @: @: 1 @:@:... a a} +@r{ ... a@: SPC @: @: 1 @:@:... a a} +@r{... a b@: TAB @: @: 3 @:@:... b a} +@r{. a b c@: M-TAB @: @: 3 @:@:... b c a} +@r{... a b@: LFD @: @: 1 @:@:... a b a} +@r{ ... a@: DEL @: @: 1 @:@:...} +@r{... a b@: M-DEL @: @: 1 @:@:... b} +@r{ @: M-RET @: @: 4 @:calc-last-args@:} +@r{ a@: ` @:editing @: 1,30 @:calc-edit@:} + +@c +@r{ ... a@: C-d @: @: 1 @:@:...} +@r{ @: C-k @: @: 27 @:calc-kill@:} +@r{ @: C-w @: @: 27 @:calc-kill-region@:} +@r{ @: C-y @: @: @:calc-yank@:} +@r{ @: C-_ @: @: 4 @:calc-undo@:} +@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:} +@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:} + +@c +@r{ @: [ @: @: @:@:[...} +@r{[.. a b@: ] @: @: @:@:[a,b]} +@r{ @: ( @: @: @:@:(...} +@r{(.. a b@: ) @: @: @:@:(a,b)} +@r{ @: , @: @: @:@:vector or rect complex} +@r{ @: ; @: @: @:@:matrix or polar complex} +@r{ @: .. @: @: @:@:interval} + +@c +@r{ @: ~ @: @: @:calc-num-prefix@:} +@r{ @: < @: @: 4 @:calc-scroll-left@:} +@r{ @: > @: @: 4 @:calc-scroll-right@:} +@r{ @: @{ @: @: 4 @:calc-scroll-down@:} +@r{ @: @} @: @: 4 @:calc-scroll-up@:} +@r{ @: ? @: @: @:calc-help@:} + +@c +@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a} +@r{ @: o @: @: 4 @:calc-realign@:} +@r{ @: p @:precision @: 31 @:calc-precision@:} +@r{ @: q @: @: @:calc-quit@:} +@r{ @: w @: @: @:calc-why@:} +@r{ @: x @:command @: @:M-x calc-@:command} +@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:} + +@c +@r{ a@: A @: @: 1 @:abs@:(a)} +@r{ a b@: B @: @: 2 @:log@:(a,b)} +@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a} +@r{ a@: C @: @: 1 @:cos@:(a)} +@r{ a@: I C @: @: 1 @:arccos@:(a)} +@r{ a@: H C @: @: 1 @:cosh@:(a)} +@r{ a@: I H C @: @: 1 @:arccosh@:(a)} +@r{ @: D @: @: 4 @:calc-redo@:} +@r{ a@: E @: @: 1 @:exp@:(a)} +@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a} +@r{ a@: F @: @: 1,11 @:floor@:(a,d)} +@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)} +@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)} +@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)} +@r{ a@: G @: @: 1 @:arg@:(a)} +@r{ @: H @:command @: 32 @:@:Hyperbolic} +@r{ @: I @:command @: 32 @:@:Inverse} +@r{ a@: J @: @: 1 @:conj@:(a)} +@r{ @: K @:command @: 32 @:@:Keep-args} +@r{ a@: L @: @: 1 @:ln@:(a)} +@r{ a@: H L @: @: 1 @:log10@:(a)} +@r{ @: M @: @: @:calc-more-recursion-depth@:} +@r{ @: I M @: @: @:calc-less-recursion-depth@:} +@r{ a@: N @: @: 5 @:evalvn@:(a)} +@r{ @: P @: @: @:@:pi} +@r{ @: I P @: @: @:@:gamma} +@r{ @: H P @: @: @:@:e} +@r{ @: I H P @: @: @:@:phi} +@r{ a@: Q @: @: 1 @:sqrt@:(a)} +@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2} +@r{ a@: R @: @: 1,11 @:round@:(a,d)} +@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)} +@r{ a@: H R @: @: 1,11 @:fround@:(a,d)} +@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)} +@r{ a@: S @: @: 1 @:sin@:(a)} +@r{ a@: I S @: @: 1 @:arcsin@:(a)} +@r{ a@: H S @: @: 1 @:sinh@:(a)} +@r{ a@: I H S @: @: 1 @:arcsinh@:(a)} +@r{ a@: T @: @: 1 @:tan@:(a)} +@r{ a@: I T @: @: 1 @:arctan@:(a)} +@r{ a@: H T @: @: 1 @:tanh@:(a)} +@r{ a@: I H T @: @: 1 @:arctanh@:(a)} +@r{ @: U @: @: 4 @:calc-undo@:} +@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:} + +@c +@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b} +@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b} +@r{ a b@: a < @: @: 2 @:lt@:(a,b) a<b} +@r{ a b@: a > @: @: 2 @:gt@:(a,b) a>b} +@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b} +@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b} +@r{ a b@: a @{ @: @: 2 @:in@:(a,b)} +@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b} +@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b} +@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a} +@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c} +@r{ a@: a . @: @: 1 @:rmeq@:(a)} +@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:} + +@c +@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)} +@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)} +@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)} +@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b} + +@c +@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)} +@r{ a b@: a % @: @: 2 @:prem@:(a,b)} +@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]} +@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b} + +@c +@r{ a@: a a @: @: 1 @:apart@:(a)} +@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)} +@r{ a@: a c @:v @: 38 @:collect@:(a,v)} +@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)} +@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)} +@r{ a@: a e @: @: @:esimplify@:(a)} +@r{ a@: a f @: @: 1 @:factor@:(a)} +@r{ a@: H a f @: @: 1 @:factors@:(a)} +@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)} +@r{ a@: a i @:v @: 38 @:integ@:(a,v)} +@r{ a@: a m @:pats @: 38 @:match@:(a,pats)} +@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)} +@r{ data x@: a p @: @: 28 @:polint@:(data,x)} +@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)} +@r{ a@: a n @: @: 1 @:nrat@:(a)} +@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)} +@r{ a@: a s @: @: @:simplify@:(a)} +@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)} +@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:} +@r{ a@: a x @: @: 4,8 @:expand@:(a)} + +@c +@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)} +@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)} +@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)} +@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)} +@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)} +@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)} +@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)} +@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)} +@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)} +@r{ a@: a P @:v @: 38 @:roots@:(a,v)} +@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)} +@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)} +@r{ a@: a S @:v @: 38 @:solve@:(a,v)} +@r{ a@: I a S @:v @: 38 @:finv@:(a,v)} +@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)} +@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)} +@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)} +@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)} +@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)} + +@c +@r{ a b@: b a @: @: 9 @:and@:(a,b,w)} +@r{ a@: b c @: @: 9 @:clip@:(a,w)} +@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)} +@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)} +@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)} +@r{ a@: b n @: @: 9 @:not@:(a,w)} +@r{ a b@: b o @: @: 9 @:or@:(a,b,w)} +@r{ v@: b p @: @: 1 @:vpack@:(v)} +@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)} +@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)} +@r{ a@: b t @: @: 10 @:rot@:(a,n,w)} +@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)} +@r{ a@: b u @: @: 1 @:vunpack@:(a)} +@r{ @: b w @:w @: 9,50 @:calc-word-size@:} +@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)} + +@c +@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)} +@r{ r n p@: b F @: @: @:fv@:(r,n,p)} +@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)} +@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)} +@r{ v@: b I @: @: 19 @:irr@:(v)} +@r{ v@: I b I @: @: 19 @:irrb@:(v)} +@r{ a@: b L @: @: 10 @:ash@:(a,n,w)} +@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)} +@r{ r n a@: b M @: @: @:pmt@:(r,n,a)} +@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)} +@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)} +@r{ r v@: b N @: @: 19 @:npv@:(r,v)} +@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)} +@r{ r n p@: b P @: @: @:pv@:(r,n,p)} +@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)} +@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)} +@r{ a@: b R @: @: 10 @:rash@:(a,n,w)} +@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)} +@r{ c s l@: b S @: @: @:sln@:(c,s,l)} +@r{ n p a@: b T @: @: @:rate@:(n,p,a)} +@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)} +@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)} +@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)} + +@r{ r p a@: b # @: @: @:nper@:(r,p,a)} +@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)} +@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)} +@r{ a b@: b % @: @: @:relch@:(a,b)} + +@c +@r{ a@: c c @: @: 5 @:pclean@:(a,p)} +@r{ a@: c 0-9 @: @: @:pclean@:(a,p)} +@r{ a@: H c c @: @: 5 @:clean@:(a,p)} +@r{ a@: H c 0-9 @: @: @:clean@:(a,p)} +@r{ a@: c d @: @: 1 @:deg@:(a)} +@r{ a@: c f @: @: 1 @:pfloat@:(a)} +@r{ a@: H c f @: @: 1 @:float@:(a)} +@r{ a@: c h @: @: 1 @:hms@:(a)} +@r{ a@: c p @: @: @:polar@:(a)} +@r{ a@: I c p @: @: @:rect@:(a)} +@r{ a@: c r @: @: 1 @:rad@:(a)} + +@c +@r{ a@: c F @: @: 5 @:pfrac@:(a,p)} +@r{ a@: H c F @: @: 5 @:frac@:(a,p)} + +@c +@r{ a@: c % @: @: @:percent@:(a*100)} + +@c +@r{ @: d . @:char @: 50 @:calc-point-char@:} +@r{ @: d , @:char @: 50 @:calc-group-char@:} +@r{ @: d < @: @: 13,50 @:calc-left-justify@:} +@r{ @: d = @: @: 13,50 @:calc-center-justify@:} +@r{ @: d > @: @: 13,50 @:calc-right-justify@:} +@r{ @: d @{ @:label @: 50 @:calc-left-label@:} +@r{ @: d @} @:label @: 50 @:calc-right-label@:} +@r{ @: d [ @: @: 4 @:calc-truncate-up@:} +@r{ @: d ] @: @: 4 @:calc-truncate-down@:} +@r{ @: d " @: @: 12,50 @:calc-display-strings@:} +@r{ @: d SPC @: @: @:calc-refresh@:} +@r{ @: d RET @: @: 1 @:calc-refresh-top@:} + +@c +@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:} +@r{ @: d 2 @: @: 50 @:calc-binary-radix@:} +@r{ @: d 6 @: @: 50 @:calc-hex-radix@:} +@r{ @: d 8 @: @: 50 @:calc-octal-radix@:} + +@c +@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:} +@r{ @: d c @: @: 50 @:calc-complex-notation@:} +@r{ @: d d @:format @: 50 @:calc-date-notation@:} +@r{ @: d e @: @: 5,50 @:calc-eng-notation@:} +@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:} +@r{ @: d g @: @:12,13,50 @:calc-group-digits@:} +@r{ @: d h @:format @: 50 @:calc-hms-notation@:} +@r{ @: d i @: @: 50 @:calc-i-notation@:} +@r{ @: d j @: @: 50 @:calc-j-notation@:} +@r{ @: d l @: @: 12,50 @:calc-line-numbering@:} +@r{ @: d n @: @: 5,50 @:calc-normal-notation@:} +@r{ @: d o @:format @: 50 @:calc-over-notation@:} +@r{ @: d p @: @: 12,50 @:calc-show-plain@:} +@r{ @: d r @:radix @: 31,50 @:calc-radix@:} +@r{ @: d s @: @: 5,50 @:calc-sci-notation@:} +@r{ @: d t @: @: 27 @:calc-truncate-stack@:} +@r{ @: d w @: @: 12,13 @:calc-auto-why@:} +@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:} + +@c +@r{ @: d B @: @: 50 @:calc-big-language@:} +@r{ @: d C @: @: 50 @:calc-c-language@:} +@r{ @: d E @: @: 50 @:calc-eqn-language@:} +@r{ @: d F @: @: 50 @:calc-fortran-language@:} +@r{ @: d M @: @: 50 @:calc-mathematica-language@:} +@r{ @: d N @: @: 50 @:calc-normal-language@:} +@r{ @: d O @: @: 50 @:calc-flat-language@:} +@r{ @: d P @: @: 50 @:calc-pascal-language@:} +@r{ @: d T @: @: 50 @:calc-tex-language@:} +@r{ @: d U @: @: 50 @:calc-unformatted-language@:} +@r{ @: d W @: @: 50 @:calc-maple-language@:} + +@c +@r{ a@: f [ @: @: 4 @:decr@:(a,n)} +@r{ a@: f ] @: @: 4 @:incr@:(a,n)} + +@c +@r{ a b@: f b @: @: 2 @:beta@:(a,b)} +@r{ a@: f e @: @: 1 @:erf@:(a)} +@r{ a@: I f e @: @: 1 @:erfc@:(a)} +@r{ a@: f g @: @: 1 @:gamma@:(a)} +@r{ a b@: f h @: @: 2 @:hypot@:(a,b)} +@r{ a@: f i @: @: 1 @:im@:(a)} +@r{ n a@: f j @: @: 2 @:besJ@:(n,a)} +@r{ a b@: f n @: @: 2 @:min@:(a,b)} +@r{ a@: f r @: @: 1 @:re@:(a)} +@r{ a@: f s @: @: 1 @:sign@:(a)} +@r{ a b@: f x @: @: 2 @:max@:(a,b)} +@r{ n a@: f y @: @: 2 @:besY@:(n,a)} + +@c +@r{ a@: f A @: @: 1 @:abssqr@:(a)} +@r{ x a b@: f B @: @: @:betaI@:(x,a,b)} +@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)} +@r{ a@: f E @: @: 1 @:expm1@:(a)} +@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)} +@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)} +@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)} +@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)} +@r{ a b@: f I @: @: 2 @:ilog@:(a,b)} +@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a} +@r{ a@: f L @: @: 1 @:lnp1@:(a)} +@r{ a@: f M @: @: 1 @:mant@:(a)} +@r{ a@: f Q @: @: 1 @:isqrt@:(a)} +@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2} +@r{ a n@: f S @: @: 2 @:scf@:(a,n)} +@r{ y x@: f T @: @: @:arctan2@:(y,x)} +@r{ a@: f X @: @: 1 @:xpon@:(a)} + +@c +@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:} +@r{ @: g b @: @: 12 @:calc-graph-border@:} +@r{ @: g c @: @: @:calc-graph-clear@:} +@r{ @: g d @: @: 41 @:calc-graph-delete@:} +@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:} +@r{ @: g g @: @: 12 @:calc-graph-grid@:} +@r{ @: g h @:title @: @:calc-graph-header@:} +@r{ @: g j @: @: 4 @:calc-graph-juggle@:} +@r{ @: g k @: @: 12 @:calc-graph-key@:} +@r{ @: g l @: @: 12 @:calc-graph-log-x@:} +@r{ @: g n @:name @: @:calc-graph-name@:} +@r{ @: g p @: @: 42 @:calc-graph-plot@:} +@r{ @: g q @: @: @:calc-graph-quit@:} +@r{ @: g r @:range @: @:calc-graph-range-x@:} +@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:} +@r{ @: g t @:title @: @:calc-graph-title-x@:} +@r{ @: g v @: @: @:calc-graph-view-commands@:} +@r{ @: g x @:display @: @:calc-graph-display@:} +@r{ @: g z @: @: 12 @:calc-graph-zero-x@:} + +@c +@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:} +@r{ @: g C @:command @: @:calc-graph-command@:} +@r{ @: g D @:device @: 43,44 @:calc-graph-device@:} +@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:} +@r{ @: g H @: @: 12 @:calc-graph-hide@:} +@r{ @: g K @: @: @:calc-graph-kill@:} +@r{ @: g L @: @: 12 @:calc-graph-log-y@:} +@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:} +@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:} +@r{ @: g P @: @: 42 @:calc-graph-print@:} +@r{ @: g R @:range @: @:calc-graph-range-y@:} +@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:} +@r{ @: g T @:title @: @:calc-graph-title-y@:} +@r{ @: g V @: @: @:calc-graph-view-trail@:} +@r{ @: g X @:format @: @:calc-graph-geometry@:} +@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:} + +@c +@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:} +@r{ @: g C-r @:range @: @:calc-graph-range-z@:} +@r{ @: g C-t @:title @: @:calc-graph-title-z@:} + +@c +@r{ @: h b @: @: @:calc-describe-bindings@:} +@r{ @: h c @:key @: @:calc-describe-key-briefly@:} +@r{ @: h f @:function @: @:calc-describe-function@:} +@r{ @: h h @: @: @:calc-full-help@:} +@r{ @: h i @: @: @:calc-info@:} +@r{ @: h k @:key @: @:calc-describe-key@:} +@r{ @: h n @: @: @:calc-view-news@:} +@r{ @: h s @: @: @:calc-info-summary@:} +@r{ @: h t @: @: @:calc-tutorial@:} +@r{ @: h v @:var @: @:calc-describe-variable@:} + +@c +@r{ @: j 1-9 @: @: @:calc-select-part@:} +@r{ @: j RET @: @: 27 @:calc-copy-selection@:} +@r{ @: j DEL @: @: 27 @:calc-del-selection@:} +@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:} +@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:} +@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:} + +@c +@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:} +@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:} +@r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:} +@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:} +@r{ @: j & @: @: 27 @:calc-sel-invert@:} + +@c +@r{ @: j a @: @: 27 @:calc-select-additional@:} +@r{ @: j b @: @: 12 @:calc-break-selections@:} +@r{ @: j c @: @: @:calc-clear-selections@:} +@r{ @: j d @: @: 12,50 @:calc-show-selections@:} +@r{ @: j e @: @: 12 @:calc-enable-selections@:} +@r{ @: j l @: @: 4,27 @:calc-select-less@:} +@r{ @: j m @: @: 4,27 @:calc-select-more@:} +@r{ @: j n @: @: 4 @:calc-select-next@:} +@r{ @: j o @: @: 4,27 @:calc-select-once@:} +@r{ @: j p @: @: 4 @:calc-select-previous@:} +@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:} +@r{ @: j s @: @: 4,27 @:calc-select-here@:} +@r{ @: j u @: @: 27 @:calc-unselect@:} +@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:} + +@c +@r{ @: j C @: @: 27 @:calc-sel-commute@:} +@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:} +@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:} +@r{ @: j I @: @: 27 @:calc-sel-isolate@:} +@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)} +@r{ @: j L @: @: 4,27 @:calc-commute-left@:} +@r{ @: j M @: @: 27 @:calc-sel-merge@:} +@r{ @: j N @: @: 27 @:calc-sel-negate@:} +@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:} +@r{ @: j R @: @: 4,27 @:calc-commute-right@:} +@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:} +@r{ @: j U @: @: 27 @:calc-sel-unpack@:} + +@c +@r{ @: k a @: @: @:calc-random-again@:} +@r{ n@: k b @: @: 1 @:bern@:(n)} +@r{ n x@: H k b @: @: 2 @:bern@:(n,x)} +@r{ n m@: k c @: @: 2 @:choose@:(n,m)} +@r{ n m@: H k c @: @: 2 @:perm@:(n,m)} +@r{ n@: k d @: @: 1 @:dfact@:(n) n!!} +@r{ n@: k e @: @: 1 @:euler@:(n)} +@r{ n x@: H k e @: @: 2 @:euler@:(n,x)} +@r{ n@: k f @: @: 4 @:prfac@:(n)} +@r{ n m@: k g @: @: 2 @:gcd@:(n,m)} +@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)} +@r{ n m@: k l @: @: 2 @:lcm@:(n,m)} +@r{ n@: k m @: @: 1 @:moebius@:(n)} +@r{ n@: k n @: @: 4 @:nextprime@:(n)} +@r{ n@: I k n @: @: 4 @:prevprime@:(n)} +@r{ n@: k p @: @: 4,28 @:calc-prime-test@:} +@r{ m@: k r @: @: 14 @:random@:(m)} +@r{ n m@: k s @: @: 2 @:stir1@:(n,m)} +@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)} +@r{ n@: k t @: @: 1 @:totient@:(n)} + +@c +@r{ n p x@: k B @: @: @:utpb@:(x,n,p)} +@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)} +@r{ v x@: k C @: @: @:utpc@:(x,v)} +@r{ v x@: I k C @: @: @:ltpc@:(x,v)} +@r{ n m@: k E @: @: @:egcd@:(n,m)} +@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)} +@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)} +@r{ m s x@: k N @: @: @:utpn@:(x,m,s)} +@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)} +@r{ m x@: k P @: @: @:utpp@:(x,m)} +@r{ m x@: I k P @: @: @:ltpp@:(x,m)} +@r{ v x@: k T @: @: @:utpt@:(x,v)} +@r{ v x@: I k T @: @: @:ltpt@:(x,v)} + +@c +@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} +@r{ @: m d @: @: @:calc-degrees-mode@:} +@r{ @: m f @: @: 12 @:calc-frac-mode@:} +@r{ @: m g @: @: 52 @:calc-get-modes@:} +@r{ @: m h @: @: @:calc-hms-mode@:} +@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:} +@r{ @: m m @: @: @:calc-save-modes@:} +@r{ @: m p @: @: 12 @:calc-polar-mode@:} +@r{ @: m r @: @: @:calc-radians-mode@:} +@r{ @: m s @: @: 12 @:calc-symbolic-mode@:} +@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:} +@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:} +@r{ @: m w @: @: 13 @:calc-working@:} +@r{ @: m x @: @: @:calc-always-load-extensions@:} + +@c +@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:} +@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:} +@r{ @: m C @: @: 12 @:calc-auto-recompute@:} +@r{ @: m D @: @: @:calc-default-simplify-mode@:} +@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:} +@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:} +@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:} +@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:} +@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:} +@r{ @: m S @: @: 12 @:calc-shift-prefix@:} +@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:} + +@c +@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:} +@r{ @: s d @:var, decl @: @:calc-declare-variable@:} +@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:} +@r{ @: s i @:buffer @: @:calc-insert-variables@:} +@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)} +@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:} +@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)} +@r{ @: s p @:var @: 29 @:calc-permanent-variable@:} +@r{ @: s r @:var @: 29 @:@:v (recalled value)} +@r{ @: r 0-9 @: @: @:calc-recall-quick@:} +@r{ a@: s s @:var @: 28,29 @:calc-store@:} +@r{ a@: s 0-9 @: @: @:calc-store-quick@:} +@r{ a@: s t @:var @: 29 @:calc-store-into@:} +@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:} +@r{ @: s u @:var @: 29 @:calc-unstore@:} +@r{ a@: s x @:var @: 29 @:calc-store-exchange@:} + +@c +@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:} +@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:} +@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:} +@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:} +@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:} +@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:} +@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:} +@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:} +@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:} +@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:} +@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:} +@r{ @: s U @:editing @: 30 @:calc-edit-Units@:} +@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:} + +@c +@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)} +@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)} +@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)} +@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)} +@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)} +@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)} +@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)} +@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)} +@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))} +@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @t{:=} b} +@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @t{=>}} + +@c +@r{ @: t [ @: @: 4 @:calc-trail-first@:} +@r{ @: t ] @: @: 4 @:calc-trail-last@:} +@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:} +@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:} +@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:} + +@c +@r{ @: t b @: @: 4 @:calc-trail-backward@:} +@r{ @: t d @: @: 12,50 @:calc-trail-display@:} +@r{ @: t f @: @: 4 @:calc-trail-forward@:} +@r{ @: t h @: @: @:calc-trail-here@:} +@r{ @: t i @: @: @:calc-trail-in@:} +@r{ @: t k @: @: 4 @:calc-trail-kill@:} +@r{ @: t m @:string @: @:calc-trail-marker@:} +@r{ @: t n @: @: 4 @:calc-trail-next@:} +@r{ @: t o @: @: @:calc-trail-out@:} +@r{ @: t p @: @: 4 @:calc-trail-previous@:} +@r{ @: t r @:string @: @:calc-trail-isearch-backward@:} +@r{ @: t s @:string @: @:calc-trail-isearch-forward@:} +@r{ @: t y @: @: 4 @:calc-trail-yank@:} + +@c +@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)} +@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)} +@r{ d@: t D @: @: 15 @:date@:(d)} +@r{ d@: t I @: @: 4 @:incmonth@:(d,n)} +@r{ d@: t J @: @: 16 @:julian@:(d,z)} +@r{ d@: t M @: @: 17 @:newmonth@:(d,n)} +@r{ @: t N @: @: 16 @:now@:(z)} +@r{ d@: t P @:1 @: 31 @:year@:(d)} +@r{ d@: t P @:2 @: 31 @:month@:(d)} +@r{ d@: t P @:3 @: 31 @:day@:(d)} +@r{ d@: t P @:4 @: 31 @:hour@:(d)} +@r{ d@: t P @:5 @: 31 @:minute@:(d)} +@r{ d@: t P @:6 @: 31 @:second@:(d)} +@r{ d@: t P @:7 @: 31 @:weekday@:(d)} +@r{ d@: t P @:8 @: 31 @:yearday@:(d)} +@r{ d@: t P @:9 @: 31 @:time@:(d)} +@r{ d@: t U @: @: 16 @:unixtime@:(d,z)} +@r{ d@: t W @: @: 17 @:newweek@:(d,w)} +@r{ d@: t Y @: @: 17 @:newyear@:(d,n)} + +@c +@r{ a b@: t + @: @: 2 @:badd@:(a,b)} +@r{ a b@: t - @: @: 2 @:bsub@:(a,b)} + +@c +@r{ @: u a @: @: 12 @:calc-autorange-units@:} +@r{ a@: u b @: @: @:calc-base-units@:} +@r{ a@: u c @:units @: 18 @:calc-convert-units@:} +@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:} +@r{ @: u e @: @: @:calc-explain-units@:} +@r{ @: u g @:unit @: @:calc-get-unit-definition@:} +@r{ @: u p @: @: @:calc-permanent-units@:} +@r{ a@: u r @: @: @:calc-remove-units@:} +@r{ a@: u s @: @: @:usimplify@:(a)} +@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:} +@r{ @: u u @:unit @: @:calc-undefine-unit@:} +@r{ @: u v @: @: @:calc-enter-units-table@:} +@r{ a@: u x @: @: @:calc-extract-units@:} +@r{ a@: u 0-9 @: @: @:calc-quick-units@:} + +@c +@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)} +@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)} +@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)} +@r{ v@: u G @: @: 19 @:vgmean@:(v)} +@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)} +@r{ v@: u M @: @: 19 @:vmean@:(v)} +@r{ v@: I u M @: @: 19 @:vmeane@:(v)} +@r{ v@: H u M @: @: 19 @:vmedian@:(v)} +@r{ v@: I H u M @: @: 19 @:vhmean@:(v)} +@r{ v@: u N @: @: 19 @:vmin@:(v)} +@r{ v@: u S @: @: 19 @:vsdev@:(v)} +@r{ v@: I u S @: @: 19 @:vpsdev@:(v)} +@r{ v@: H u S @: @: 19 @:vvar@:(v)} +@r{ v@: I H u S @: @: 19 @:vpvar@:(v)} +@r{ @: u V @: @: @:calc-view-units-table@:} +@r{ v@: u X @: @: 19 @:vmax@:(v)} + +@c +@r{ v@: u + @: @: 19 @:vsum@:(v)} +@r{ v@: u * @: @: 19 @:vprod@:(v)} +@r{ v@: u # @: @: 19 @:vcount@:(v)} + +@c +@r{ @: V ( @: @: 50 @:calc-vector-parens@:} +@r{ @: V @{ @: @: 50 @:calc-vector-braces@:} +@r{ @: V [ @: @: 50 @:calc-vector-brackets@:} +@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:} +@r{ @: V , @: @: 50 @:calc-vector-commas@:} +@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:} +@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:} +@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:} +@r{ @: V / @: @: 12,50 @:calc-break-vectors@:} +@r{ @: V . @: @: 12,50 @:calc-full-vectors@:} + +@c +@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)} +@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)} +@r{ s@: V ~ @: @: 1 @:vcompl@:(s)} +@r{ s@: V # @: @: 1 @:vcard@:(s)} +@r{ s@: V : @: @: 1 @:vspan@:(s)} +@r{ s@: V + @: @: 1 @:rdup@:(s)} + +@c +@r{ m@: V & @: @: 1 @:inv@:(m) 1/m} + +@c +@r{ v@: v a @:n @: @:arrange@:(v,n)} +@r{ a@: v b @:n @: @:cvec@:(a,n)} +@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)} +@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)} +@r{ m@: v c @:0 @: 31 @:getdiag@:(m)} +@r{ v@: v d @: @: 25 @:diag@:(v,n)} +@r{ v m@: v e @: @: 2 @:vexp@:(v,m)} +@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)} +@r{ v a@: v f @: @: 26 @:find@:(v,a,n)} +@r{ v@: v h @: @: 1 @:head@:(v)} +@r{ v@: I v h @: @: 1 @:tail@:(v)} +@r{ v@: H v h @: @: 1 @:rhead@:(v)} +@r{ v@: I H v h @: @: 1 @:rtail@:(v)} +@r{ @: v i @:n @: 31 @:idn@:(1,n)} +@r{ @: v i @:0 @: 31 @:idn@:(1)} +@r{ h t@: v k @: @: 2 @:cons@:(h,t)} +@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)} +@r{ v@: v l @: @: 1 @:vlen@:(v)} +@r{ v@: H v l @: @: 1 @:mdims@:(v)} +@r{ v m@: v m @: @: 2 @:vmask@:(v,m)} +@r{ v@: v n @: @: 1 @:rnorm@:(v)} +@r{ a b c@: v p @: @: 24 @:calc-pack@:} +@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)} +@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)} +@r{ m@: v r @:0 @: 31 @:getdiag@:(m)} +@r{ v i j@: v s @: @: @:subvec@:(v,i,j)} +@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)} +@r{ m@: v t @: @: 1 @:trn@:(m)} +@r{ v@: v u @: @: 24 @:calc-unpack@:} +@r{ v@: v v @: @: 1 @:rev@:(v)} +@r{ @: v x @:n @: 31 @:index@:(n)} +@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)} + +@c +@r{ v@: V A @:op @: 22 @:apply@:(op,v)} +@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)} +@r{ m@: V D @: @: 1 @:det@:(m)} +@r{ s@: V E @: @: 1 @:venum@:(s)} +@r{ s@: V F @: @: 1 @:vfloor@:(s)} +@r{ v@: V G @: @: @:grade@:(v)} +@r{ v@: I V G @: @: @:rgrade@:(v)} +@r{ v@: V H @:n @: 31 @:histogram@:(v,n)} +@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)} +@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)} +@r{ m@: V J @: @: 1 @:ctrn@:(m)} +@r{ m@: V L @: @: 1 @:lud@:(m)} +@r{ v@: V M @:op @: 22,23 @:map@:(op,v)} +@r{ v@: V N @: @: 1 @:cnorm@:(v)} +@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)} +@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)} +@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)} +@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)} +@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)} +@r{ v@: V S @: @: @:sort@:(v)} +@r{ v@: I V S @: @: @:rsort@:(v)} +@r{ m@: V T @: @: 1 @:tr@:(m)} +@r{ v@: V U @:op @: 22 @:accum@:(op,v)} +@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)} +@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)} +@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)} +@r{ s t@: V V @: @: 2 @:vunion@:(s,t)} +@r{ s t@: V X @: @: 2 @:vxor@:(s,t)} + +@c +@r{ @: Y @: @: @:@:user commands} + +@c +@r{ @: z @: @: @:@:user commands} + +@c +@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:} +@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:} +@r{ @: Z : @: @: @:calc-kbd-else@:} +@r{ @: Z ] @: @: @:calc-kbd-end-if@:} + +@c +@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:} +@r{ c@: Z / @: @: 45 @:calc-kbd-break@:} +@r{ @: Z @} @: @: @:calc-kbd-end-loop@:} +@r{ n@: Z < @: @: @:calc-kbd-repeat@:} +@r{ @: Z > @: @: @:calc-kbd-end-repeat@:} +@r{ n m@: Z ( @: @: @:calc-kbd-for@:} +@r{ s@: Z ) @: @: @:calc-kbd-end-for@:} + +@c +@r{ @: Z C-g @: @: @:@:cancel if/loop command} + +@c +@r{ @: Z ` @: @: @:calc-kbd-push@:} +@r{ @: Z ' @: @: @:calc-kbd-pop@:} +@r{ a@: Z = @:message @: 28 @:calc-kbd-report@:} +@r{ @: Z # @:prompt @: @:calc-kbd-query@:} + +@c +@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:} +@r{ @: Z D @:key, command @: @:calc-user-define@:} +@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:} +@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:} +@r{ @: Z G @:key @: @:calc-get-user-defn@:} +@r{ @: Z I @: @: @:calc-user-define-invocation@:} +@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:} +@r{ @: Z P @:key @: @:calc-user-define-permanent@:} +@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:} +@r{ @: Z T @: @: 12 @:calc-timing@:} +@r{ @: Z U @:key @: @:calc-user-undefine@:} + +@end format + +@noindent +NOTES + +@enumerate +@c 1 +@item +Positive prefix arguments apply to @cite{n} stack entries. +Negative prefix arguments apply to the @cite{-n}th stack entry. +A prefix of zero applies to the entire stack. (For @key{LFD} and +@kbd{M-DEL}, the meaning of the sign is reversed.) + +@c 2 +@item +Positive prefix arguments apply to @cite{n} stack entries. +Negative prefix arguments apply to the top stack entry +and the next @cite{-n} stack entries. + +@c 3 +@item +Positive prefix arguments rotate top @cite{n} stack entries by one. +Negative prefix arguments rotate the entire stack by @cite{-n}. +A prefix of zero reverses the entire stack. + +@c 4 +@item +Prefix argument specifies a repeat count or distance. + +@c 5 +@item +Positive prefix arguments specify a precision @cite{p}. +Negative prefix arguments reduce the current precision by @cite{-p}. + +@c 6 +@item +A prefix argument is interpreted as an additional step-size parameter. +A plain @kbd{C-u} prefix means to prompt for the step size. + +@c 7 +@item +A prefix argument specifies simplification level and depth. +1=Default, 2=like @kbd{a s}, 3=like @kbd{a e}. + +@c 8 +@item +A negative prefix operates only on the top level of the input formula. + +@c 9 +@item +Positive prefix arguments specify a word size of @cite{w} bits, unsigned. +Negative prefix arguments specify a word size of @cite{w} bits, signed. + +@c 10 +@item +Prefix arguments specify the shift amount @cite{n}. The @cite{w} argument +cannot be specified in the keyboard version of this command. + +@c 11 +@item +From the keyboard, @cite{d} is omitted and defaults to zero. + +@c 12 +@item +Mode is toggled; a positive prefix always sets the mode, and a negative +prefix always clears the mode. + +@c 13 +@item +Some prefix argument values provide special variations of the mode. + +@c 14 +@item +A prefix argument, if any, is used for @cite{m} instead of taking +@cite{m} from the stack. @cite{M} may take any of these values: +@iftex +{@advance@tableindent10pt +@end iftex +@table @asis +@item Integer +Random integer in the interval @cite{[0 .. m)}. +@item Float +Random floating-point number in the interval @cite{[0 .. m)}. +@item 0.0 +Gaussian with mean 1 and standard deviation 0. +@item Error form +Gaussian with specified mean and standard deviation. +@item Interval +Random integer or floating-point number in that interval. +@item Vector +Random element from the vector. +@end table +@iftex +} +@end iftex + +@c 15 +@item +A prefix argument from 1 to 6 specifies number of date components +to remove from the stack. @xref{Date Conversions}. + +@c 16 +@item +A prefix argument specifies a time zone; @kbd{C-u} says to take the +time zone number or name from the top of the stack. @xref{Time Zones}. + +@c 17 +@item +A prefix argument specifies a day number (0-6, 0-31, or 0-366). + +@c 18 +@item +If the input has no units, you will be prompted for both the old and +the new units. + +@c 19 +@item +With a prefix argument, collect that many stack entries to form the +input data set. Each entry may be a single value or a vector of values. + +@c 20 +@item +With a prefix argument of 1, take a single @c{$N\times2$} +@asis{Nx2} matrix from the +stack instead of two separate data vectors. + +@c 21 +@item +The row or column number @cite{n} may be given as a numeric prefix +argument instead. A plain @kbd{C-u} prefix says to take @cite{n} +from the top of the stack. If @cite{n} is a vector or interval, +a subvector/submatrix of the input is created. + +@c 22 +@item +The @cite{op} prompt can be answered with the key sequence for the +desired function, or with @kbd{x} or @kbd{z} followed by a function name, +or with @kbd{$} to take a formula from the top of the stack, or with +@kbd{'} and a typed formula. In the last two cases, the formula may +be a nameless function like @samp{<#1+#2>} or @samp{<x, y : x+y>}, or it +may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the +last argument of the created function), or otherwise you will be +prompted for an argument list. The number of vectors popped from the +stack by @kbd{V M} depends on the number of arguments of the function. + +@c 23 +@item +One of the mapping direction keys @kbd{_} (horizontal, i.e., map +by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or +reduce down), or @kbd{=} (map or reduce by rows) may be used before +entering @cite{op}; these modify the function name by adding the letter +@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,'' +or @code{d} for ``down.'' + +@c 24 +@item +The prefix argument specifies a packing mode. A nonnegative mode +is the number of items (for @kbd{v p}) or the number of levels +(for @kbd{v u}). A negative mode is as described below. With no +prefix argument, the mode is taken from the top of the stack and +may be an integer or a vector of integers. +@iftex +{@advance@tableindent-20pt +@end iftex +@table @cite +@item -1 +@var{(2)} Rectangular complex number. +@item -2 +@var{(2)} Polar complex number. +@item -3 +@var{(3)} HMS form. +@item -4 +@var{(2)} Error form. +@item -5 +@var{(2)} Modulo form. +@item -6 +@var{(2)} Closed interval. +@item -7 +@var{(2)} Closed .. open interval. +@item -8 +@var{(2)} Open .. closed interval. +@item -9 +@var{(2)} Open interval. +@item -10 +@var{(2)} Fraction. +@item -11 +@var{(2)} Float with integer mantissa. +@item -12 +@var{(2)} Float with mantissa in @cite{[1 .. 10)}. +@item -13 +@var{(1)} Date form (using date numbers). +@item -14 +@var{(3)} Date form (using year, month, day). +@item -15 +@var{(6)} Date form (using year, month, day, hour, minute, second). +@end table +@iftex +} +@end iftex + +@c 25 +@item +A prefix argument specifies the size @cite{n} of the matrix. With no +prefix argument, @cite{n} is omitted and the size is inferred from +the input vector. + +@c 26 +@item +The prefix argument specifies the starting position @cite{n} (default 1). + +@c 27 +@item +Cursor position within stack buffer affects this command. + +@c 28 +@item +Arguments are not actually removed from the stack by this command. + +@c 29 +@item +Variable name may be a single digit or a full name. + +@c 30 +@item +Editing occurs in a separate buffer. Press @kbd{M-# M-#} (or @kbd{C-c C-c}, +@key{LFD}, or in some cases @key{RET}) to finish the edit, or press +@kbd{M-# x} to cancel the edit. The @key{LFD} key prevents evaluation +of the result of the edit. + +@c 31 +@item +The number prompted for can also be provided as a prefix argument. + +@c 32 +@item +Press this key a second time to cancel the prefix. + +@c 33 +@item +With a negative prefix, deactivate all formulas. With a positive +prefix, deactivate and then reactivate from scratch. + +@c 34 +@item +Default is to scan for nearest formula delimiter symbols. With a +prefix of zero, formula is delimited by mark and point. With a +non-zero prefix, formula is delimited by scanning forward or +backward by that many lines. + +@c 35 +@item +Parse the region between point and mark as a vector. A nonzero prefix +parses @var{n} lines before or after point as a vector. A zero prefix +parses the current line as a vector. A @kbd{C-u} prefix parses the +region between point and mark as a single formula. + +@c 36 +@item +Parse the rectangle defined by point and mark as a matrix. A positive +prefix @var{n} divides the rectangle into columns of width @var{n}. +A zero or @kbd{C-u} prefix parses each line as one formula. A negative +prefix suppresses special treatment of bracketed portions of a line. + +@c 37 +@item +A numeric prefix causes the current language mode to be ignored. + +@c 38 +@item +Responding to a prompt with a blank line answers that and all +later prompts by popping additional stack entries. + +@c 39 +@item +Answer for @cite{v} may also be of the form @cite{v = v_0} or +@cite{v - v_0}. + +@c 40 +@item +With a positive prefix argument, stack contains many @cite{y}'s and one +common @cite{x}. With a zero prefix, stack contains a vector of +@cite{y}s and a common @cite{x}. With a negative prefix, stack +contains many @cite{[x,y]} vectors. (For 3D plots, substitute +@cite{z} for @cite{y} and @cite{x,y} for @cite{x}.) + +@c 41 +@item +With any prefix argument, all curves in the graph are deleted. + +@c 42 +@item +With a positive prefix, refines an existing plot with more data points. +With a negative prefix, forces recomputation of the plot data. + +@c 43 +@item +With any prefix argument, set the default value instead of the +value for this graph. + +@c 44 +@item +With a negative prefix argument, set the value for the printer. + +@c 45 +@item +Condition is considered ``true'' if it is a nonzero real or complex +number, or a formula whose value is known to be nonzero; it is ``false'' +otherwise. + +@c 46 +@item +Several formulas separated by commas are pushed as multiple stack +entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"} +delimiters may be omitted. The notation @kbd{$$$} refers to the value +in stack level three, and causes the formula to replace the top three +stack levels. The notation @kbd{$3} refers to stack level three without +causing that value to be removed from the stack. Use @key{LFD} in place +of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET} +to evaluate variables.@refill + +@c 47 +@item +The variable is replaced by the formula shown on the right. The +Inverse flag reverses the order of the operands, e.g., @kbd{I s - x} +assigns @c{$x \coloneq a-x$} +@cite{x := a-x}. + +@c 48 +@item +Press @kbd{?} repeatedly to see how to choose a model. Answer the +variables prompt with @cite{iv} or @cite{iv;pv} to specify +independent and parameter variables. A positive prefix argument +takes @i{N+1} vectors from the stack; a zero prefix takes a matrix +and a vector from the stack. + +@c 49 +@item +With a plain @kbd{C-u} prefix, replace the current region of the +destination buffer with the yanked text instead of inserting. + +@c 50 +@item +All stack entries are reformatted; the @kbd{H} prefix inhibits this. +The @kbd{I} prefix sets the mode temporarily, redraws the top stack +entry, then restores the original setting of the mode. + +@c 51 +@item +A negative prefix sets the default 3D resolution instead of the +default 2D resolution. + +@c 52 +@item +This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize}, +@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar}, +@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12 +grabs the @var{n}th mode value only. +@end enumerate + +@iftex +(Space is provided below for you to keep your own written notes.) +@page +@endgroup +@end iftex + + +@c [end-summary] + +@node Key Index, Command Index, Summary, Top +@unnumbered Index of Key Sequences + +@printindex ky + +@node Command Index, Function Index, Key Index, Top +@unnumbered Index of Calculator Commands + +Since all Calculator commands begin with the prefix @samp{calc-}, the +@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically +types @samp{calc-} for you. Thus, @kbd{x last-args} is short for +@kbd{M-x calc-last-args}. + +@printindex pg + +@node Function Index, Concept Index, Command Index, Top +@unnumbered Index of Algebraic Functions + +This is a list of built-in functions and operators usable in algebraic +expressions. Their full Lisp names are derived by adding the prefix +@samp{calcFunc-}, as in @code{calcFunc-sqrt}. +@iftex +All functions except those noted with ``*'' have corresponding +Calc keystrokes and can also be found in the Calc Summary. +@end iftex + +@printindex tp + +@node Concept Index, Variable Index, Function Index, Top +@unnumbered Concept Index + +@printindex cp + +@node Variable Index, Lisp Function Index, Concept Index, Top +@unnumbered Index of Variables + +The variables in this list that do not contain dashes are accessible +as Calc variables. Add a @samp{var-} prefix to get the name of the +corresponding Lisp variable. + +The remaining variables are Lisp variables suitable for @code{setq}ing +in your @file{.emacs} file. + +@printindex vr + +@node Lisp Function Index, , Variable Index, Top +@unnumbered Index of Lisp Math Functions + +The following functions are meant to be used with @code{defmath}, not +@code{defun} definitions. For names that do not start with @samp{calc-}, +the corresponding full Lisp name is derived by adding a prefix of +@samp{math-}. + +@printindex fn + +@summarycontents + +@c [end] + +@contents +@bye + +