emacs/info/calc-3

This is ../../info/calc, produced by makeinfo version 4.13 from
calc.texi.

This file documents Calc, the GNU Emacs calculator.

Copyright (C) 1990-1991, 2001-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being just "GNU GENERAL
     PUBLIC LICENSE", with the Front-Cover texts being "A GNU Manual,"
     and with the Back-Cover Texts as in (a) below.  A copy of the
     license is included in the section entitled "GNU Free
     Documentation License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION Emacs misc features
START-INFO-DIR-ENTRY
* Calc: (calc).                 Advanced desk calculator and mathematical tool.
END-INFO-DIR-ENTRY


File: calc,  Node: Related Financial Functions,  Next: Depreciation Functions,  Prev: Present Value,  Up: Financial Functions

9.6.4 Related Financial Functions
---------------------------------

The functions in this section are basically inverses of the present
value functions with respect to the various arguments.

   The `b M' (`calc-fin-pmt') [`pmt'] command computes the amount of
periodic payment necessary to amortize a loan.  Thus `pmt(RATE, N,
AMOUNT)' equals the value of PAYMENT such that `pv(RATE, N, PAYMENT) =
AMOUNT'.

   The `I b M' [`pmtb'] command does the same computation but using
`pvb' instead of `pv'.  Like `pv' and `pvb', these functions can also
take a fourth argument which represents an initial lump-sum investment.

   The `H b M' key just invokes the `fvl' function, which is the
inverse of `pvl'.  There is no explicit `pmtl' function.

   The `b #' (`calc-fin-nper') [`nper'] command computes the number of
regular payments necessary to amortize a loan.  Thus `nper(RATE,
PAYMENT, AMOUNT)' equals the value of N such that `pv(RATE, N, PAYMENT)
= AMOUNT'.  If PAYMENT is too small ever to amortize a loan for AMOUNT
at interest rate RATE, the `nper' function is left in symbolic form.

   The `I b #' [`nperb'] command does the same computation but using
`pvb' instead of `pv'.  You can give a fourth lump-sum argument to
these functions, but the computation will be rather slow in the
four-argument case.

   The `H b #' [`nperl'] command does the same computation using `pvl'.
By exchanging PAYMENT and AMOUNT you can also get the solution for
`fvl'.  For example, `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.

   The `b T' (`calc-fin-rate') [`rate'] command computes the rate of
return on an investment.  This is also an inverse of `pv': `rate(N,
PAYMENT, AMOUNT)' computes the value of RATE such that `pv(RATE, N,
PAYMENT) = AMOUNT'.  The result is expressed as a formula like `6.3%'.

   The `I b T' [`rateb'] and `H b T' [`ratel'] commands solve the
analogous equations with `pvb' or `pvl' in place of `pv'.  Also, `rate'
and `rateb' can accept an optional fourth argument just like `pv' and
`pvb'.  To redo the above example from a different perspective,
`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.

   The `b I' (`calc-fin-irr') [`irr'] command is the analogous function
to `rate' but for net present value.  Its argument is a vector of
payments.  Thus `irr(PAYMENTS)' computes the RATE such that `npv(RATE,
PAYMENTS) = 0'; this rate is known as the "internal rate of return".

   The `I b I' [`irrb'] command computes the internal rate of return
assuming payments occur at the beginning of each period.


File: calc,  Node: Depreciation Functions,  Next: Definitions of Financial Functions,  Prev: Related Financial Functions,  Up: Financial Functions

9.6.5 Depreciation Functions
----------------------------

The functions in this section calculate "depreciation", which is the
amount of value that a possession loses over time.  These functions are
characterized by three parameters:  COST, the original cost of the
asset; SALVAGE, the value the asset will have at the end of its
expected "useful life"; and 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.

   The `b S' (`calc-fin-sln') [`sln'] command computes the
"straight-line" depreciation.  In this method, the asset depreciates by
the same amount every year (or period).  For example, `sln(12000, 2000,
5)' returns 2000.  The asset costs $12000 initially and will be worth
$2000 after five years; it loses $2000 per year.

   The `b Y' (`calc-fin-syd') [`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, `b Y' takes a fourth PERIOD parameter which
specifies which year is requested, from 1 to LIFE.  If PERIOD is
outside this range, the `syd' function will return zero.

   The `b D' (`calc-fin-ddb') [`ddb'] command computes an accelerated
depreciation using the double-declining balance method.  It also takes
a fourth PERIOD parameter.

   For symmetry, the `sln' function will accept a PERIOD parameter as
well, although it will ignore its value except that the return value
will as usual be zero if PERIOD is out of range.

   For example, pushing the vector `[1,2,3,4,5]' (perhaps with `v x 5')
and then mapping `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:

     [ [ 2000, 3333, 4800 ]
       [ 2000, 2667, 2880 ]
       [ 2000, 2000, 1728 ]
       [ 2000, 1333,  592 ]
       [ 2000,  667,   0  ] ]

(Values have been rounded to nearest integers in this figure.)  We see
that `sln' depreciates by the same amount each year, `syd' depreciates
more at the beginning and less at the end, and `ddb' weights the
depreciation even more toward the beginning.

   Summing columns with `V R : +' yields `[10000, 10000, 10000]'; the
total depreciation in any method is (by definition) the difference
between the cost and the salvage value.


File: calc,  Node: Definitions of Financial Functions,  Prev: Depreciation Functions,  Up: Financial Functions

9.6.6 Definitions
-----------------

For your reference, here are the actual formulas used to compute Calc's
financial functions.

   Calc will not evaluate a financial function unless the RATE or N
argument is known.  However, PAYMENT or AMOUNT can be a variable.  Calc
expands these functions according to the formulas below for symbolic
arguments only when you use the `a "' (`calc-expand-formula') command,
or when taking derivatives or integrals or solving equations involving
the functions.

   These formulas are shown using the conventions of Big display mode
(`d B'); for example, the formula for `fv' written linearly is `pmt *
((1 + rate)^n) - 1) / rate'.

                                             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

In `pmt' and `pmtb', `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 `log' in `nper' is negative,
`nper' leaves itself in symbolic form rather than returning a
(financially meaningless) complex number.

   `rate(num, pmt, amt)' solves the equation `pv(rate, num, pmt) = amt'
for `rate' using `H a R' (`calc-find-root'), with the interval `[.01%
.. 100%]' for an initial guess.  The `rateb' function is the same except
that it uses `pvb'.  Note that `ratel' can be solved directly; its
formula is shown in the above list.

   Similarly, `irr(pmts)' solves the equation `npv(rate, pmts) = 0' for
`rate'.

   If you give a fourth argument to `nper' or `nperb', Calc will also
use `H a R' to solve the equation using an initial guess interval of
`[0 .. 100]'.

   A fourth argument to `fv' simply sums the two components calculated
from the above formulas for `fv' and `fvl'.  The same is true of `fvb',
`pv', and `pvb'.

   The `ddb' function is computed iteratively; the "book" value starts
out equal to COST, and decreases according to the above formula for the
specified number of periods.  If the book value would decrease below
SALVAGE, it only decreases to SALVAGE and the depreciation is zero for
all subsequent periods.  The `ddb' function returns the amount the book
value decreased in the specified period.


File: calc,  Node: Binary Functions,  Prev: Financial Functions,  Up: Arithmetic

9.7 Binary Number Functions
===========================

The commands in this chapter all use two-letter sequences beginning with
the `b' prefix.

   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 `d 2', `d 8', or `d 6' commands,
respectively).  You may also wish to enable display of leading zeros
with `d z'.  *Note Radix Modes::.

   The Calculator maintains a current "word size" `w', an arbitrary
positive or negative integer.  For a positive word size, all of the
binary operations described here operate modulo `2^w'.  In particular,
negative arguments are converted to positive integers modulo `2^w' by
all binary functions.

   If the word size is negative, binary operations produce
twos-complement integers from `-(2^(-w-1))' to `2^(-w-1)-1' inclusive.
Either mode accepts inputs in any range; the sign of `w' affects only
the results produced.

   The `b c' (`calc-clip') [`clip'] command can be used to clip a
number by reducing it modulo `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,
*note Simplification Modes::, `calc-bin-simplify-mode'.)  For example,
with a word size of 8 bits `b c' converts a number to the range 0 to
255; with a word size of -8 `b c' converts to the range -128 to 127.

   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:  `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 `b w' (`calc-word-size').  This
command displays a prompt with the current word size; press <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
`and(a,b)' is finally evaluated, the word size current at that time
will be used, but when `and(a,b,-8)' is evaluated, a word size of -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 `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.

   The `b a' (`calc-and') [`and'] command computes the bitwise AND of
the two numbers on the top of the stack.  In other words, for each of
the `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:
`and(2#1100, 2#1010) = 2#1000'.

   The `b o' (`calc-or') [`or'] command computes the bitwise inclusive
OR of two numbers.  A bit is 1 if either of the input bits, or both,
are 1:  `or(2#1100, 2#1010) = 2#1110'.

   The `b x' (`calc-xor') [`xor'] command computes the bitwise
exclusive OR of two numbers.  A bit is 1 if exactly one of the input
bits is 1:  `xor(2#1100, 2#1010) = 2#0110'.

   The `b d' (`calc-diff') [`diff'] command computes the bitwise
difference of two numbers; this is defined by `diff(a,b) =
and(a,not(b))', so that `diff(2#1100, 2#1010) = 2#0100'.

   The `b n' (`calc-not') [`not'] command computes the bitwise NOT of a
number.  A bit is 1 if the input bit is 0 and vice-versa.

   The `b l' (`calc-lshift-binary') [`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,
`lsh(a)' is short for `lsh(a,1)', which in turn is short for
`lsh(a,n,w)'.  Bits shifted "off the end," according to the current
word size, are lost.

   The `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.

   The `b r' (`calc-rshift-binary') [`rsh'] command shifts a number
right by one bit, or by the number of bits specified in the numeric
prefix argument:  `rsh(a,n) = lsh(a,-n)'.

   The `b L' (`calc-lshift-arith') [`ash'] command shifts a number
left.  It is analogous to `lsh', except that if the shift is rightward
(the prefix argument is negative), an arithmetic shift is performed as
described below.

   The `b R' (`calc-rshift-arith') [`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 `rsh' and `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.

   The `b t' (`calc-rotate-binary') [`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.

   *Note Set Operations::, for the `b p' and `b u' commands that pack
and unpack binary integers into sets.  (For example, `b u' unpacks the
number `2#11001' to the set of bit-numbers `[0, 3, 4]'.)  Type `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 `b u' to
unpack; type `31 <TAB> -' to replace each bit-number in the set with 31
minus that bit-number; type `b p' to pack the set back into a binary
integer.


File: calc,  Node: Scientific Functions,  Next: Matrix Functions,  Prev: Arithmetic,  Up: Top

10 Scientific Functions
***********************

The functions described here perform trigonometric and other
transcendental calculations.  They generally produce floating-point
answers correct to the full current precision.  The `H' (Hyperbolic)
and `I' (Inverse) flag keys must be used to get some of these functions
from the keyboard.

   One miscellaneous command is shift-`P' (`calc-pi'), which pushes the
value of `pi' (at the current precision) onto the stack.  With the
Hyperbolic flag, it pushes the value `e', the base of natural
logarithms.  With the Inverse flag, it pushes Euler's constant `gamma'
(about 0.5772).  With both Inverse and Hyperbolic, it pushes the
"golden ratio" `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
`pi', `e', `gamma', and `phi', respectively, instead of their values;
*note Symbolic Mode::.

   The `Q' (`calc-sqrt') [`sqrt'] function is described elsewhere;
*note Basic Arithmetic::.  With the Inverse flag [`sqr'], this command
computes the square of the argument.

   *Note 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::


File: calc,  Node: Logarithmic Functions,  Next: Trigonometric and Hyperbolic Functions,  Prev: Scientific Functions,  Up: Scientific Functions

10.1 Logarithmic Functions
==========================

The shift-`L' (`calc-ln') [`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 `E' command.

   The shift-`E' (`calc-exp') [`exp'] command computes the exponential,
i.e., `e' raised to the power of the number on the stack.  The meanings
of the Inverse and Hyperbolic flags follow from those for the `calc-ln'
command.

   The `H L' (`calc-log10') [`log10'] command computes the common
(base-10) logarithm of a number.  (With the Inverse flag [`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 `ln(10)'.

   The `B' (`calc-log') [`log'] command computes a logarithm to any
base.  For example, `1024 <RET> 2 B' produces 10, since `2^10 = 1024'.
In certain cases like `log(3,9)', the result will be either `1:2' or
`0.5' depending on the current Fraction mode setting.  With the Inverse
flag [`alog'], this command is similar to `^' except that the order of
the arguments is reversed.

   The `f I' (`calc-ilog') [`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 `ilog(x,10)' is 3 for all `x' in the range
from 1000 to 9999.  If both arguments are positive integers, exact
integer arithmetic is used; otherwise, this is equivalent to
`floor(log(x,b))'.

   The `f E' (`calc-expm1') [`expm1'] command computes `exp(x)-1', but
using an algorithm that produces a more accurate answer when the result
is close to zero, i.e., when `exp(x)' is close to one.

   The `f L' (`calc-lnp1') [`lnp1'] command computes `ln(x+1)',
producing a more accurate answer when `x' is close to zero.


File: calc,  Node: Trigonometric and Hyperbolic Functions,  Next: Advanced Math Functions,  Prev: Logarithmic Functions,  Up: Scientific Functions

10.2 Trigonometric/Hyperbolic Functions
=======================================

The shift-`S' (`calc-sin') [`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.

   Calc's "units" mechanism includes angular units like `deg', `rad',
and `grad'.  While `sin(45 deg)' is not evaluated all the time, the `u
s' (`calc-simplify-units') command will simplify `sin(45 deg)' by
taking the sine of 45 degrees, regardless of the current angular mode.
*Note Basic Operations on Units::.

   Also, the symbolic variable `pi' is not ordinarily recognized in
arguments to trigonometric functions, as in `sin(3 pi / 4)', but the `a
s' (`calc-simplify') command recognizes many such formulas when the
current angular mode is Radians _and_ Symbolic mode is enabled; this
example would be replaced by `sqrt(2) / 2'.  *Note Symbolic Mode::.
Beware, this simplification occurs even if you have stored a different
value in the variable `pi'; this is one reason why changing built-in
variables is a bad idea.  Arguments of the form `x' plus a multiple of
`pi/2' are also simplified.  Calc includes similar formulas for `cos'
and `tan'.

   The `a s' command knows all angles which are integer multiples of
`pi/12', `pi/10', or `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.

   With the Inverse flag, `calc-sin' computes an arcsine.  This is also
available as the `calc-arcsin' command or `arcsin' algebraic function.
The returned argument is converted to degrees, radians, or HMS notation
depending on the current angular mode.

   With the Hyperbolic flag, `calc-sin' computes the hyperbolic sine,
also available as `calc-sinh' [`sinh'].  With the Hyperbolic and
Inverse flags, it computes the hyperbolic arcsine (`calc-arcsinh')
[`arcsinh'].

   The shift-`C' (`calc-cos') [`cos'] command computes the cosine of an
angle or complex number, and shift-`T' (`calc-tan') [`tan'] computes
the tangent, along with all the various inverse and hyperbolic variants
of these functions.

   The `f T' (`calc-arctan2') [`arctan2'] command takes two numbers
from the stack and computes the arc tangent of their ratio.  The result
is in the full range from -180 (exclusive) to +180 (inclusive) degrees,
or the analogous range in radians.  A similar result would be obtained
with `/' followed by `I T', but the value would only be in the range
from -90 to +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 `arctan2' would avoid.  By (arbitrary)
definition, `arctan2(0,0)=0'.

   The `calc-sincos' [`sincos'] command computes the sine and cosine of
a number, returning them as a vector of the form `[COS, SIN]'.  With
the Inverse flag [`arcsincos'], this command takes a two-element vector
as an argument and computes `arctan2' of the elements.  (This command
does not accept the Hyperbolic flag.)

   The remaining trigonometric functions, `calc-sec' [`sec'],
`calc-csc' [`csc'] and `calc-cot' [`cot'], are also available.  With
the Hyperbolic flag, these compute their hyperbolic counterparts, which
are also available separately as `calc-sech' [`sech'], `calc-csch'
[`csch'] and `calc-coth' [`coth'].  (These commands do not accept the
Inverse flag.)


File: calc,  Node: Advanced Math Functions,  Next: Branch Cuts,  Prev: Trigonometric and Hyperbolic Functions,  Up: Scientific Functions

10.3 Advanced Mathematical Functions
====================================

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 precision.  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.

   The `f g' (`calc-gamma') [`gamma'] command computes the Euler gamma
function.  For positive integer arguments, this is related to the
factorial function:  `gamma(n+1) = fact(n)'.  For general complex
arguments the gamma function can be defined by the following definite
integral: `gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)'.  (The actual
implementation uses far more efficient computational methods.)

   The `f G' (`calc-inc-gamma') [`gammaP'] command computes the
incomplete gamma function, denoted `P(a,x)'.  This is defined by the
integral, `gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)'.
This implies that `gammaP(a,inf) = 1' for any `a' (see the definition
of the normal gamma function).

   Several other varieties of incomplete gamma function are defined.
The complement of `P(a,x)', called `Q(a,x) = 1-P(a,x)' by some authors,
is computed by the `I f G' [`gammaQ'] command.  You can think of this
as taking the other half of the integral, from `x' to infinity.

   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
`g(a,x)' and `G(a,x)', respectively (where `g' and `G' represent the
lower- and upper-case Greek letter gamma).  You can obtain these using
the `H f G' [`gammag'] and `H I f G' [`gammaG'] commands.

   The `f b' (`calc-beta') [`beta'] command computes the Euler beta
function, which is defined in terms of the gamma function as `beta(a,b)
= gamma(a) gamma(b) / gamma(a+b)', or by `beta(a,b) = integ(t^(a-1)
(1-t)^(b-1), t, 0, 1)'.

   The `f B' (`calc-inc-beta') [`betaI'] command computes the
incomplete beta function `I(x,a,b)'.  It is defined by `betaI(x,a,b) =
integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)'.  Once again, the `H'
(hyperbolic) prefix gives the corresponding un-normalized version
[`betaB'].

   The `f e' (`calc-erf') [`erf'] command computes the error function
`erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)'.  The complementary
error function `I f e' (`calc-erfc') [`erfc'] is the corresponding
integral from `x' to infinity; the sum `erf(x) + erfc(x) = 1'.

   The `f j' (`calc-bessel-J') [`besJ'] and `f y' (`calc-bessel-Y')
[`besY'] commands compute the Bessel functions of the first and second
kinds, respectively.  In `besJ(n,x)' and `besY(n,x)' the "order"
parameter `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!


File: calc,  Node: Branch Cuts,  Next: Random Numbers,  Prev: Advanced Math Functions,  Up: Scientific Functions

10.4 Branch Cuts and 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
"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 `arctan' and `arctanh' were changed
between the first and second editions of Steele.  Recent versions of
Calc 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
`arctan' cut is always in the right half of the complex plane, and its
`arctanh' cut is always in the top half of the plane.  Calc's cuts are
continuous with quadrants I and III for `arctan', or II and IV for
`arctanh'.

   Note:  The current implementations of these functions with complex
arguments are designed with proper behavior around the branch cuts in
mind, _not_ efficiency or accuracy.  You may need to increase the
floating precision and wait a while to get suitable answers from them.

   For `sqrt(a+bi)':  When `a<0' and `b' is small but positive or zero,
the result is close to the `+i' axis.  For `b' small and negative, the
result is close to the `-i' axis.  The result always lies in the right
half of the complex plane.

   For `ln(a+bi)':  The real part is defined as `ln(abs(a+bi))'.  The
imaginary part is defined as `arg(a+bi) = arctan2(b,a)'.  Thus the
branch cuts for `sqrt' and `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 `z' are as shown, then the real and
imaginary parts of `f(z)' will be as shown.  Here `eps' stands for a
small positive value; each occurrence of `eps' may stand for a
different small value.

          z           sqrt(z)       ln(z)
     ----------------------------------------
        +,   0         +,  0       any, 0
        -,   0         0,  +       any, pi
        -, +eps      +eps, +      +eps, +
        -, -eps      +eps, -      +eps, -

   For `z1^z2':  This is defined by `exp(ln(z1)*z2)'.  One interesting
consequence of this is that `(-8)^1:3' does not evaluate to -2 as you
might expect, but to the complex number `(1., 1.732)'.  Both of these
are valid cube roots of -8 (as is `(1., -1.732)'); Calc chooses a
perhaps less-obvious root for the sake of mathematical consistency.

   For `arcsin(z)':  This is defined by `-i*ln(i*z + sqrt(1-z^2))'.
The branch cuts are on the real axis, less than -1 and greater than 1.

   For `arccos(z)':  This is defined by `-i*ln(z + i*sqrt(1-z^2))', or
equivalently by `pi/2 - arcsin(z)'.  The branch cuts are on the real
axis, less than -1 and greater than 1.

   For `arctan(z)':  This is defined by `(ln(1+i*z) - ln(1-i*z)) /
(2*i)'.  The branch cuts are on the imaginary axis, below `-i' and
above `i'.

   For `arcsinh(z)':  This is defined by `ln(z + sqrt(1+z^2))'.  The
branch cuts are on the imaginary axis, below `-i' and above `i'.

   For `arccosh(z)':  This is defined by `ln(z +
(z+1)*sqrt((z-1)/(z+1)))'.  The branch cut is on the real axis less
than 1.

   For `arctanh(z)':  This is defined by `(ln(1+z) - ln(1-z)) / 2'.
The branch cuts are on the real axis, less than -1 and greater than 1.

   The following tables for `arcsin', `arccos', and `arctan' assume the
current angular mode is Radians.  The hyperbolic functions operate
independently of the angular mode.

            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,   +

            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

            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, +

   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.

     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)

   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.


File: calc,  Node: Random Numbers,  Next: Combinatorial Functions,  Prev: Branch Cuts,  Up: Scientific Functions

10.5 Random Numbers
===================

The `k r' (`calc-random') [`random'] command produces random numbers of
various sorts.

   Given a positive numeric prefix argument `M', it produces a random
integer `N' in the range `0 <= N < M'.  Each possible value `N' appears
with equal probability.

   With no numeric prefix argument, the `k r' command takes its argument
from the stack instead.  Once again, if this is a positive integer `M'
the result is a random integer less than `M'.  However, note that while
numeric prefix arguments are limited to six digits or so, an `M' taken
from the stack can be arbitrarily large.  If `M' is negative, the
result is a random integer in the range `M < N <= 0'.

   If the value on the stack is a floating-point number `M', the result
is a random floating-point number `N' in the range `0 <= N < M' or `M <
N <= 0', according to the sign of `M'.

   If `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 `M' is an error form `m +/- s' where M and S are both real
numbers, the result uses a Gaussian distribution with mean M and
standard deviation S.

   If `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, `random([1.0..2.0))' will return any of one million
numbers from 1.00000 to 1.99999; `random([1.0..2.0])' may additionally
return 2.00000, but the probability of this happening is extremely
small.)

   If `M' is a vector, the result is one element taken at random from
the vector.  All elements of the vector are given equal probabilities.

   The sequence of numbers produced by `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
`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
`RandSeed', Calc will switch to a different pseudo-random sequence.  If
you "unstore" `RandSeed', Calc will re-seed itself from the current
time.  If you store the same integer that you used before back into
`RandSeed', you will get the exact same sequence of random numbers as
before.

   The `calc-rrandom' command (not on any key) produces a random real
number between zero and one.  It is equivalent to `random(1.0)'.

   The `k a' (`calc-random-again') command produces another random
number, re-using the most recent value of `M'.  With a numeric prefix
argument N, it produces N more random numbers using that value of `M'.

   The `k h' (`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 `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 `M' from second-to-top.)

   If `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 `k h' and using `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 `k r''s will produce the same number more than
once.  The `k h' command produces a vector whose elements are always
distinct.  (Actually, there is a slight exception: If `M' is a vector,
no given vector element will be drawn more than once, but if several
elements of `M' are equal, they may each make it into the result
vector.)

   One use of `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: `[1,
1.5, 2, 2.5, 3] 5 k h' might produce the permuted list `[2.5, 1, 1.5,
3, 2]'.  As a convenient feature, if the argument N is negative it is
replaced by the size of the set represented by `M'.  Naturally, this is
allowed only when `M' specifies a small discrete set of possibilities.

   To do the equivalent of `k h' but with duplications allowed, given
`M' on the stack and with N just entered as a numeric prefix, use `v b'
to build a vector of copies of `M', then use `V M k r' to "map" the
normal `k r' function over the elements of this vector.  *Note Matrix
Functions::.

* Menu:

* Random Number Generator::     (Complete description of Calc's algorithm)


File: calc,  Node: Random Number Generator,  Prev: Random Numbers,  Up: Random Numbers

10.5.1 Random Number Generator
------------------------------

Calc's random number generator uses several methods to ensure that the
numbers it produces are highly random.  Knuth's _Art of Computer
Programming_, Volume II, contains a thorough description of the theory
of random number generators and their measurement and characterization.

   If `RandSeed' has no stored value, Calc calls Emacs's built-in
`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 `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 `random' function, Calc exercises the function several
times to estimate the range.  When Calc subsequently uses the `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
`random'.

   If `RandSeed' contains an integer, Calc uses this integer to seed an
"additive congruential" method (Knuth's algorithm 3.2.2A, computing
`X_n-55 - X_n-24').  This method expands the seed value into a large
table which is maintained internally; the variable `RandSeed' is
changed from, e.g., 42 to the vector `[42]' to indicate that the seed
has been absorbed into this table.  When `RandSeed' contains a vector,
`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 `s r RandSeed' to get the seed
vector, `v u' to unpack it back into a number, then `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 `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 `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 P, Calc
simply creates a random P-digit integer and multiplies by `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 `10^-9' or `10^-10', but those numbers will only have two or three
random digits since they correspond to small integers times `10^-12'.

   To create a random integer in the interval `[0 .. M)', Calc counts
the digits in M, creates a random integer with three additional digits,
then reduces modulo M.  Unless 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 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 M is a power of ten, however, the numbers should be completely
unbiased.

   The Gaussian random numbers generated by `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 `random(0.0)' will require significant calculations.


File: calc,  Node: Combinatorial Functions,  Next: Probability Distribution Functions,  Prev: Random Numbers,  Up: Scientific Functions

10.6 Combinatorial Functions
============================

Commands relating to combinatorics and number theory begin with the `k'
key prefix.

   The `k g' (`calc-gcd') [`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
`a / gcd(a,x)' should yield an integer for any `a' and `x'.  For other
types of arguments, the operation is left in symbolic form.

   The `k l' (`calc-lcm') [`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.

   The `k E' (`calc-extended-gcd') [`egcd'] command computes the GCD of
two integers `x' and `y' and returns a vector `[g, a, b]' where `g =
gcd(x,y) = a x + b y'.

   The `!' (`calc-factorial') [`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.

   The `k d' (`calc-double-factorial') [`dfact'] command computes the
"double factorial" of an integer.  For an even integer, this is the
product of even integers from 2 to `N'.  For an odd integer, this is
the product of odd integers from 3 to `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
`N!!' is also recognized for double factorials.

   The `k c' (`calc-choose') [`choose'] command computes the binomial
coefficient `N'-choose-`M', where `M' is the number on the top of the
stack and `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 `N! / M! (N-M)!'.

   The `H k c' (`calc-perm') [`perm'] command computes the
number-of-permutations function `N! / (N-M)!'.

   The `k b' (`calc-bernoulli-number') [`bern'] command computes a
given Bernoulli number.  The value at the top of the stack is a
nonnegative integer `n' that specifies which Bernoulli number is
desired.  The `H k b' command computes a Bernoulli polynomial, taking
`n' from the second-to-top position and `x' from the top of the stack.
If `x' is a variable or formula the result is a polynomial in `x'; if
`x' is a number the result is a number.

   The `k e' (`calc-euler-number') [`euler'] command similarly computes
an Euler number, and `H k e' computes an Euler polynomial.  Bernoulli
and Euler numbers occur in the Taylor expansions of several functions.

   The `k s' (`calc-stirling-number') [`stir1'] command computes a
Stirling number of the first kind, given two integers `n' and `m' on
the stack.  The `H k s' [`stir2'] command computes a Stirling number of
the second kind.  These are the number of `m'-cycle permutations of `n'
objects, and the number of ways to partition `n' objects into `m'
non-empty sets, respectively.

   The `k p' (`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 `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.

   The normal `k p' command performs one iteration of the primality
test.  Pressing `k p' repeatedly for the same integer will perform
additional iterations.  Also, `k p' with a numeric prefix performs the
specified number of iterations.  There is also an algebraic function
`prime(n)' or `prime(n,iters)' which returns 1 if `n' is (probably)
prime and 0 if not.

   The `k f' (`calc-prime-factors') [`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 -1.  For inputs -1, 0, and 1, the result is
a list of the same number.

   The `k n' (`calc-next-prime') [`nextprime'] command finds the next
prime above a given number.  Essentially, it searches by calling
`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 `k p' commands to increase your certainty
that the number is indeed prime.

   The `I k n' (`calc-prev-prime') [`prevprime'] command analogously
finds the next prime less than a given number.

   The `k t' (`calc-totient') [`totient'] command computes the Euler
"totient" function, the number of integers less than `n' which are
relatively prime to `n'.

   The `k m' (`calc-moebius') [`moebius'] command computes the Moebius
"mu" function.  If the input number is a product of `k' distinct
factors, this is `(-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.


File: calc,  Node: Probability Distribution Functions,  Prev: Combinatorial Functions,  Up: Scientific Functions

10.7 Probability Distribution Functions
=======================================

The functions in this section compute various probability distributions.
For continuous distributions, this is the integral of the probability
density function from `x' to infinity.  (These are the "upper tail"
distribution functions; there are also corresponding "lower tail"
functions which integrate from minus infinity to `x'.)  For discrete
distributions, the upper tail function gives the sum from `x' to
infinity; the lower tail function gives the sum from minus infinity up
to, but not including, `x'.

   To integrate from `x' to `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 `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 `ltpn(2.8,2,1) - ltpn(2.5,2,1)'.

   The `k B' (`calc-utpb') [`utpb'] function uses the binomial
distribution.  Push the parameters N, P, and then X onto the stack; the
result (`utpb(x,n,p)') is the probability that an event will occur X or
more times out of N trials, if its probability of occurring in any given
trial is P.  The `I k B' [`ltpb'] function is the probability that the
event will occur fewer than X times.

   The other probability distribution functions similarly take the form
`k X' (`calc-utpX') [`utpX'] and `I k X' [`ltpX'], for various letters
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., `2 <RET> 1 <RET> 2.5 k N M-<RET>
<DEL> 2.8 k N -', using `M-<RET> <DEL>' to recover the original
arguments but substitute a new value for `x'.)

   The `utpc(x,v)' function uses the chi-square distribution with `v'
degrees of freedom.  It is the probability that a model is correct if
its chi-square statistic is `x'.

   The `utpf(F,v1,v2)' function uses the F distribution, used in
various statistical tests.  The parameters `v1' and `v2' are the
degrees of freedom in the numerator and denominator, respectively, used
in computing the statistic `F'.

   The `utpn(x,m,s)' function uses a normal (Gaussian) distribution
with mean `m' and standard deviation `s'.  It is the probability that
such a normal-distributed random variable would exceed `x'.

   The `utpp(n,x)' function uses a Poisson distribution with mean `x'.
It is the probability that `n' or more such Poisson random events will
occur.

   The `utpt(t,v)' function uses the Student's "t" distribution with `v'
degrees of freedom.  It is the probability that a t-distributed random
variable will be greater than `t'.  (Note:  This computes the
distribution function `A(t|v)' where `A(0|v) = 1' and `A(inf|v) -> 0'.
The `UTPT' operation on the HP-48 uses a different definition which
returns half of Calc's value:  `UTPT(t,v) = .5*utpt(t,v)'.)

   While Calc does not provide inverses of the probability distribution
functions, the `a R' command can be used to solve for the inverse.
Since the distribution functions are monotonic, `a R' is guaranteed to
be able to find a solution given any initial guess.  *Note Numerical
Solutions::.


File: calc,  Node: Matrix Functions,  Next: Algebra,  Prev: Scientific Functions,  Up: Top

11 Vector/Matrix Functions
**************************

Many of the commands described here begin with the `v' prefix.  (For
convenience, the shift-`V' prefix is equivalent to `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 `[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::


File: calc,  Node: Packing and Unpacking,  Next: Building Vectors,  Prev: Matrix Functions,  Up: Matrix Functions

11.1 Packing and Unpacking
==========================

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.

   The `v p' (`calc-pack') [`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, `C-u 5 v p' will pop the top five stack elements
and push back a single vector of those five elements.  (`C-u 0 v p'
simply creates an empty vector.)

   The same effect can be had by pressing `[' to push an incomplete
vector on the stack, using <TAB> (`calc-roll-down') to sneak the
incomplete object up past a certain number of elements, and then
pressing `]' to complete the vector.

   Negative packing modes create other kinds of composite objects:

`-1'
     Two values are collected to build a complex number.  For example,
     `5 <RET> 7 C-u -1 v p' creates the complex number `(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
     `a + (0, 1) b'.  (The other packing modes also create a symbolic
     answer if the components are not suitable.)

`-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.

`-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.

`-4'
     Two values are collected into an error form.  The inputs may be
     real numbers or formulas.

`-5'
     Two values are collected into a modulo form.  The inputs must be
     real numbers.

`-6'
     Two values are collected into the interval `[a .. b]'.  The inputs
     may be real numbers, HMS or date forms, or formulas.

`-7'
     Two values are collected into the interval `[a .. b)'.

`-8'
     Two values are collected into the interval `(a .. b]'.

`-9'
     Two values are collected into the interval `(a .. b)'.

`-10'
     Two integer values are collected into a fraction.

`-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.

`-12'
     This is treated the same as -11 by the `v p' command.  When
     unpacking, -12 specifies that a floating-point mantissa is desired.

`-13'
     A real number is converted into a date form.

`-14'
     Three numbers (year, month, day) are packed into a pure date form.

`-15'
     Six numbers are packed into a date/time form.

   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, `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; `C-u -5 v p' could convert a vector of numbers and a single
number M into a vector of numbers modulo M.

   If you don't give a prefix argument to `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 `1 <RET> 2 <RET> 4 n v p' is another way to
enter the error form `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 `[2,
3]', then six numbers will be taken from the stack and returned in the
form `[[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, `[2, 3, -4]'
takes 12 objects and creates a 2x3 matrix of error forms: `[[a +/- b, c
+/- d ... ]]'.  Also, `[-4, -10]' will convert four integers into an
error form consisting of two fractions:  `a:b +/- c:d'.

   There is an equivalent algebraic function, `pack(MODE, ITEMS)' where
MODE is a packing mode (an integer or a vector of integers) and ITEMS
is a vector of objects to be packed (re-packed, really) according to
that mode.  For example, `pack([3, -4], [a,b,c,d,e,f])' yields `[a +/-
b, c +/- d, e +/- f]'.  The function is left in symbolic form if the
packing mode is invalid, or if the number of data items does not match
the number of items required by the mode.

   The `v u' (`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 `v p'.  If the value at the top
of the stack is a formula, `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 `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 `[a +/- b, c^2, d +/- 7]', the result of `C-u -4 v u' will
be the two vectors `[a, c^2, d]' and `[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 -5, then `c-u
-1 v u' yields -5 and 0 (the components of -5 when viewed as a
rectangular complex number); `C-u -2 v u' yields 5 and 180 (assuming
Degrees mode); and `C-u -10 v u' yields -5 and 1 (the numerator and
denominator of -5, viewed as a rational number).  Plain `v u' with this
input would complain that the input is not a composite object.

   Unpacking mode -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 -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 `v p'.  A
mode of 1 is much like plain `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, `C-u 1 v u' followed
by `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.

   There are two algebraic functions analogous to `v u'.  The
`unpack(MODE, ITEM)' function unpacks the ITEM using the given MODE,
returning the result as a vector of components.  Here the MODE must be
an integer, not a vector.  For example, `unpack(-4, a +/- b)' returns
`[a, b]', as does `unpack(1, a +/- b)'.

   The `unpackt' function is like `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, `unpackt(1, 2:3 +/- 1:4)'
returns `[-4, [2:3, 1:4]]', and `unpackt(2, 2:3 +/- 1:4)' returns
`[[-4, -10], [2, 3, 1, 4]]'.  The identity for re-building the original
object is `apply(pack, unpackt(N, X)) = X'.  (The `apply' function
builds a function call given the function name and a vector of
arguments.)

   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 `unpack(-10, X)_1'.


File: calc,  Node: Building Vectors,  Next: Extracting Elements,  Prev: Packing and Unpacking,  Up: Matrix Functions

11.2 Building Vectors
=====================

Vectors and matrices can be added, subtracted, multiplied, and divided;
*note Basic Arithmetic::.

   The `|' (`calc-concat') [`vconcat'] command "concatenates" two
vectors into one.  For example, after `[ 1 , 2 ] [ 3 , 4 ] |', the stack
will contain the single vector `[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 `|' is concerned.)

   If either argument to `|' is a scalar (a non-vector), it is treated
like a one-element vector for purposes of concatenation:  `1 [ 2 , 3 ]
|' produces the vector `[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.

   The `H |' (`calc-append') [`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 `append' function is left in symbolic form.
See also `cons' and `rcons' below.

   The `I |' and `H I |' commands are similar, but they use their two
stack arguments in the opposite order.  Thus `I |' is equivalent to
`<TAB> |', but possibly more convenient and also a bit faster.

   The `v d' (`calc-diag') [`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 3x3 matrix filled with
ones, use `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
`v b' and `v a'; see below.)

   The `v i' (`calc-ident') [`idn'] function builds an identity matrix
of the specified size.  It is a convenient form of `v d' where the
diagonal element is always one.  If no prefix argument is given, this
command prompts for one.

   In algebraic notation, `idn(a,n)' acts much like `diag(a,n)', except
that `a' is required to be a scalar (non-vector) quantity.  If `n' is
omitted, `idn(a)' represents `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 `v i' command with an argument of zero creates a generic
identity matrix, `idn(1)'.  Note that in dimensioned Matrix mode (*note
Matrix Mode::), generic identity matrices are immediately expanded to
the current default dimensions.

   The `v x' (`calc-index') [`index'] function builds a vector of
consecutive integers from 1 to N, where N is the numeric prefix
argument.  If you do not provide a prefix argument, you will be
prompted to enter a suitable number.  If N is negative, the result is a
vector of negative integers from N to -1.

   With a prefix argument of just `C-u', the `v x' command takes three
values from the stack: N, START, and INCR (with INCR at top-of-stack).
Counting starts at START and increases by INCR for successive vector
elements.  If START or N is in floating-point format, the resulting
vector elements will also be floats.  Note that START and INCR may in
fact be any kind of numbers or formulas.

   When START and INCR are specified, a negative N has a different
interpretation:  It causes a geometric instead of arithmetic sequence
to be generated.  For example, `index(-3, a, b)' produces `[a, a b, a
b^2]'.  If you omit INCR in the algebraic form, `index(N, START)', the
default value for INCR is one for positive N or two for negative N.

   The `v b' (`calc-build-vector') [`cvec'] function builds a vector of
N copies of the value on the top of the stack, where N is the numeric
prefix argument.  In algebraic formulas, `cvec(x,n,m)' can also be used
to build an N-by-M matrix of copies of X.  (Interactively, just use `v
b' twice: once to build a row, then again to build a matrix of copies
of that row.)

   The `v h' (`calc-head') [`head'] function returns the first element
of a vector.  The `I v h' (`calc-tail') [`tail'] function returns the
vector with its first element removed.  In both cases, the argument
must be a non-empty vector.

   The `v k' (`calc-cons') [`cons'] function takes a value H and a
vector T from the stack, and produces the vector whose head is H and
whose tail is T.  This is similar to `|', except if H is itself a
vector, `|' will concatenate the two vectors whereas `cons' will insert
H at the front of the vector T.

   Each of these three functions also accepts the Hyperbolic flag
[`rhead', `rtail', `rcons'] in which case T instead represents the
_last_ single element of the vector, with H representing the remainder
of the vector.  Thus the vector `[a, b, c, d] = cons(a, [b, c, d]) =
rcons([a, b, c], d)'.  Also, `head([a, b, c, d]) = a', `tail([a, b, c,
d]) = [b, c, d]', `rhead([a, b, c, d]) = [a, b, c]', and `rtail([a, b,
c, d]) = d'.


File: calc,  Node: Extracting Elements,  Next: Manipulating Vectors,  Prev: Building Vectors,  Up: Matrix Functions

11.3 Extracting Vector Elements
===============================

The `v r' (`calc-mrow') [`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.

   With a prefix argument of `C-u' only, `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 `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.

   Subscript notation in algebraic formulas (`a_b') stands for the Calc
function `subscr', which is synonymous with `mrow'.  Thus, `[x, y,
z]_k' produces `x', `y', or `z' if `k' is one, two, or three,
respectively.  A double subscript (`M_i_j', equivalent to
`subscr(subscr(M, i), j)') will access the element at row `i', column
`j' of a matrix.  The `a _' (`calc-subscript') command creates a
subscript formula `a_b' out of two stack entries.  (It is on the `a'
"algebra" prefix because subscripted variables are often used purely as
an algebraic notation.)

   Given a negative prefix argument, `v r' instead deletes one row or
element from the matrix or vector on the top of the stack.  Thus `C-u 2
v r' replaces a matrix with its second row, but `C-u -2 v r' replaces
the matrix with the same matrix with its second row removed.  In
algebraic form this function is called `mrrow'.

   Given a prefix argument of zero, `v r' extracts the diagonal elements
of a square matrix in the form of a vector.  In algebraic form this
function is called `getdiag'.

   The `v c' (`calc-mcol') [`mcol' or `mrcol'] command is the analogous
operation on columns of a matrix.  Given a plain vector it extracts (or
removes) one element, just like `v r'.  If the index in `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).

   To extract a matrix element at a given row and column, use `v r' to
extract the row as a vector, then `v c' to extract the column element
from that vector.  In algebraic formulas, it is often more convenient to
use subscript notation:  `m_i_j' gives row `i', column `j' of matrix
`m'.

   The `v s' (`calc-subvector') [`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 _past_ the range to be taken.
Thus, `subvec([a, b, c, d, e], 2, 4)' produces the subvector `[b, c]'.
You could get the same result using `mrow([a, b, c, d, e], [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 `subvec([a, b,
c, d, e], 2, -2)' also produces `[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, `inf', also has this effect when used as the
ending index.

   With the Inverse flag, `I v s' [`rsubvec'] removes a subvector from
a vector.  The arguments are interpreted the same as for the normal `v
s' command.  Thus, `rsubvec([a, b, c, d, e], 2, 4)' produces `[a, d,
e]'.  It is always true that `subvec' and `rsubvec' return
complementary parts of the input vector.

   *Note Selecting Subformulas::, for an alternative way to operate on
vectors one element at a time.


File: calc,  Node: Manipulating Vectors,  Next: Vector and Matrix Arithmetic,  Prev: Extracting Elements,  Up: Matrix Functions

11.4 Manipulating Vectors
=========================

The `v l' (`calc-vlength') [`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.

   With the Hyperbolic flag, `H v l' [`mdims'] computes a vector of the
dimensions of a vector, matrix, or higher-order object.  For example,
`mdims([[a,b,c],[d,e,f]])' returns `[2, 3]' since its argument is a 2x3
matrix.

   The `v f' (`calc-vector-find') [`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.

   The `v a' (`calc-arrange-vector') [`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 "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 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 `[[1, 2], [3, 4]]'
on the stack, `v a 4' produces `[[1, 2, 3, 4]]' (a 1x4 matrix), `v a 1'
produces `[[1], [2], [3], [4]]' (a 4x1 matrix), `v a 2' produces `[[1,
2], [3, 4]]' (the original 2x2 matrix), `v a 3' produces `[[1, 2, 3],
[4]]' (not a matrix), and `v a 0' produces the flattened list `[1, 2,
3, 4]'.

   The `V S' (`calc-sort') [`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 (*note Strings::), this means vectors of strings are also sorted
into alphabetical order by this command.

   The `I V S' [`rsort'] command sorts a vector into decreasing order.

   The `V G' (`calc-grade') [`grade', `rgrade'] command produces an
index table or permutation vector which, if applied to the input vector
(as the index of `C-u v r', say), would sort the vector.  A permutation
vector is just a vector of integers from 1 to 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 `V G', then use the result to reorder the original matrix with
`C-u v r'.  Another interesting property of the `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 Kth element says where the Kth original vector element
will rest when the vector is sorted.  To get a rank table, just use `V
G V G'.

   With the Inverse flag, `I V G' produces an index table that would
sort the input into decreasing order.  Note that `V S' and `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 `V S', since two elements which are equal look the same, but
with `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.

   The `V H' (`calc-histogram') [`histogram'] command builds a
histogram of a vector of numbers.  Vector elements are assumed to be
integers or real numbers in the range [0..N) for some "number of bins"
N, which is the numeric prefix argument given to the command.  The
result is a vector of 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.)

   If no prefix is given, then you will be prompted for a vector which
will be used to determine the bins. (If a positive integer is given at
this prompt, it will be still treated as if it were given as a prefix.)
Each bin will consist of the interval of numbers closest to the
corresponding number of this new vector; if the vector `[a, b, c, ...]'
is entered at the prompt, the bins will be `(-inf, (a+b)/2]',
`((a+b)/2, (b+c)/2]', etc.  The result of this command will be a vector
counting how many elements of the original vector are in each bin.

   The result will then be a vector with the same length as this new
vector; each element of the new vector will be replaced by the number of
elements of the original vector which are closest to it.

   With the Hyperbolic flag, `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.

   The `v t' (`calc-transpose') [`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.

   The `v v' (`calc-reverse-vector') [`rev'] command reverses a vector
end-for-end.  Given a matrix, it reverses the order of the rows.  (To
reverse the columns instead, just use `v t v v v t'.  The same
principle can be used to apply other vector commands to the columns of
a matrix.)

   The `v m' (`calc-mask-vector') [`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, `vmask([1, 0, 1, 0, 1], [a, b,
c, d, e])' produces `[a, c, e]'.  *Note Logical Operations::.

   The `v e' (`calc-expand-vector') [`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 `vexp([2, 0, 3, 0, 7], [a, b])' produces `[a, 0, b,
0, 7]'.

   With the Hyperbolic flag, `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:  `vexp([2, 0, 3, 0, 7], [a, b], z)' produces `[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: `vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])'
produces `[a, x, b, 7, y, 0]'.

   Another variation on the masking idea is to combine `[a, b, c, d, e]'
with the mask `[1, 0, 1, 0, 1]' to produce `[a, 0, c, 0, e]'.  You can
accomplish this with `V M a &', mapping the logical "and" operation
across the two vectors.  *Note Logical Operations::.  Note that the `?
:' operation also discussed there allows other types of masking using
vectors.


File: calc,  Node: Vector and Matrix Arithmetic,  Next: Set Operations,  Prev: Manipulating Vectors,  Up: Matrix Functions

11.5 Vector and Matrix Arithmetic
=================================

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.)
*Note Basic Arithmetic::.

   The following functions are applied element-wise if their arguments
are vectors or matrices: `change-sign', `conj', `arg', `re', `im',
`polar', `rect', `clean', `float', `frac'.  *Note Function Index::.

   The `V J' (`calc-conj-transpose') [`ctrn'] command computes the
conjugate transpose of its argument, i.e., `conj(trn(x))'.

   The `A' (`calc-abs') [`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.

   The `v n' (`calc-rnorm') [`rnorm'] command computes the
infinity-norm of a vector, or the row norm of a 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.

   The `V N' (`calc-cnorm') [`cnorm'] command computes the one-norm of
a vector, or column norm of a 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 `k'-norms for `k'
other than one or infinity are not provided.  However, the 2-norm (or
Frobenius norm) is provided for vectors by the `A' (`calc-abs') command.

   The `V C' (`calc-cross') [`cross'] command computes the right-handed
cross product of two vectors, each of which must have exactly three
elements.

   The `&' (`calc-inv') [`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 `&' is a plain number `x', this command simply
computes `1/x'.  This is okay, because the `/' operator also does a
matrix inversion when dividing one by a matrix.

   The `V D' (`calc-mdet') [`det'] command computes the determinant of
a square matrix.

   The `V L' (`calc-mlud') [`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.

   The `V T' (`calc-mtrace') [`tr'] command computes the trace of a
square matrix.  This is defined as the sum of the diagonal elements of
the matrix.

   The `V K' (`calc-kron') [`kron'] command computes the Kronecker
product of two matrices.


File: calc,  Node: Set Operations,  Next: Statistical Operations,  Prev: Vector and Matrix Arithmetic,  Up: Matrix Functions

11.6 Set Operations using Vectors
=================================

Calc includes several commands which interpret vectors as "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 `[b]' from
`[a, b]' always yields the set `[a]' even though if the variables `a'
and `b' both equaled 17, you might expect the answer `[]'.

   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
A, it is treated like the one-element vector `[A]'.  The result is
always a vector, except that if the set consists of a single interval,
the interval itself is returned instead.

   *Note Logical Operations::, for the `in' function which tests if a
certain value is a member of a given set.  To test if the set `A' is a
subset of the set `B', use `vdiff(A, B) = []'.

   The `V +' (`calc-remove-duplicates') [`rdup'] command converts an
arbitrary vector into set notation.  It works by sorting the vector as
if by `V S', then removing duplicates.  (For example, `[a, 5, 4, a,
4.0]' is sorted to `[4, 4.0, 5, a, a]' and then reduced to `[4, 5,
a]').  Overlapping intervals are merged as necessary.  You rarely need
to use `V +' explicitly, since all the other set-based commands apply
`V +' to their inputs before using them.

   The `V V' (`calc-set-union') [`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 `|', then using `V +'.)

   The `V ^' (`calc-set-intersect') [`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 `[]'.  Note that the characters `V' and `^' were
chosen to be close to the conventional mathematical notation for set
union and intersection.

   The `V -' (`calc-set-difference') [`vdiff'] command computes the
difference between two sets.  An object is in the difference `A - B' if
and only if it is in `A' but not in `B'.  Thus subtracting `[y,z]' from
a set will remove the elements `y' and `z' if they are present.  You
can also think of this as a general "set complement" operator; if `A'
is the set of all possible values, then `A - B' is the "complement" of
`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).

   The `V X' (`calc-set-xor') [`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
_not_ both, of the sets.  Objects that occur in both sets "cancel out."

   The `V ~' (`calc-set-complement') [`vcompl'] command computes the
complement of a set with respect to the real numbers.  Thus `vcompl(x)'
is equivalent to `vdiff([-inf .. inf], x)'.  For example, `vcompl([2,
(3 .. 4]])' evaluates to `[[-inf .. 2), (2 .. 3], (4 .. inf]]'.

   The `V F' (`calc-set-floor') [`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 `[2, 6,
7, 8]' is messy, but if you wanted the complement with respect to the
set of integers you could type `V ~ V F' to get `[[-inf .. 1], [3 ..
5], [9 .. inf]]'.

   The `V E' (`calc-set-enumerate') [`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 `-inf' or `inf').

   The `V :' (`calc-set-span') [`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, `vspan([])' returns the
empty interval `[0 .. 0)'.

   The `V #' (`calc-set-cardinality') [`vcard'] command counts the
number of integers in a set.  The result is the length of the vector
that would be produced by `V E', although the computation is much more
efficient than actually producing that vector.

   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.  *Note
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:  `b o' (`calc-or'), `b a'
(`calc-and'), `b d' (`calc-diff'), `b x' (`calc-xor'), and `b n'
(`calc-not'), respectively.  You can use whatever representation for
sets is most convenient to you.

   The `b u' (`calc-unpack-bits') [`vunpack'] command converts an
integer that represents a set in binary into a set in vector/interval
notation.  For example, `vunpack(67)' returns `[[0 .. 1], 6]'.  If the
input is negative, the set it represents is semi-infinite: `vunpack(-4)
= [2 .. inf)'.  Use `V E' afterwards to expand intervals to individual
values if you wish.  Note that this command uses the `b' (binary)
prefix key.

   The `b p' (`calc-pack-bits') [`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 `V F'
(`vfloor').  Beware that a simple input like `[100]' can result in a
huge integer representation (`2^100', a 31-digit integer, in this case).


File: calc,  Node: Statistical Operations,  Next: Reducing and Mapping,  Prev: Set Operations,  Up: Matrix Functions

11.7 Statistical Operations on Vectors
======================================

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
_Data Reduction and Error Analysis for the Physical Sciences_, and
_Numerical Recipes_ by Press, Flannery, Teukolsky and Vetterling.

   The statistical commands use the `u' prefix key followed by a
shifted letter or other character.

   *Note Manipulating Vectors::, for a description of `V H'
(`calc-histogram').

   *Note Curve Fitting::, for the `a F' command for doing least-squares
fits to statistical data.

   *Note Probability Distribution Functions::, for several common
probability distribution functions.

* Menu:

* Single-Variable Statistics::
* Paired-Sample Statistics::


File: calc,  Node: Single-Variable Statistics,  Next: Paired-Sample Statistics,  Prev: Statistical Operations,  Up: Statistical Operations

11.7.1 Single-Variable Statistics
---------------------------------

These functions do various statistical computations on single vectors.
Given a numeric prefix argument, they actually pop 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 `v a 0'; *note 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 M
argument of the random number function `k r'.  In particular, an
interval with integer limits is considered an integer distribution, so
that `[2 .. 6)' is the same as `[2 .. 5]'.  An interval with at least
one floating-point limit is a continuous distribution:  `[2.0 .. 6.0)'
is _not_ the same as `[2.0 .. 5.0]'!

   The `u #' (`calc-vector-count') [`vcount'] command computes the
number of data values represented by the inputs.  For example,
`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.

   The `u +' (`calc-vector-sum') [`vsum'] command computes the sum of
the data values.  The `u *' (`calc-vector-prod') [`vprod'] command
computes the product of the data values.  If the input is a single flat
vector, these are the same as `V R +' and `V R *' (*note Reducing and
Mapping::).

   The `u X' (`calc-vector-max') [`vmax'] command computes the maximum
of the data values, and the `u N' (`calc-vector-min') [`vmin'] command
computes the minimum.  If the argument is an interval, this finds the
minimum or maximum value in the interval.  (Note that `vmax([2..6)) =
5' as described above.)  If the argument is an error form, this returns
plus or minus infinity.

   The `u M' (`calc-vector-mean') [`vmean'] command computes the
average (arithmetic mean) of the data values.  If the inputs are error
forms `x +/- s', this is the weighted mean of the `x' values with
weights `1 / s^2'.  If the inputs are not error forms, this is simply
the sum of the values divided by the count of the values.

   Note that a plain number can be considered an error form with error
`s = 0'.  If the input to `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 `A +/- B' is simply `a'.  The
mean of an interval is the mean of the minimum and maximum values of
the interval.

   The `I u M' (`calc-vector-mean-error') [`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.)  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.)

   The `H u M' (`calc-vector-median') [`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.

   The `H I u M' (`calc-vector-harmonic-mean') [`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.

   The `u G' (`calc-vector-geometric-mean') [`vgmean'] command computes
the geometric mean of the data values.  This is the Nth root of the
product of the values.  This is also equal to the `exp' of the
arithmetic mean of the logarithms of the data values.

   The `H u G' [`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.

   Another commonly used mean, the RMS (root-mean-square), can be
computed for a vector of numbers simply by using the `A' command.

   The `u S' (`calc-vector-sdev') [`vsdev'] command computes the
standard deviation of the data values.  If the values are error forms,
the errors are used as weights just as for `u M'.  This is the _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 `N'
values, divided by `N-1'.

   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 `sqrt(12)'.  The standard deviation of an integer
interval is the same as the standard deviation of a vector of those
integers.

   The `I u S' (`calc-vector-pop-sdev') [`vpsdev'] command computes the
_population_ standard deviation.  It is defined by the same formula as
above but dividing by `N' instead of by `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.

   For error forms and continuous intervals, `vpsdev' works exactly
like `vsdev'.  For integer intervals, it computes the population
standard deviation of the equivalent vector of integers.

   The `H u S' (`calc-vector-variance') [`vvar'] and `H I u S'
(`calc-vector-pop-variance') [`vpvar'] commands compute the variance of
the data values.  The variance is the square 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.)

   The `vflat' algebraic function returns a vector of its arguments,
interpreted in the same way as the other functions in this section.
For example, `vflat(1, [2, [3, 4]], 5)' returns `[1, 2, 3, 4, 5]'.


File: calc,  Node: Paired-Sample Statistics,  Prev: Single-Variable Statistics,  Up: Statistical Operations

11.7.2 Paired-Sample Statistics
-------------------------------

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 Nx2 matrix of data values.  Once again, variable names
can be used in place of actual vectors and matrices.

   The `u C' (`calc-vector-covariance') [`vcov'] command computes the
sample covariance of two vectors.  The covariance of vectors X and Y is
the sum of the products of the differences between the elements of X
and the mean of X times the differences between the corresponding
elements of Y and the mean of Y, all divided by `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 X and 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.

   The `I u C' (`calc-vector-pop-covariance') [`vpcov'] command
computes the population covariance, which is the same as the sample
covariance computed by `u C' except dividing by `N' instead of `N-1'.

   The `H u C' (`calc-vector-correlation') [`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.)


File: calc,  Node: Reducing and Mapping,  Next: Vector and Matrix Formats,  Prev: Statistical Operations,  Up: Matrix Functions

11.8 Reducing and Mapping Vectors
=================================

The commands in this section allow for more general operations on the
elements of vectors.

   The simplest of these operations is `V A' (`calc-apply') [`apply'],
which applies a given operator to the elements of a vector.  For
example, applying the hypothetical function `f' to the vector
`[1, 2, 3]' would produce the function call `f(1, 2, 3)'.  Applying the
`+' function to the vector `[a, b]' gives `a + b'.  Applying `+' to the
vector `[a, b, c]' is an error, since the `+' function expects exactly
two arguments.

   While `V A' is useful in some cases, you will usually find that
either `V R' or `V M', described below, is closer to what you want.

* Menu:

* Specifying Operators::
* Mapping::
* Reducing::
* Nesting and Fixed Points::
* Generalized Products::


File: calc,  Node: Specifying Operators,  Next: Mapping,  Prev: Reducing and Mapping,  Up: Reducing and Mapping

11.8.1 Specifying Operators
---------------------------

Commands in this section (like `V A') prompt you to press the key
corresponding to the desired operator.  Press `?' 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, `V A H C' uses the
hyperbolic cosine operator, `cosh'.  (Since `cosh' expects one
argument, `V A H C' requires a vector with a single element as its
argument.)

   You can press `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 `Z F' command.  (*Note Algebraic
Definitions::.)  If you give a name for which no function has been
defined, the result is left in symbolic form, as in `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., `V M 3 x f
<RET>' calls `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 `v e' [`vexp']
function accepts two or three arguments; if you want to map with the
three-argument version, you will have to type `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
`'' (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 `x + 2y^x'.  The
default argument list would be `(x y)', which means that if this
function is applied to the arguments `[3, 10]' the result will be `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 `Z F'.)

   Another way to specify the arguments to the formula you enter is with
`$', `$$', and so on.  For example, `V A ' $$ + 2$^$$' has the same
effect as the previous example.  The argument list is automatically
taken to be `($$ $)'.  (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 `$' 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 `V A $' or
related command then start at the second-to-top stack position.  You
will still be prompted for an argument list.

   A function can be written without a name using the notation `<#1 -
#2>', which means "a function of two arguments that computes the first
argument minus the second argument."  The symbols `#1' and `#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:  `<x, y : x - y>'.  When you type `V A ' $$ + 2$^$$ <RET>', Calc
builds the nameless function `<#1 + 2 #2^#1>' as the function to map
across the vectors.  When you type `V A ' x + 2y^x <RET> <RET>', Calc
builds the nameless function `<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 `#' in place of `#1'.
(Note that `< >' notation is also used for date forms.  Calc tells that
`<STUFF>' is a nameless function by the presence of `#' signs inside
STUFF, or by the fact that STUFF begins with a list of variables
followed by a colon.)

   You can type a nameless function directly to `V A '', or put one on
the stack and use it with `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 `V A '', you can omit
the `< >' marks if you use `#' notation for the arguments, so that `V A
' #1+#2 <RET>' is the same as `V A ' <#1+#2> <RET>', which in turn is
the same as `V A ' $$+$ <RET>'.

   The internal format for `<x, y : x + y>' is `lambda(x, y, x + y)'.
(The word `lambda' derives from Lisp notation and the theory of
functions.)  The internal format for `<#1 + #2>' is `lambda(ArgA, ArgB,
ArgA + ArgB)'.  Note that there is no actual Calc function called
`lambda'; the whole point is that the `lambda' expression is used in
its symbolic form, not evaluated for an answer until it is applied to
specific arguments by a command like `V A' or `V M'.

   (Actually, `lambda' does have one special property:  Its arguments
are never evaluated; for example, putting `<(2/3) #>' on the stack will
not simplify the `2/3' until the nameless function is actually called.)

   As usual, commands like `V A' have algebraic function name
equivalents.  For example, `V A k g' with an argument of `v' is
equivalent to `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 `<#^3+1>'.  Operators that
are normally written as algebraic symbols have the names `add', `sub',
`mul', `div', `pow', `neg', `mod', and `vconcat'.

   The `call' function builds a function call out of several arguments:
`call(gcd, x, y)' is the same as `apply(gcd, [x, y])', which in turn is
the same as `gcd(x, y)'.  The first argument of `call', like the other
functions described here, may be either a variable naming a function,
or a nameless function (`call(<#1+2#2>, x, y)' is the same as `x + 2y').

   (Experts will notice that it's not quite proper to use a variable to
name a function, since the name `gcd' corresponds to the Lisp variable
`var-gcd' but to the Lisp function `calcFunc-gcd'.  Calc automatically
makes this translation, so you don't have to worry about it.)


File: calc,  Node: Mapping,  Next: Reducing,  Prev: Specifying Operators,  Up: Reducing and Mapping

11.8.2 Mapping
--------------

The `V M' (`calc-map') [`map'] command applies a given operator
elementwise to one or more vectors.  For example, mapping `A' [`abs']
produces a vector of the absolute values of the elements in the input
vector.  Mapping `+' 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, `[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.

   If any argument to `V M' is a matrix, the operator is normally mapped
across all elements of the matrix.  For example, given the matrix `[[1,
-2, 3], [-4, 5, -6]]', `V M A' takes six absolute values to produce
another 3x2 matrix, `[[1, 2, 3], [4, 5, 6]]'.

   The command `V M _' [`mapr'] (i.e., type an underscore at the
operator prompt) maps by rows instead.  For example, `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 `[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, `v
v' reverses a vector, so `V M _ v v' would reverse each row of the
matrix to get a new matrix, `[[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 `V M _'
if you want to map a function across the whole strings or sets rather
than across their individual elements.

   The command `V M :' [`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, `V M : A' takes the absolute
values of the three columns of the matrix, treating each as a 2-vector,
and `V M : v v' reverses the columns to get the matrix `[[-4, 5, -6],
[1, -2, 3]]'.

   (The symbols `_' and `:' 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 `V M'.)

   The `_' and `:' 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 `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 `V M _') or columns (for `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 `V M'.  For example, `V M _ V A +' applies `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 `V M', it automatically uses map-by-rows mode if you don't specify
otherwise; thus `V M V A +' is equivalent to `V M _ V A +'.  (If you
really want to map-by-elements another mapping command, you can use a
triple-nested mapping command:  `V M V M V A +' means to map `V M V A
+' over the rows of the matrix; in turn, `V A +' is mapped over the
elements of each row.)

   Previous versions of Calc had "map across" and "map down" modes that
are now considered obsolete; the old "map across" is now simply `V M V
A', and "map down" is now `V M : V A'.  The algebraic functions `mapa'
and `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 `:' and `_'
modifiers apply only to the current mapping command.  The default `V M'
always means map-by-elements.

   *Note Algebraic Manipulation::, for the `a M' command, which is like
`V M' but for equations and inequalities instead of vectors.  *Note
Storing Variables::, for the `s m' command which modifies a variable's
stored value using a `V M'-like operator.


File: calc,  Node: Reducing,  Next: Nesting and Fixed Points,  Prev: Mapping,  Up: Reducing and Mapping

11.8.3 Reducing
---------------

The `V R' (`calc-reduce') [`reduce'] command applies a given binary
operator across all the elements of a vector.  A binary operator is a
function such as `+' or `max' which takes two arguments.  For example,
reducing `+' over a vector computes the sum of the elements of the
vector.  Reducing `-' computes the first element minus each of the
remaining elements.  Reducing `max' computes the maximum element and so
on.  In general, reducing `f' over the vector `[a, b, c, d]' produces
`f(f(f(a, b), c), d)'.

   The `I V R' [`rreduce'] command is similar to `V R' except that
works from right to left through the vector.  For example, plain `V R
-' on the vector `[a, b, c, d]' produces `a - b - c - d' but `I V R -'
on the same vector produces `a - (b - (c - d))', or `a - b + c - d'.
This "alternating sum" occurs frequently in power series expansions.

   The `V U' (`calc-accumulate') [`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 `+' over the vector `[a, b, c,
d]' produces the vector `[a, a + b, a + b + c, a + b + c + d]'.

   The `I V U' [`raccum'] command does a right-to-left accumulation.
For example, `I V U -' on the vector `[a, b, c, d]' produces the vector
`[a - b + c - d, b - c + d, c - d, d]'.

   As for `V M', `V R' normally reduces a matrix elementwise.  For
example, given the matrix `[[a, b, c], [d, e, f]]', `V R +' will
compute `a + b + c + d + e + f'.  You can type `V R _' or `V R :' to
modify this behavior.  The `V R _' [`reducea'] command reduces "across"
the matrix; it reduces each row of the matrix as a vector, then
collects the results.  Thus `V R _ +' of this matrix would produce `[a
+ b + c, d + e + f]'.  Similarly, `V R :' [`reduced'] reduces down; `V
R : +' would produce `[a + d, b + e, c + f]'.

   There is a third "by rows" mode for reduction that is occasionally
useful; `V R =' [`reducer'] simply reduces the operator over the rows
of the matrix themselves.  Thus `V R = +' on the above matrix would get
the same result as `V R : +', since adding two row vectors is
equivalent to adding their elements.  But `V R = *' would multiply the
two rows (to get a single number, their dot product), while `V R : *'
would produce a vector of the products of the columns.

   These three matrix reduction modes work with `V R' and `I V R', but
they are not currently supported with `V U' or `I V U'.

   The obsolete reduce-by-columns function, `reducec', is still
supported but there is no way to get it through the `V R' command.

   The commands `C-x * :' and `C-x * _' are equivalent to typing `C-x *
r' to grab a rectangle of data into Calc, and then typing `V R : +' or
`V R _ +', respectively, to sum the columns or rows of the matrix.
*Note Grabbing From Buffers::.


File: calc,  Node: Nesting and Fixed Points,  Next: Generalized Products,  Prev: Reducing,  Up: Reducing and Mapping

11.8.4 Nesting and Fixed Points
-------------------------------

The `H V R' [`nest'] command applies a function to a given argument
repeatedly.  It takes two values, `a' and `n', from the stack, where
`n' must be an integer.  It then applies the function nested `n' times;
if the function is `f' and `n' is 3, the result is `f(f(f(a)))'.  The
number `n' may be negative if Calc knows an inverse for the function
`f'; for example, `nest(sin, a, -2)' returns `arcsin(arcsin(a))'.

   The `H V U' [`anest'] command is an accumulating version of `nest':
It returns a vector of `n+1' values, e.g., `[a, f(a), f(f(a)),
f(f(f(a)))]'.  If `n' is negative and `F' is the inverse of `f', then
the result is of the form `[a, F(a), F(F(a)), F(F(F(a)))]'.

   The `H I V R' [`fixp'] command is like `H V R', except that it takes
only an `a' value from the stack; the function is applied until it
reaches a "fixed point," i.e., until the result no longer changes.

   The `H I V U' [`afixp'] command is an accumulating `fixp'.  The
first element of the return vector will be the initial value `a'; the
last element will be the final result that would have been returned by
`fixp'.

   For example, 0.739085 is a fixed point of the cosine function (in
radians): `cos(0.739085) = 0.739085'.  You can find this value by
putting, say, 1.0 on the stack and typing `H I V U C'.  (We use the
accumulating version so we can see the intermediate results:  `[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 `(x + 5/x) / 2'.  Putting a guess of 1 on the stack and typing
`H I V R ' ($ + 5/$)/2 <RET>' quickly yields the result 2.23607.  This
is equivalent to using the `a R' (`calc-find-root') command to find a
root of the equation `x^2 = 5'.

   These examples used numbers for `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 `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 `C-g' to stop the Calculator.

   The algebraic `fixp' function takes two optional arguments, `n' and
`tol'.  The first is the maximum number of steps to be allowed, and
must be either an integer or the symbol `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, `fixp(<(# + A/#)/2>, B, 20, 1e-10)'
computes the square root of `A' given the initial guess `B', stopping
when the result is correct within the specified tolerance, or when 20
steps have been taken, whichever is sooner.


File: calc,  Node: Generalized Products,  Prev: Nesting and Fixed Points,  Up: Reducing and Mapping

11.8.5 Generalized Products
---------------------------

The `V O' (`calc-outer-product') [`outer'] command applies a given
binary operator to all possible pairs of elements from two vectors, to
produce a matrix.  For example, `V O *' with `[a, b]' and `[x, y, z]'
on the stack produces a multiplication table: `[[a x, a y, a z], [b x,
b y, b z]]'.  Element R,C of the result matrix is obtained by applying
the operator to element R of the lefthand vector and element C of the
righthand vector.

   The `V I' (`calc-inner-product') [`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 `*' and `+',
respectively, the result is a standard matrix multiplication.  Element
R,C of the result matrix is obtained by mapping the multiplicative
operator across row R of the lefthand matrix and column C of the
righthand matrix, and then reducing with the additive operator.  Just
as for the standard `*' command, this can also do a vector-matrix or
matrix-vector inner product, or a vector-vector generalized dot product.

   Since `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 `$' 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.


File: calc,  Node: Vector and Matrix Formats,  Prev: Reducing and Mapping,  Up: Matrix Functions

11.9 Vector and Matrix Display Formats
======================================

Commands for controlling vector and matrix display use the `v' prefix
instead of the usual `d' prefix.  But they are display modes; in
particular, they are influenced by the `I' and `H' prefix keys in the
same way (*note Display Modes::).  Matrix display is also influenced by
the `d O' (`calc-flat-language') mode; *note Normal Language Modes::.

   The commands `v <' (`calc-matrix-left-justify'), `v >'
(`calc-matrix-right-justify'), and `v =' (`calc-matrix-center-justify')
control whether matrix elements are justified to the left, right, or
center of their columns.

   The `v [' (`calc-vector-brackets') command turns the square brackets
that surround vectors and matrices displayed in the stack on and off.
The `v {' (`calc-vector-braces') and `v (' (`calc-vector-parens')
commands use curly braces or parentheses, respectively, instead of
square brackets.  For example, `v {' might be used in preparation for
yanking a matrix into a buffer running Mathematica.  (In fact, the
Mathematica language mode uses this mode; *note 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.

   The `v ]' (`calc-matrix-brackets') command controls the "big" style
display of matrices, for matrices which have more than one row.  It
prompts for a string of code letters; currently implemented letters are
`R', which enables brackets on each row of the matrix; `O', which
enables outer brackets in opposite corners of the matrix; and `C',
which enables commas or semicolons at the ends of all rows but the
last.  The default format is `RO'.  (Before Calc 2.00, the format was
fixed at `ROC'.)  Here are some example matrices:

     [ [ 123,  0,   0  ]       [ [ 123,  0,   0  ],
       [  0,  123,  0  ]         [  0,  123,  0  ],
       [  0,   0,  123 ] ]       [  0,   0,  123 ] ]

              RO                        ROC

       [ 123,  0,   0            [ 123,  0,   0 ;
          0,  123,  0               0,  123,  0 ;
          0,   0,  123 ]            0,   0,  123 ]

               O                        OC

       [ 123,  0,   0  ]           123,  0,   0
       [  0,  123,  0  ]            0,  123,  0
       [  0,   0,  123 ]            0,   0,  123

               R                       blank

Note that of the formats shown here, `RO', `ROC', and `OC' are all
recognized as matrices during reading, while the others are useful for
display only.

   The `v ,' (`calc-vector-commas') command turns commas on and off in
vector and matrix display.

   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, `[a b]' could be a vector of the
one formula `a b', or it could be a vector of two variables with commas
turned off.  Calc will display the former case as `[(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 `P' to the
control string you give to `v ]' (as described above).

   The `v .' (`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:  `[a, b, c, ..., z]'.  When very large vectors are
involved this will substantially improve Calc's display speed.

   The `t .' (`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 `t y'
(`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.

   The `v /' (`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.


File: calc,  Node: Algebra,  Next: Units,  Prev: Matrix Functions,  Up: Top

12 Algebra
**********

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 "rewrite rule" mechanism is discussed.

   The algebraic commands use the `a' key prefix; selection commands
use the `j' (for "just a letter that wasn't used for anything else")
prefix.

   *Note Editing Stack Entries::, to see how to manipulate formulas
using regular Emacs editing commands.

   When doing algebraic work, you may find several of the Calculator's
modes to be helpful, including Algebraic Simplification mode (`m A') or
No-Simplification mode (`m O'), Algebraic entry mode (`m a'), Fraction
mode (`m f'), and Symbolic mode (`m s').  *Note Mode Settings::, for
discussions of these modes.  You may also wish to select Big display
mode (`d B').  *Note Normal Language Modes::.

* Menu:

* Selecting Subformulas::
* Algebraic Manipulation::
* Simplifying Formulas::
* Polynomials::
* Calculus::
* Solving Equations::
* Numerical Solutions::
* Curve Fitting::
* Summations::
* Logical Operations::
* Rewrite Rules::


File: calc,  Node: Selecting Subformulas,  Next: Algebraic Manipulation,  Prev: Algebra,  Up: Algebra

12.1 Selecting Sub-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::


File: calc,  Node: Making Selections,  Next: Changing Selections,  Prev: Selecting Subformulas,  Up: Selecting Subformulas

12.1.1 Making Selections
------------------------

To select a sub-formula, move the Emacs cursor to any character in that
sub-formula, and press `j s' (`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 mode (`d B').  Suppose you enter the following
formula:

                3    ___
         (a + b)  + V c
     1:  ---------------
             2 x + 1

(by typing `' ((a+b)^3 + sqrt(c)) / (2x+1)').  If you move the cursor
to the letter `b' and press `j s', the display changes to

                .    ...
         .. . b.  . . .
     1*  ...............
             . . . .

Every character not part of the sub-formula `b' has been changed to a
dot. (If the customizable variable
`calc-highlight-selections-with-faces' is non-nil, then the characters
not part of the sub-formula are de-emphasized by using a less
noticeable face instead of using dots. *note Displaying Selections::.)
The `*' 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 `Sel' also
appears in the mode line because the stack may not be visible.  *note
Embedded Mode::.)

   If you had instead placed the cursor on the parenthesis immediately
to the right of the `b', the selection would have been:

                .    ...
         (a + b)  . . .
     1*  ...............
             . . . .

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 `+' sign would
have had the same effect.

   (Strictly speaking, the Emacs cursor is really the manifestation of
the Emacs "point," which is a position _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 N, the selection is expanded
to the Nth enclosing sub-formula.  Thus, positioning the cursor on the
`b' and typing `C-u 1 j s' will select `a + b'; typing `C-u 2 j s' will
select `(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 `.' 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.

   The `j a' (`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 `j s',
then move to the other and press `j a'.  This is roughly analogous to
using `C-@' (`set-mark-command') to select the two ends of a region of
text during normal Emacs editing.

   The `j o' (`calc-select-once') command selects a formula in exactly
the same way as `j s', except that the selection will last only as long
as the next command that uses it.  For example, `j o 1 +' is a handy
way to add one to the sub-formula indicated by the cursor.

   (A somewhat more precise definition: The `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 `j a' and `j O' clear this flag.)

   The `j S' (`calc-select-here-maybe') and `j O'
(`calc-select-once-maybe') commands are equivalent to `j s' and `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 `j r' (`calc-rewrite-selection'; *note Selections with Rewrite
Rules::) and is mainly intended to be used in keyboard macros that
implement your own selection-oriented commands.

   Selection of sub-formulas normally treats associative terms like `a
+ b - c + d' and `x * y * z' as single levels of the formula.  If you
place the cursor anywhere inside `a + b - c + d' except on one of the
variable names and use `j s', you will select the entire four-term sum.

   The `j b' (`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 `((a + b) - c) + d' and `x * (y *
z)'.  (Note that for certain obscure reasons, by default Calc treats
multiplication as right-associative.)  Once you have enabled `j b'
mode, selecting with the cursor on the `-' sign would only select the
`a + b - c' portion, which makes sense when the deep structure of the
sum is considered.  There is no way to select the `b - c + d' portion;
although this might initially look like just as legitimate a sub-formula
as `a + b - c', the deep structure shows that it isn't.  The `d U'
command can be used to view the deep structure of any formula (*note
Normal Language Modes::).

   When `j b' mode has not been enabled, the deep structure is
generally hidden by the selection commands--what you see is what you
get.

   The `j u' (`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 Nth
stack element rather than using the cursor position.

   The `j c' (`calc-clear-selections') command unselects all stack
elements.


File: calc,  Node: Changing Selections,  Next: Displaying Selections,  Prev: Making Selections,  Up: Selecting Subformulas

12.1.2 Changing Selections
--------------------------

Once you have selected a sub-formula, you can expand it using the `j m'
(`calc-select-more') command.  If `a + b' is selected, pressing `j m'
repeatedly works as follows:

                3    ...                3    ___                3    ___
         (a + b)  . . .          (a + b)  + V c          (a + b)  + V c
     1*  ...............     1*  ...............     1*  ---------------
             . . . .                 . . . .                 2 x + 1

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 `*' character is still there on the line number.

   With a numeric prefix argument N, `j m' expands N times (or until
the entire formula is selected).  Note that `j s' with argument N is
equivalent to plain `j s' followed by `j m' with argument N.  If `j m'
is used when there is no current selection, it is equivalent to `j s'.

   Even though `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, `j m' when the cursor is not on
any stack element operates on the top stack element.

   The `j l' (`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 `j m'.  If the cursor is not inside the current selection,
the command de-selects the formula.

   The `j 1' through `j 9' (`calc-select-part') commands select the Nth
sub-formula of the current selection.  They are like `j l'
(`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 `a + b + c' or `f(a, b, c)' or `[a, b, c]', then
`j 1' selects `a', `j 2' selects `b', and `j 3' selects `c'; in each of
these cases, `j 4' through `j 9' would be errors.

   If there is no current selection, `j 1' through `j 9' select the Nth
top-level sub-formula.  (In other words, they act as if the entire
stack entry were selected first.)  To select the Nth sub-formula where
N is greater than nine, you must instead invoke `j 1' with N as a
numeric prefix argument.

   The `j n' (`calc-select-next') and `j p' (`calc-select-previous')
commands change the current selection to the next or previous
sub-formula at the same level.  For example, if `b' is selected in
`2 + a*b*c + x', then `j n' selects `c'.  Further `j n' commands would
be in error because, even though there is something to the right of `c'
(namely, `x'), it is not at the same level; in this case, it is not a
term of the same product as `b' and `c'.  However, `j m' (to select the
whole product `a*b*c' as a term of the sum) followed by `j n' would
successfully select the `x'.

   Similarly, `j p' moves the selection from the `b' in this sample
formula to the `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 `j n' command is completely analogous
to Info's `n' command.  Likewise, `j p' maps to `p', `j 2' maps to `2',
and Info's `u' is like `j m'.  (Note that `j u' stands for
`calc-unselect', not "up".)  The Info `m' command is somewhat similar
to Calc's `j s' and `j l'; in each case, you can jump directly to a
sub-component of the hierarchy simply by pointing to it with the cursor.


File: calc,  Node: Displaying Selections,  Next: Operating on Selections,  Prev: Changing Selections,  Up: Selecting Subformulas

12.1.3 Displaying Selections
----------------------------

The `j d' (`calc-show-selections') command controls how selected
sub-formulas are displayed.  One of the alternatives is illustrated in
the above examples; if we press `j d' we switch to the other style in
which the selected portion itself is obscured by `#' signs:

                3    ...                  #    ___
         (a + b)  . . .            ## # ##  + V c
     1*  ...............       1*  ---------------
             . . . .                   2 x + 1
If the customizable variable `calc-highlight-selections-with-faces' is
non-nil, then the non-selected portion of the formula will be
de-emphasized by using a less noticeable face (`calc-nonselected-face')
instead of dots and the selected sub-formula will be highlighted by
using a more noticeable face (`calc-selected-face') instead of `#'
signs. (*note Customizing Calc::.)


File: calc,  Node: Operating on Selections,  Next: Rearranging with Selections,  Prev: Displaying Selections,  Up: Selecting Subformulas

12.1.4 Operating on Selections
------------------------------

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.)

   The `j e' (`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 `*' markers on the line
numbers are gone, even though selections are visible.  To reactivate
the selections, press `j e' again.

   To extract a sub-formula as a new formula, simply select the
sub-formula and press <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 <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.

                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)

   In this example we select a sub-formula of our original example,
enter a new formula, <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 `j e' before and after.

   The `j '' (`calc-enter-selection') command is another way to replace
a selected sub-formula.  This command does an algebraic entry just like
the regular `'' key.  When you press <RET>, the formula you type
replaces the original selection.  You can use the `$' 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 `j ''.

   The `j `' (`calc-edit-selection') command is a similar analogue of
the ``' (`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 <DEL>.  This generally replaces the
sub-formula with the constant zero, but in a few suitable contexts it
uses the constant one instead.  The <DEL> key automatically deselects
and re-simplifies the entire formula afterwards.  Thus:

                   ###
         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

   In this example, we first delete the `sqrt(c)' term; Calc
accomplishes this by replacing `sqrt(c)' with zero and resimplifying.
We then delete the `x' in the numerator; since this is part of a
product, Calc replaces it with `1' and resimplifies.

   If you select an element of a vector and press <DEL>, that element
is deleted from the vector.  If you delete one side of an equation or
inequality, only the opposite side remains.

   The `j <DEL>' (`calc-del-selection') command is like <DEL> but with
the auto-selecting behavior of `j '' and `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.

   (There is also an auto-selecting `j <RET>' (`calc-copy-selection')
command.)

   Normal arithmetic operations also apply to sub-formulas.  Here we
select the denominator, press `5 -' to subtract five from the
denominator, press `n' to negate the denominator, then press `Q' to
take the square root.

          .. .           .. .           .. .             .. .
     1*  .......    1*  .......    1*  .......    1*  ..........
         2 x + 1        2 x - 4        4 - 2 x         _________
                                                      V 4 - 2 x

   Certain types of operations on selections are not allowed.  For
example, for an arithmetic function like `-' 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 `2 x' term of our sample
formula by selecting it and pressing `n' (`calc-change-sign').

            .. .                .. .
     1*  ..........      1*  ...........
          .........           ..........
         . . . 2 x           . . . -2 x

   Unselecting the sub-formula reveals that the minus sign, which would
normally have canceled out with the subtraction automatically, has not
been able to do so because the subtraction was not part of the selected
portion.  Pressing `=' (`calc-evaluate') or doing any other
mathematical operation on the whole formula will cause it to be
simplified.

            17 y                17 y
     1:  -----------     1:  ----------
          __________          _________
         V 4 - -2 x          V 4 + 2 x


File: calc,  Node: Rearranging with Selections,  Prev: Operating on Selections,  Up: Selecting Subformulas

12.1.5 Rearranging Formulas using Selections
--------------------------------------------

The `j R' (`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 `j '' and `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 `a' and type `j R', then repeat.

     1:  a + b - c          1:  b + a - c          1:  b - c + a

Note that in the final step above, the `a' is switched with the `c' but
the signs are adjusted accordingly.  When moving terms of sums and
products, `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.

     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)

   The `j L' (`calc-commute-left') command is like `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.

   The `j D' (`calc-sel-distribute') command mixes the selected sum or
product into the surrounding formula using the distributive law.  For
example, in `a * (b - c)' with the `b - c' selected, the result is `a b
- a c'.  This also distributes products or quotients into surrounding
powers, and can also do transformations like `exp(a + b)' to `exp(a)
exp(b)', where `a + b' is the selected term, and `ln(a ^ b)' to `ln(a)
b', where `a ^ b' is the selected term.

   For multiple-term sums or products, `j D' takes off one term at a
time:  `a * (b + c - d)' goes to `a * (c - d) + a b' with the `c - d'
selected so that you can type `j D' repeatedly to expand completely.
The `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.

   The `j D' command is implemented using rewrite rules.  *Note
Selections with Rewrite Rules::.  The rules are stored in the Calc
variable `DistribRules'.  A convenient way to view these rules is to
use `s e' (`calc-edit-variable') which displays and edits the stored
value of a variable.  Press `C-c C-c' to return from editing mode; be
careful not to make any actual changes or else you will affect the
behavior of future `j D' commands!

   To extend `j D' to handle new cases, just edit `DistribRules' as
described above.  You can then use the `s p' command to save this
variable's value permanently for future Calc sessions.  *Note
Operations on Variables::.

   The `j M' (`calc-sel-merge') command is the complement of `j D';
given `a b - a c' with either `a b' or `a c' selected, the result is `a
* (b - c)'.  Once again, `j M' can also merge calls to functions like
`exp' and `ln'; examine the variable `MergeRules' to see all the
relevant rules.

   The `j C' (`calc-sel-commute') command swaps the arguments of the
selected sum, product, or equation.  It always behaves as if `j b' mode
were in effect, i.e., the sum `a + b + c' is treated as the nested sums
`(a + b) + c' by this command.  If you put the cursor on the first `+',
the result is `(b + a) + c'; if you put the cursor on the second `+',
the result is `c + (a + b)' (which the default simplifications will
rearrange to `(c + a) + b').  The relevant rules are stored in the
variable `CommuteRules'.

   You may need to turn default simplifications off (with the `m O'
command) in order to get the full benefit of `j C'.  For example,
commuting `a - b' produces `-b + a', but the default simplifications
will "simplify" this right back to `a - b' if you don't turn them off.
The same is true of some of the other manipulations described in this
section.

   The `j N' (`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 `exp(a - b)' where
`a - b' is selected, the result is `1 / exp(b - a)'.  By contrast,
selecting a term and using the regular `n' (`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 `NegateRules'.

   The `j &' (`calc-sel-invert') command is similar to `j N' except it
takes the reciprocal of the selected term.  For example, given `a -
ln(b)' with `b' selected, the result is `a + ln(1/b)'.  The rules
variable is `InvertRules'.

   The `j E' (`calc-sel-jump-equals') command moves the selected term
from one side of an equation to the other.  Given `a + b = c + d' with
`c' selected, the result is `a + b - c = d'.  This command also works
if the selected term is part of a `*', `/', or `^' formula.  The
relevant rules variable is `JumpRules'.

   The `j I' (`calc-sel-isolate') command isolates the selected term on
its side of an equation.  It uses the `a S' (`calc-solve-for') command
to solve the equation, and the Hyperbolic flag affects it in the same
way.  *Note Solving Equations::.  When it applies, `j I' is often
easier to use than `j E'.  It understands more rules of algebra, and
works for inequalities as well as equations.

   The `j *' (`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 `a
s' (`calc-simplify') before re-forming the quotient or equation.  You
can suppress this simplification by providing a prefix argument: `C-u j
*'.  There is also a `j /' (`calc-sel-div-both-sides') which is similar
to `j *' but dividing instead of multiplying by the factor you enter.

   If the selection is a quotient with numerator 1, then Calc's default
simplifications would normally cancel the new factors.  To prevent
this, when the `j *' command is used on a selection whose numerator is
1 or -1, the denominator is expanded at the top level using the
distributive law (as if using the `C-u 1 a x' command).  Suppose the
formula on the stack is `1 / (a + 1)' and you wish to multiplying the
top and bottom by `a - 1'.  Calc's default simplifications would
normally change the result `(a - 1) /(a + 1) (a - 1)' back to the
original form by cancellation; when `j *' is used, Calc expands the
denominator to  `a (a - 1) + a - 1' to prevent this.

   If you wish the `j *' command to completely expand the denominator
of a quotient you can call it with a zero prefix: `C-u 0 j *'.  For
example, if the formula on the stack is `1 / (sqrt(a) + 1)', you may
wish to eliminate the square root in the denominator by multiplying the
top and bottom by `sqrt(a) - 1'.  If you did this simply by using a
simple `j *' command, you would get `(sqrt(a)-1)/ (sqrt(a) (sqrt(a) -
1) + sqrt(a) - 1)'.  Instead, you would probably want to use `C-u 0 j
*', which would expand the bottom and give you the desired result
`(sqrt(a)-1)/(a-1)'.  More generally, if `j *' is called with an
argument of a positive integer N, then the denominator of the
expression will be expanded N times (as if with the `C-u N a x'
command).

   If the selection is an inequality, `j *' and `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.)  *Note 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.

   The `j +' (`calc-sel-add-both-sides') and `j -'
(`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.

   The `j U' (`calc-sel-unpack') command replaces the selected function
call with its argument.  For example, given `a + sin(x^2)' with
`sin(x^2)' selected, the result is `a + x^2'.  (The `x^2' will remain
selected; if you wanted to change the `sin' to `cos', just press `C'
now to take the cosine of the selected part.)

   The `j v' (`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 `m O'
command.  This command is just an auto-selecting version of the `a v'
command (*note Algebraic Manipulation::).

   With a numeric prefix argument of 2, `C-u 2 j v' applies the `a s'
(`calc-simplify') command to the selected sub-formula.  With a prefix
argument of 3 or more, e.g., `C-u j v' applies the `a e'
(`calc-simplify-extended') command.  *Note Simplifying Formulas::.
With a negative prefix argument it simplifies at the top level only,
just as with `a v'.  Here the "top" level refers to the top level of
the selected sub-formula.

   The `j "' (`calc-sel-expand-formula') command is to `a "' (*note
Algebraic Manipulation::) what `j v' is to `a v'.

   You can use the `j r' (`calc-rewrite-selection') command to define
other algebraic operations on sub-formulas.  *Note Rewrite Rules::.


File: calc,  Node: Algebraic Manipulation,  Next: Simplifying Formulas,  Prev: Selecting Subformulas,  Up: Algebra

12.2 Algebraic Manipulation
===========================

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.

   The `a v' (`calc-alg-evaluate') command performs the normal default
simplifications on a formula; for example, `a - -b' is changed to `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 `m O' command.  *Note Simplification
Modes::.

   It is often more convenient to type `=', which is like `a v' but
which also substitutes stored values for variables in the formula.  Use
`a v' if you want the variables to ignore their stored values.

   If you give a numeric prefix argument of 2 to `a v', it simplifies
as if in Algebraic Simplification mode.  This is equivalent to typing
`a s'; *note Simplifying Formulas::.  If you give a numeric prefix of 3
or more, it uses Extended Simplification mode (`a e').

   If you give a negative prefix argument -1, -2, or -3, it simplifies
in the corresponding mode but only works on the top-level function call
of the formula.  For example, `(2 + 3) * (2 + 3)' will simplify to `(2
+ 3)^2', without simplifying the sub-formulas `2 + 3'.  As another
example, typing `V R +' to sum the vector `[1, 2, 3, 4]' produces the
formula `reduce(add, [1, 2, 3, 4])' in No-Simplify mode.  Using `a v'
will evaluate this all the way to 10; using `C-u - a v' will evaluate
it only to `1 + 2 + 3 + 4'.  (*Note Reducing and Mapping::.)

   The `=' command corresponds to the `evalv' function, and the related
`N' command, which is like `=' but temporarily disables Symbolic mode
(`m s') during the evaluation, corresponds to the `evalvn' function.
(These commands interpret their prefix arguments differently than `a
v'; `=' treats the prefix as the number of stack elements to evaluate
at once, and `N' treats it as a temporary different working precision.)

   The `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
`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, `evalvn(pi -
3.1415)' at a precision of 12 will return `9.265359e-5'; `evalvn(pi -
3.1415, 30)' will return `9.26535897932e-5' (computing a 25-digit
result which is then rounded down to 12); and `evalvn(pi - 3.1415,
[-2])' will return `9.2654e-5'.

   The `a "' (`calc-expand-formula') command expands functions into
their defining formulas wherever possible.  For example, `deg(x^2)' is
changed to `180 x^2 / pi'.  Most functions, like `sin' and `gcd', are
not defined by simple formulas and so are unaffected by this command.
One important class of functions which _can_ be expanded is the
user-defined functions created by the `Z F' command.  *Note Algebraic
Definitions::.  Other functions which `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 `a "' in the same way as it does `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.

   The `a M' (`calc-map-equation') [`mapeq'] command applies a given
function or operator to one or more equations.  It is analogous to `V
M', which operates on vectors instead of equations.  *note Reducing and
Mapping::.  For example, `a M S' changes `x = y+1' to `sin(x) =
sin(y+1)', and `a M +' with `x = y+1' and `6' on the stack produces
`x+6 = y+7'.  With two equations on the stack, `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
`<=' with a `<' or `!=' (not-equal) produces a `<'.  If inequalities
with opposite direction (e.g., `<' and `>') are mapped, the direction
of the second inequality is reversed to match the first:  Using `a M +'
on `a < b' and `a > 2' reverses the latter to get `2 < a', which then
allows the combination `a + 2 < b + a', which the `a s' command can
then simplify to get `2 < b'.

   Using `a M *', `a M /', `a M n', or `a M &' to negate or invert an
inequality will reverse the direction of the inequality.  Other
adjustments to inequalities are _not_ done automatically; `a M S' will
change `x < y' to `sin(x) < sin(y)' even though this is not true for
all values of the variables.

   With the Hyperbolic flag, `H a M' [`mapeqp'] does a plain mapping
operation without reversing the direction of any inequalities.  Thus,
`H a M &' would change `x > 2' to `1/x > 0.5'.  (This change is
mathematically incorrect, but perhaps you were fixing an inequality
which was already incorrect.)

   With the Inverse flag, `I a M' [`mapeqr'] always reverses the
direction of the inequality.  You might use `I a M C' to change `x < y'
to `cos(x) > cos(y)' if you know you are working with small positive
angles.

   The `a b' (`calc-substitute') [`subst'] command substitutes all
occurrences of some variable or sub-expression of an expression with a
new sub-expression.  For example, substituting `sin(x)' with `cos(y)'
in `2 sin(x)^2 + x sin(x) + sin(2 x)' produces `2 cos(y)^2 + x cos(y) +
sin(2 x)'.  Note that this is a purely structural substitution; the
lone `x' and the `sin(2 x)' stayed the same because they did not look
like `sin(x)'.  *Note Rewrite Rules::, for a more general method for
doing substitutions.

   The `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 `a b' has no understanding of commutativity or
associativity.  The pattern `x+y' will not match the formula `y+x'.
Also, `y+z' will not match inside the formula `x+y+z' because the `+'
operator is left-associative, so the "deep structure" of that formula
is `(x+y) + z'.  Use `d U' (`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, `subst' takes three arguments: Target
expression, old, new.  Note that `subst' is always evaluated
immediately, even if its arguments are variables, so if you wish to put
a call to `subst' onto the stack you must turn the default
simplifications off first (with `m O').


File: calc,  Node: Simplifying Formulas,  Next: Polynomials,  Prev: Algebraic Manipulation,  Up: Algebra

12.3 Simplifying Formulas
=========================

The `a s' (`calc-simplify') [`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 `a + b + 2 a'
to `b + 3 a', and some formulas like `sin(arcsin(x))' are simplified to
`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.  *Note
Rearranging with Selections::.  *Note Rewrite Rules::.

   *Note Simplification Modes::, for commands to control what level of
simplification occurs automatically.  Normally only the "default
simplifications" occur.

   There are some simplifications that, while sometimes useful, are
never done automatically.  For example, the `I' prefix can be given to
`a s'; the `I a s' command will change any trigonometric function to
the appropriate combination of `sin's and `cos's before simplifying.
This can be useful in simplifying even mildly complicated trigonometric
expressions.  For example, while `a s' can reduce `sin(x) csc(x)' to
`1', it will not simplify `sin(x)^2 csc(x)'.  The command `I a s' can
be used to simplify this latter expression; it will transform `sin(x)^2
csc(x)' into `sin(x)'.  However, `I a s' will also perform some
"simplifications" which may not be desired; for example, it will
transform `tan(x)^2' into `sin(x)^2 / cos(x)^2'.  The Hyperbolic prefix
`H' can be used similarly; the `H a s' will replace any hyperbolic
functions in the formula with the appropriate combinations of `sinh's
and `cosh's before simplifying.

* Menu:

* Default Simplifications::
* Algebraic Simplifications::
* Unsafe Simplifications::
* Simplification of Units::


File: calc,  Node: Default Simplifications,  Next: Algebraic Simplifications,  Prev: Simplifying Formulas,  Up: Simplifying Formulas

12.3.1 Default Simplifications
------------------------------

This section describes the "default simplifications," those which are
normally applied to all results.  For example, if you enter the variable
`x' on the stack twice and push `+', Calc's default simplifications
automatically change `x + x' to `2 x'.

   The `m O' command turns off the default simplifications, so that `x
+ x' will remain in this form unless you give an explicit "simplify"
command like `=' or `a v'.  *Note Algebraic Manipulation::.  The `m D'
command turns the default simplifications back on.

   The most basic default simplification is the evaluation of functions.
For example, `2 + 3' is evaluated to `5', and `sqrt(9)' is evaluated to
`3'.  Evaluation does not occur if the arguments to a function are
somehow of the wrong type `tan([2,3,4])'), range (`tan(90)'), or number
(`tan(3,5)'), or if the function name is not recognized (`f(5)'), or if
Symbolic mode (*note Symbolic Mode::) prevents evaluation (`sqrt(2)').

   Calc simplifies (evaluates) the arguments to a function before it
simplifies the function itself.  Thus `sqrt(5+4)' is simplified to
`sqrt(9)' before the `sqrt' function itself is applied.  There are very
few exceptions to this rule: `quote', `lambda', and `condition' (the
`::' operator) do not evaluate their arguments, `if' (the `? :'
operator) does not evaluate all of its arguments, and `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 `+' and `Q' [`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.

   As well as the simplifications described here, if you have stored
any rewrite rules in the variable `EvalRules' then these rules will
also be applied before any built-in default simplifications.  *Note
Automatic Rewrites::, for details.

   And now, on with the default simplifications:

   Arithmetic operators like `+' and `*' 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, `((a + b) + c) + d', and (by default) a right-associative
form for products, `a * (b * (c * d))'.  Formulas like `(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 _not_ rearranged according to the commutative
law (`a + b' to `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 `a b + b a' can be simplified to `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 `a s'
command.  *Note Algebraic Simplifications::.

   Differences `a - b' are treated like sums `a + (-b)' for purposes of
simplification; one of the default simplifications is to rewrite `a +
(-b)' or `(-b) + a', where `-b' represents a "negative-looking" term,
into `a - b' form.  "Negative-looking" means negative numbers, negated
formulas like `-x', and products or quotients in which either term is
negative-looking.

   Other simplifications involving negation are `-(-x)' to `x'; `-(a
b)' or `-(a/b)' where either `a' or `b' is negative-looking, simplified
by negating that term, or else where `a' or `b' is any number, by
negating that number; `-(a + b)' to `-a - b', and `-(b - a)' to `a - b'.
(This, and rewriting `(-b) + a' to `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: `a x +
b x' to `(a + b) x', where `a' represents a number or an implicit 1 or
-1 (as in `x' or `-x') and similarly for `b'.  Use the `a c', `a f', or
`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 `a + b + b + c' is simplified to
`a + 2 b + c', but `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 `a s'.

   Finally, `a + 0' and `0 + a' are simplified to `a'.  A consequence
of the above rules is that `0 - a' is simplified to `-a'.

   The products `1 a' and `a 1' are simplified to `a'; `(-1) a' and `a
(-1)' are simplified to `-a'; `0 a' and `a 0' are simplified to `0',
except that in Matrix mode where `a' is not provably scalar the result
is the generic zero matrix `idn(0)', and that if `a' is infinite the
result is `nan'.

   Also, `(-a) b' and `a (-b)' are simplified to `-(a b)', where this
occurs for negated formulas but not for regular negative numbers.

   Products are commuted only to move numbers to the front: `a b 2' is
commuted to `2 a b'.

   The product `a (b + c)' is distributed over the sum only if `a' and
at least one of `b' and `c' are numbers: `2 (x + 3)' goes to `2 x + 6'.
The formula `(-a) (b - c)', where `-a' is a negative number, is
rewritten to `a (c - b)'.

   The distributive law of products and powers is used for adjacent
terms of the product: `x^a x^b' goes to `x^(a+b)' where `a' is a
number, or an implicit 1 (as in `x'), or the implicit one-half of
`sqrt(x)', and similarly for `b'.  The result is written using `sqrt'
or `1/sqrt' if the sum of the powers is `1/2' or `-1/2', respectively.
If the sum of the powers is zero, the product is simplified to `1' or
to `idn(1)' if Matrix mode is enabled.

   The product of a negative power times anything but another negative
power is changed to use division: `x^(-2) y' goes to `y / x^2' unless
Matrix mode is in effect and neither `x' nor `y' are scalar (in which
case it is considered unsafe to rearrange the order of the terms).

   Finally, `a (b/c)' is rewritten to `(a b)/c', and also `(a/b) c' is
changed to `(a c)/b' unless in Matrix mode.

   Simplifications for quotients are analogous to those for products.
The quotient `0 / x' is simplified to `0', with the same exceptions
that were noted for `0 x'.  Likewise, `x / 1' and `x / (-1)' are
simplified to `x' and `-x', respectively.

   The quotient `x / 0' is left unsimplified or changed to an infinite
quantity, as directed by the current infinite mode.  *Note Infinite
Mode::.

   The expression `a / b^(-c)' is changed to `a b^c', where `-c' is any
negative-looking power.  Also, `1 / b^c' is changed to `b^(-c)' for any
power `c'.

   Also, `(-a) / b' and `a / (-b)' go to `-(a/b)'; `(a/b) / c' goes to
`a / (b c)'; and `a / (b/c)' goes to `(a c) / b' unless Matrix mode
prevents this rearrangement.  Similarly, `a / (b:c)' is simplified to
`(c:b) a' for any fraction `b:c'.

   The distributive law is applied to `(a + b) / c' only if `c' and at
least one of `a' and `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, `a x b / a y b' is canceled
to `x b / y b' but not to `x / y'.  Once again this is because full
cancellation can be slow; use `a s' to cancel all terms of the quotient.

   Quotients of negative-looking values are simplified according to
`(-a) / (-b)' to `a / b', `(-a) / (b - c)' to `a / (c - b)', and `(a -
b) / (-c)' to `(b - a) / c'.

   The formula `x^0' is simplified to `1', or to `idn(1)' in Matrix
mode.  The formula `0^x' is simplified to `0' unless `x' is a negative
number, complex number or zero.  If `x' is negative, complex or `0.0',
`0^x' is an infinity or an unsimplified formula according to the
current infinite mode.  The expression `0^0' is simplified to `1'.

   Powers of products or quotients `(a b)^c', `(a/b)^c' are distributed
to `a^c b^c', `a^c / b^c' only if `c' is an integer, or if either `a'
or `b' are nonnegative real numbers.  Powers of powers `(a^b)^c' are
simplified to `a^(b c)' only when `c' is an integer and `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, `((-3)^1:2)^2' is safe to simplify, but
`((-3)^2)^1:2' is not.)  *Note Declarations::, for ways to inform Calc
that your variables satisfy these requirements.

   As a special case of this rule, `sqrt(x)^n' is simplified to
`x^(n/2)' only for even integers `n'.

   If `a' is known to be real, `b' is an even integer, and `c' is a
half- or quarter-integer, then `(a^b)^c' is simplified to `abs(a^(b
c))'.

   Also, `(-a)^b' is simplified to `a^b' if `b' is an even integer, or
to `-(a^b)' if `b' is an odd integer, for any negative-looking
expression `-a'.

   Square roots `sqrt(x)' generally act like one-half powers `x^1:2'
for the purposes of the above-listed simplifications.

   Also, note that `1 / x^1:2' is changed to `x^(-1:2)', but `1 /
sqrt(x)' is left alone.

   Generic identity matrices (*note Matrix Mode::) are simplified by the
following rules:  `idn(a) + b' to `a + b' if `b' is provably scalar, or
expanded out if `b' is a matrix; `idn(a) + idn(b)' to `idn(a + b)';
`-idn(a)' to `idn(-a)'; `a idn(b)' to `idn(a b)' if `a' is provably
scalar, or to `a b' if `a' is provably non-scalar;  `idn(a) idn(b)' to
`idn(a b)'; analogous simplifications for quotients involving `idn';
and `idn(a)^n' to `idn(a^n)' where `n' is an integer.

   The `floor' function and other integer truncation functions vanish
if the argument is provably integer-valued, so that `floor(round(x))'
simplifies to `round(x)'.  Also, combinations of `float', `floor' and
its friends, and `ffloor' and its friends, are simplified in appropriate
ways.  *Note Integer Truncation::.

   The expression `abs(-x)' changes to `abs(x)'.  The expression
`abs(abs(x))' changes to `abs(x)';  in fact, `abs(x)' changes to `x' or
`-x' if `x' is provably nonnegative or nonpositive (*note
Declarations::).

   While most functions do not recognize the variable `i' as an
imaginary number, the `arg' function does handle the two cases `arg(i)'
and `arg(-i)' just for convenience.

   The expression `conj(conj(x))' simplifies to `x'.  Various other
expressions involving `conj', `re', and `im' are simplified, especially
if some of the arguments are provably real or involve the constant `i'.
For example, `conj(a + b i)' is changed to `conj(a) - conj(b) i',  or
to `a - b i' if `a' and `b' are known to be real.

   Functions like `sin' and `arctan' generally don't have any default
simplifications beyond simply evaluating the functions for suitable
numeric arguments and infinity.  The `a s' command described in the
next section does provide some simplifications for these functions,
though.

   One important simplification that does occur is that `ln(e)' is
simplified to 1, and `ln(e^x)' is simplified to `x' for any `x'.  This
occurs even if you have stored a different value in the Calc variable
`e'; but this would be a bad idea in any case if you were also using
natural logarithms!

   Among the logical functions, !(A <= B) changes to 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 `!!x' to `x',
this would not be valid in general because `!!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.


File: calc,  Node: Algebraic Simplifications,  Next: Unsafe Simplifications,  Prev: Default Simplifications,  Up: Simplifying Formulas

12.3.2 Algebraic Simplifications
--------------------------------

The `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 `m A' to have Calc
apply them automatically.

   This section describes all simplifications that are performed by the
`a s' command.  Note that these occur in addition to the default
simplifications; even if the default simplifications have been turned
off by an `m O' command, `a s' will turn them back on temporarily while
it simplifies the formula.

   There is a variable, `AlgSimpRules', in which you can put rewrites
to be applied by `a s'.  Its use is analogous to `EvalRules', but
without the special restrictions.  Basically, the simplifier does `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 `EvalRules'), then `AlgSimpRules', then the
built-in simplifications, and so on.

   Sums are simplified in two ways.  Constant terms are commuted to the
end of the sum, so that `a + 2 + b' changes to `a + b + 2'.  The only
exception is that a constant will not be commuted away from the first
position of a difference, i.e., `2 - x' is not commuted to `-x + 2'.

   Also, terms of sums are combined by the distributive law, as in `x +
y + 2 x' to `y + 3 x'.  This always occurs for adjacent terms, but `a
s' compares all pairs of terms including non-adjacent ones.

   Products are sorted into a canonical order using the commutative
law.  For example, `b c a' is commuted to `a b c'.  This allows easier
comparison of products; for example, the default simplifications will
not change `x y + y x' to `2 x y', but `a s' will; it first rewrites
the sum to `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 `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 `(x + y)
(y + x)' will be simplified to `(x + y)^2'.  A subtle point is that `(x
- y) (y - x)' will _not_ be simplified to `-(x - y)^2'; Calc does not
notice that one term can be written as a constant times the other, even
if that constant is -1.

   A fraction times any expression, `(a:b) x', is changed to a quotient
involving integers:  `a x / b'.  This is not done for floating-point
numbers like `0.5', however.  This is one reason why you may find it
convenient to turn Fraction mode on while doing algebra; *note Fraction
Mode::.

   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, `a x^2 b / c x^3 d' will cancel `x^2'
from the top and bottom to get `a b / c x d'.  (The terms in the
denominator will then be rearranged to `c d x' as described above.)  If
there is any common integer or fractional factor in the numerator and
denominator, it is canceled out; for example, `(4 x + 6) / 8 x'
simplifies to `(2 x + 3) / 4 x'.

   Non-constant common factors are not found even by `a s'.  To cancel
the factor `a' in `(a x + a) / a^2' you could first use `j M' on the
product `a x' to Merge the numerator to `a (1+x)', which can then be
simplified successfully.

   Integer powers of the variable `i' are simplified according to the
identity `i^2 = -1'.  If you store a new value other than the complex
number `(0,1)' in `i', this simplification will no longer occur.  This
is done by `a s' instead of by default in case someone (unwisely) uses
the name `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 `sqrt(8)' is rewritten as `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:  `1 / sqrt(3)' changes to `sqrt(3) / 3'.  The same effect
occurs for the square root of a fraction: `sqrt(2:3)' changes to
`sqrt(6) / 3'.

   The `%' (modulo) operator is simplified in several ways when the
modulus `M' is a positive real number.  First, if the argument is of
the form `x + n' for some real number `n', then `n' is itself reduced
modulo `M'.  For example, `(x - 23) % 10' is simplified to `(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 canceled
out.  For example, `12 x % 15' is changed to `3 (4 x % 5)' by factoring
out 3.  Also, `(12 x + 1) % 15' is changed to `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 `int' declarations to
evaluate the expression.  For example, the idiom `x % 2' is often used
to check whether a number is odd or even.  As described above,
`2 n % 2' and `(2 n + 1) % 2' are simplified to `2 (n % 1)' and `2 ((n
+ 1:2) % 1)', respectively; Calc can simplify these to 0 and 1
(respectively) if `n' has been declared to be an integer.

   Trigonometric functions are simplified in several ways.  Whenever a
products of two trigonometric functions can be replaced by a single
function, the replacement is made; for example, `tan(x) cos(x)' is
simplified to `sin(x)'.  Reciprocals of trigonometric functions are
replaced by their reciprocal function; for example, `1/sec(x)' is
simplified to `cos(x)'.  The corresponding simplifications for the
hyperbolic functions are also handled.

   Trigonometric functions of their inverse functions are simplified.
The expression `sin(arcsin(x))' is simplified to `x', and similarly for
`cos' and `tan'.  Trigonometric functions of inverses of different
trigonometric functions can also be simplified, as in `sin(arccos(x))'
to `sqrt(1 - x^2)'.

   If the argument to `sin' is negative-looking, it is simplified to
`-sin(x)', and similarly for `cos' and `tan'.  Finally, certain special
values of the argument are recognized; *note Trigonometric and
Hyperbolic Functions::.

   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 `arcsin',
`arctan', `arcsinh', and `arctanh'.  Note that `arcsin(sin(x))' can
_not_ safely change to `x', since this only correct within an integer
multiple of `2 pi' radians or 360 degrees.  However, `arcsinh(sinh(x))'
is simplified to `x' if `x' is known to be real.

   Several simplifications that apply to logarithms and exponentials
are that `exp(ln(x))', `e^ln(x)', and `10^log10(x)' all reduce to `x'.
Also, `ln(exp(x))', etc., can reduce to `x' if `x' is provably real.
The form `exp(x)^y' is simplified to `exp(x y)'.  If `x' is a suitable
multiple of `pi i' (as described above for the trigonometric
functions), then `exp(x)' or `e^x' will be expanded.  Finally, `ln(x)'
is simplified to a form involving `pi' and `i' where `x' is provably
negative, positive imaginary, or negative imaginary.

   The error functions `erf' and `erfc' are simplified when their
arguments are negative-looking or are calls to the `conj' function.

   Equations and inequalities are simplified by canceling factors of
products, quotients, or sums on both sides.  Inequalities change sign
if a negative multiplicative factor is canceled.  Non-constant
multiplicative factors as in `a b = a c' are canceled from equations
only if they are provably nonzero (generally because they were declared
so; *note Declarations::).  Factors are canceled 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 `x'
is declared to be an integer greater than 5, then `x < 3', `x = 3', and
`x = 7.5' are all simplified to 0, but `x > 3' is simplified to 1.  By
a similar analysis, `abs(x) >= 0' is simplified to 1, as is `x^2 >= 0'
if `x' is known to be real.


File: calc,  Node: Unsafe Simplifications,  Next: Simplification of Units,  Prev: Algebraic Simplifications,  Up: Simplifying Formulas

12.3.3 "Unsafe" Simplifications
-------------------------------

The `a e' (`calc-simplify-extended') [`esimplify'] command is like `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 `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 `a'
only," Calc (like most other symbolic integration programs) will simply
produce an unqualified result.

   Because `a e''s simplifications are unsafe, it is sometimes better
to type `C-u -3 a v', which does extended simplification only on the
top level of the formula without affecting the sub-formulas.  In fact,
`C-u -3 j v' allows you to target extended simplification to any
specific part of a formula.

   The variable `ExtSimpRules' contains rewrites to be applied by the
`a e' command.  These are applied in addition to `EvalRules' and
`AlgSimpRules'.  (The `a r AlgSimpRules' step described above is simply
followed by an `a r ExtSimpRules' step.)

   Following is a complete list of "unsafe" simplifications performed
by `a e'.

   Inverse trigonometric or hyperbolic functions, called with their
corresponding non-inverse functions as arguments, are simplified by `a
e'.  For example, `arcsin(sin(x))' changes to `x'.  Also,
`arcsin(cos(x))' and `arccos(sin(x))' both change to `pi/2 - x'.  These
simplifications are unsafe because they are valid only for values of
`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 `(x^a)^b' are simplified to `x^(a b)' for all `a'
and `b'.  These results will be valid only in a restricted range of
`x'; for example, in `(x^2)^1:2' the powers cancel to get `x', which is
valid for positive values of `x' but not for negative or complex values.

   Similarly, `sqrt(x^a)' and `sqrt(x)^a' are both simplified (possibly
unsafely) to `x^(a/2)'.

   Forms like `sqrt(1 - sin(x)^2)' are simplified to, e.g., `cos(x)'.
Calc has identities of this sort for `sin', `cos', `tan', `sinh', and
`cosh'.

   Arguments of square roots are partially factored to look for squared
terms that can be extracted.  For example, `sqrt(a^2 b^3 + a^3 b^2)'
simplifies to `a b sqrt(a+b)'.

   The simplifications of `ln(exp(x))', `ln(e^x)', and `log10(10^x)' to
`x' are also unsafe because of problems with principal values (although
these simplifications are safe if `x' is known to be real).

   Common factors are canceled from products on both sides of an
equation, even if those factors may be zero:  `a x / b x' to `a / b'.
Such factors are never canceled from inequalities:  Even `a e' is not
bold enough to reduce `a x < b x' to `a < b' (or `a > b', depending on
whether you believe `x' is positive or negative).  The `a M /' command
can be used to divide a factor out of both sides of an inequality.


File: calc,  Node: Simplification of Units,  Prev: Unsafe Simplifications,  Up: Simplifying Formulas

12.3.4 Simplification of Units
------------------------------

The simplifications described in this section are applied by the `u s'
(`calc-simplify-units') command.  These are in addition to the regular
`a s' (but not `a e') simplifications described earlier.  *Note Basic
Operations on Units::.

   The variable `UnitSimpRules' contains rewrites to be applied by the
`u s' command.  These are applied in addition to `EvalRules' and
`AlgSimpRules'.

   Scalar mode is automatically put into effect when simplifying units.
*Note Matrix Mode::.

   Sums `a + b' involving units are simplified by extracting the units
of `a' as if by the `u x' command (call the result `u_a'), then
simplifying the expression `b / u_a' using `u b' and `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 `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 canceling and combining units in products and quotients, Calc
accounts for unit names that differ only in the prefix letter.  For
example, `2 km m' is simplified to `2000 m^2'.  However, compatible but
different units like `ft' and `in' are not combined in this way.

   Quotients `a / b' are simplified in three additional ways.  First,
if `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 `3 s in N / kg cm' the units `in / cm' will be
replaced by `2.54'.

   Third, if the units in the quotient exactly cancel out, so that a `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 `(a b)^c'
to `a^c b^c', `(a/b)^c' to `a^c / b^c', and `(a^b)^c' to `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, `acre^1.5' is simplified by noting that `1.5 =
3:2', that `acre' is defined in terms of `m^2', and that the 2 in the
power of `m' is a multiple of 2 in `3:2'.  Thus, `acre^1.5' is replaced
by approximately `(4046 m^2)^1.5', which is then changed to `4046^1.5
(m^2)^1.5', then to `257440 m^3'.

   The functions `float', `frac', `clean', `abs', as well as `floor'
and the other integer truncation functions, applied to unit names or
products or quotients involving units, are simplified.  For example,
`round(1.6 in)' is changed to `round(1.6) round(in)'; the lefthand term
evaluates to 2, and the righthand term simplifies to `in'.

   The functions `sin', `cos', and `tan' with arguments that have
angular units like `rad' or `arcmin' are simplified by converting to
base units (radians), then evaluating with the angular mode temporarily
set to radians.


File: calc,  Node: Polynomials,  Next: Calculus,  Prev: Simplifying Formulas,  Up: Algebra

12.4 Polynomials
================

A "polynomial" is a sum of terms which are coefficients times various
powers of a "base" variable.  For example, `2 x^2 + 3 x - 4' is a
polynomial in `x'.  Some formulas can be considered polynomials in
several different variables:  `1 + 2 x + 3 y + 4 x y^2' is a polynomial
in both `x' and `y'.  Polynomial coefficients are often numbers, but
they may in general be any formulas not involving the base variable.

   The `a f' (`calc-factor') [`factor'] command factors a polynomial
into a product of terms.  For example, the polynomial `x^3 + 2 x^2 + x'
is factored into `x*(x+1)^2'.  As another example, `a c + b d + b c + a
d' is factored into the product `(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 (`x',
`x+1', and `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 (`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.)

   The rewrite-based factorization method uses rules stored in the
variable `FactorRules'.  *Note Rewrite Rules::, for a discussion of the
operation of rewrite rules.  The default `FactorRules' are able to
factor quadratic forms symbolically into two linear terms, `(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 `thecoefs(x, [a, b, c,
...])' where `x' is the polynomial base variable and `a', `b', etc.,
are polynomial coefficients (which may be numbers or formulas).  The
constant term is written first, i.e., in the `a' position.  When the
rules complete, they should have changed the formula into the form
`thefactors(x, [f1, f2, f3, ...])' where each `fi' should be a factored
term, e.g., `x - ai'.  Calc then multiplies these terms together to get
the complete factored form of the polynomial.  If the rules do not
change the `thecoefs' call to a `thefactors' call, `a f' leaves the
polynomial alone on the assumption that it is unfactorable.  (Note that
the function names `thecoefs' and `thefactors' are used only as
placeholders; there are no actual Calc functions by those names.)

   The `H a f' [`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, `x^5 + x^4 -
33 x^3 + 63 x^2' factors to `(x + 7) x^2 (x - 3)^2' in `a f', or to `[
[x, 2], [x+7, 1], [x-3, 2] ]' in `H a f'.  If there is an overall
numeric factor, it always comes first in the list.  The functions
`factor' and `factors' allow a second argument when written in
algebraic form; `factor(x,v)' factors `x' with respect to the specific
variable `v'.  The default is to factor with respect to all the
variables that appear in `x'.

   The `a c' (`calc-collect') [`collect'] command rearranges a formula
as a polynomial in a given variable, ordered in decreasing powers of
that variable.  For example, given `1 + 2 x + 3 y + 4 x y^2' on the
stack, `a c x' would produce `(2 + 4 y^2) x + (1 + 3 y)', and `a c y'
would produce `(4 x) y^2 + 3 y + (1 + 2 x)'.  The polynomial will be
expanded out using the distributive law as necessary:  Collecting `x'
in `(x - 1)^3' produces `x^3 - 3 x^2 + 3 x - 1'.  Terms not involving
`x' will not be expanded.

   The "variable" you specify at the prompt can actually be any
expression: `a c ln(x+1)' will collect together all terms multiplied by
`ln(x+1)' or integer powers thereof.  If `x' also appears in the
formula in a context other than `ln(x+1)', `a c' will treat those
occurrences as unrelated to `ln(x+1)', i.e., as constants.

   The `a x' (`calc-expand') [`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 `a x' and `j D' commands are somewhat redundant.  Use `a x' if
you want to expand all products of sums in your formula.  Use `j D' if
you want to expand a particular specified term of the formula.  There
is an exactly analogous correspondence between `a f' and `j M'.  (The
`j D' and `j M' commands also know many other kinds of expansions, such
as `exp(a + b) = exp(a) exp(b)', which `a x' and `a f' do not do.)

   Calc's automatic simplifications will sometimes reverse a partial
expansion.  For example, the first step in expanding `(x+1)^3' is to
write `(x+1) (x+1)^2'.  If `a x' stops there and tries to put this
formula onto the stack, though, Calc will automatically simplify it
back to `(x+1)^3' form.  The solution is to turn simplification off
first (*note Simplification Modes::), or to run `a x' without a numeric
prefix argument so that it expands all the way in one step.

   The `a a' (`calc-apart') [`apart'] command expands a rational
function by partial fractions.  A rational function is the quotient of
two polynomials; `apart' pulls this apart into a sum of rational
functions with simple denominators.  In algebraic notation, the `apart'
function allows a second argument that specifies which variable to use
as the "base"; by default, Calc chooses the base variable automatically.

   The `a n' (`calc-normalize-rat') [`nrat'] command attempts to
arrange a formula into a quotient of two polynomials.  For example,
given `1 + (a + b/c) / d', the result would be `(b + a c + c d) / c d'.
The quotient is reduced, so that `a n' will simplify `(x^2 + 2x + 1) /
(x^2 - 1)' by dividing out the common factor `x + 1', yielding `(x + 1)
/ (x - 1)'.

   The `a \' (`calc-poly-div') [`pdiv'] command divides two polynomials
`u' and `v', yielding a new polynomial `q'.  If several variables occur
in the inputs, the inputs are considered multivariate polynomials.
(Calc divides by the variable with the largest power in `u' first, or,
in the case of equal powers, chooses the variables in alphabetical
order.)  For example, dividing `x^2 + 3 x + 2' by `x + 2' yields `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 `pdiv' in algebraic notation, you can specify the particular
variable to be used as the base: `pdiv(A,B,X)'.  If `pdiv' is given
only two arguments (as is always the case with the `a \' command), then
it does a multivariate division as outlined above.

   The `a %' (`calc-poly-rem') [`prem'] command divides two polynomials
and keeps the remainder `r'.  The quotient `q' is discarded.  For any
formulas `a' and `b', the results of `a \' and `a %' satisfy `a = q b +
r'.  (This is analogous to plain `\' and `%', which compute the integer
quotient and remainder from dividing two numbers.)

   The `a /' (`calc-poly-div-rem') [`pdivrem'] command divides two
polynomials and reports both the quotient and the remainder as a vector
`[q, r]'.  The `H a /' [`pdivide'] command divides two polynomials and
constructs the formula `q + r/b' on the stack.  (Naturally if the
remainder is zero, this will immediately simplify to `q'.)

   The `a g' (`calc-poly-gcd') [`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 `a n' command uses `a g' to take
the GCD of the numerator and denominator of a quotient, then divides
each by the result using `a \'.  (The definition of GCD ensures that
this division can take place without leaving a remainder.)

   While the polynomials used in operations like `a /' and `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 `(x^2 + 3 x - 1) mod 5', Calc automatically
transforms this into a polynomial over the field of integers mod 5:
`(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)'.

   Congratulations and thanks go to Ove Ewerlid
(`ewerlid@mizar.DoCS.UU.SE'), who contributed many of the polynomial
routines used in the above commands.

   *Note Decomposing Polynomials::, for several useful functions for
extracting the individual coefficients of a polynomial.


File: calc,  Node: Calculus,  Next: Solving Equations,  Prev: Polynomials,  Up: Algebra

12.5 Calculus
=============

The following calculus commands do not automatically simplify their
inputs or outputs using `calc-simplify'.  You may find it helps to do
this by hand by typing `a s' or `a e'.  It may also help to use `a x'
and/or `a c' to arrange a result in the most readable way.

* Menu:

* Differentiation::
* Integration::
* Customizing the Integrator::
* Numerical Integration::
* Taylor Series::


File: calc,  Node: Differentiation,  Next: Integration,  Prev: Calculus,  Up: Calculus

12.5.1 Differentiation
----------------------

The `a d' (`calc-derivative') [`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., `deriv(y,x)' is reduced to zero.  With the
Hyperbolic flag, the `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 `pi' are
considered constant, as are variables that have been declared `const';
*note Declarations::.)

   With a numeric prefix argument N, this command computes the Nth
derivative.

   When working with trigonometric functions, it is best to switch to
Radians mode first (with `m r').  The derivative of `sin(x)' in degrees
is `(pi/180) cos(x)', probably not the expected answer!

   If you use the `deriv' function directly in an algebraic formula,
you can write `deriv(f,x,x0)' which represents the derivative of `f'
with respect to `x', evaluated at the point `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, `deriv(f(2x), x)'
produces `2 f'(2 x)', where the function `f'' represents the derivative
of `f'.

   For functions you have defined with the `Z F' command, Calc expands
the functions according to their defining formulas unless you have also
defined `f'' suitably.  For example, suppose we define `sinc(x) =
sin(x)/x' using `Z F'.  If we then differentiate the formula `sinc(2
x)', the formula will be expanded to `sin(2 x) / (2 x)' and
differentiated.  However, if we also define `sinc'(x) = dsinc(x)', say,
then Calc will write the result as `2 dsinc(2 x)'.  *Note Algebraic
Definitions::.

   For multi-argument functions `f(x,y,z)', the derivative with respect
to the first argument is written `f'(x,y,z)'; derivatives with respect
to the other arguments are `f'2(x,y,z)' and `f'3(x,y,z)'.  Various
higher-order derivatives can be formed in the obvious way, e.g.,
`f''(x)' (the second derivative of `f') or `f''2'3(x,y,z)' (`f'
differentiated with respect to each argument once).


File: calc,  Node: Integration,  Next: Customizing the Integrator,  Prev: Differentiation,  Up: Calculus

12.5.2 Integration
------------------

The `a i' (`calc-integral') [`integ'] command computes the indefinite
integral of the expression on the top of the stack with respect to a
prompted-for 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;
`x/(1+x^-2)' is not strictly a quotient of polynomials, but it is
equivalent to `x^3/(x^2+1)', which is.)  Also, square roots of terms
involving `x' and `x^2' may appear in rational functions being
integrated.  Finally, rational functions involving trigonometric or
hyperbolic functions can be integrated.

   With an argument (`C-u a i'), this command will compute the definite
integral of the expression on top of the stack.  In this case, the
command will again prompt for an integration variable, then prompt for a
lower limit and an upper limit.

   If you use the `integ' function directly in an algebraic formula,
you can also write `integ(f,x,v)' which expresses the resulting
indefinite integral in terms of variable `v' instead of `x'.  With four
arguments, `integ(f(x),x,a,b)' represents a definite integral from `a'
to `b'.

   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
`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 `1/(1+tan(x))' differs from
the solution given in the _CRC Math Tables_ by a constant factor of `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
`calc-flush-caches' command; *note Caches::.

   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 `IntegLimit'.  (The
`s I' command is a convenient way to edit `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
`*Trace*'.  If such a buffer exists, the `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.  *Note Rewrite Rules::.


File: calc,  Node: Customizing the Integrator,  Next: Numerical Integration,  Prev: Integration,  Up: Calculus

12.5.3 Customizing the Integrator
---------------------------------

Calc has two built-in rewrite rules called `IntegRules' and
`IntegAfterRules' which you can edit to define new integration methods.
*Note Rewrite Rules::.  At each step of the integration process, Calc
wraps the current integrand in a call to the fictitious function
`integtry(EXPR,VAR)', where EXPR is the integrand and VAR is the
integration variable.  If your rules rewrite this to be a plain formula
(not a call to `integtry'), then Calc will use this formula as the
integral of EXPR.  For example, the rule `integtry(mysin(x),x) :=
-mycos(x)' would define a rule to integrate a function `mysin' that
acts like the sine function.  Then, putting `4 mysin(2y+1)' on the
stack and typing `a i y' will produce the integral `-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 `mysin(a x + b)', but you don't need to use this much
generality in your `IntegRules'.

   As a more serious example, the expression `exp(x)/x' cannot be
integrated in terms of the standard functions, so the "exponential
integral" function `Ei(x)' was invented to describe it.  We can get
Calc to do this integral in terms of a made-up `Ei' function by adding
the rule `[integtry(exp(x)/x, x) := Ei(x)]' to `IntegRules'.  Now
entering `exp(2x)/x' on the stack and typing `a i x' yields `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 `Ei':  For example, now Calc will also be able
to integrate `exp(exp(x))' and `ln(ln(x))' (to get `Ei(exp(x))' and `x
ln(ln(x)) - Ei(ln(x))', respectively).

   Your rule may do further integration by calling `integ'.  For
example, `integtry(twice(u),x) := twice(integ(u))' allows Calc to
integrate `twice(sin(x))' to get `twice(-cos(x))'.  Note that `integ'
was called with only one argument.  This notation is allowed only
within `IntegRules'; it means "integrate this with respect to the same
integration variable."  If Calc is unable to integrate `u', the
integration that invoked `IntegRules' also fails.  Thus integrating
`twice(f(x))' fails, returning the unevaluated integral
`integ(twice(f(x)), x)'.  It is still valid to call `integ' with two or
more arguments, however; in this case, if `u' is not integrable,
`twice' itself will still be integrated:  If the above rule is changed
to `... := twice(integ(u,x))', then integrating `twice(f(x))' will
yield `twice(integ(f(x),x))'.

   If a rule instead produces the formula `integsubst(SEXPR, SVAR)',
either replacing the top-level `integtry' call or nested anywhere
inside the expression, then Calc will apply the substitution `U =
SEXPR(SVAR)' to try to integrate the original EXPR.  For example, the
rule `sqrt(a) := integsubst(sqrt(x),x)' says that if Calc ever finds a
square root in the integrand, it should attempt the substitution `u =
sqrt(x)'.  (This particular rule is unnecessary because Calc always
tries "obvious" substitutions where SEXPR actually appears in the
integrand.)  The variable SVAR may be the same as the VAR that appeared
in the call to `integtry', but it need not be.

   When integrating according to an `integsubst', Calc uses the
equation solver to find the inverse of SEXPR (if the integrand refers
to VAR anywhere except in subexpressions that exactly match SEXPR).  It
uses the differentiator to find the derivative of 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
`integsubst' your rules construct; the general form is
`integsubst(SEXPR, SVAR, SINV, SPRIME)', where SINV is the inverse of
SEXPR (still written as a function of SVAR), and SPRIME is the
derivative of SEXPR with respect to 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 `IntegRules' as if by `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 `integsubst(sqrt(x),x)' example
above would keep on adding layers of `integsubst' calls forever!)

   Another set of rules, stored in `IntegSimpRules', are applied every
time the integrator uses `a s' to simplify an intermediate result.  For
example, putting the rule `twice(x) := 2 x' into `IntegSimpRules' would
tell Calc to convert the `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 `Z F' command (*note 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.)

   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 `integsubst' as described above to try
to hint at a more direct path to the desired result, or you can use
`IntegAfterRules'.  This is an extra rule set that runs after the main
integrator returns its result; basically, Calc does an `a r
IntegAfterRules' on the result before showing it to you.  (It also does
an `a s', without `IntegSimpRules', after that to further simplify the
result.)  For example, Calc's integrator sometimes produces expressions
of the form `ln(1+x) - ln(1-x)'; the default `IntegAfterRules' rewrite
this into the more readable form `2 arctanh(x)'.  Note that, unlike
`IntegRules', `IntegSimpRules' and `IntegAfterRules' are applied any
number of times until no further changes are possible.  Rewriting by
`IntegAfterRules' occurs only after the main integrator has finished,
not at every step as for `IntegRules' and `IntegSimpRules'.


File: calc,  Node: Numerical Integration,  Next: Taylor Series,  Prev: Customizing the Integrator,  Up: Calculus

12.5.4 Numerical Integration
----------------------------

If you want a purely numerical answer to an integration problem, you can
use the `a I' (`calc-num-integral') [`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 `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 `a I'.  If Calc appears to be taking too long, press
`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 `-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 `1/sqrt(x)' from 0 to 1 exists (it can be
found by Calc's symbolic integrator, for example), but `a I' will fail
because the integrand goes to infinity at one of the endpoints.


File: calc,  Node: Taylor Series,  Prev: Numerical Integration,  Up: Calculus

12.5.5 Taylor Series
--------------------

The `a t' (`calc-taylor') [`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
`VAR = A' or `VAR - A' instead of just a variable to produce a Taylor
expansion about the point 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.

   If the `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.


File: calc,  Node: Solving Equations,  Next: Numerical Solutions,  Prev: Calculus,  Up: Algebra

12.6 Solving Equations
======================

The `a S' (`calc-solve-for') [`solve'] command rearranges an equation
to solve for a specific variable.  An equation is an expression of the
form `L = R'.  For example, the command `a S x' will rearrange `y = 3x
+ 6' to the form, `x = y/3 - 2'.  If the input is not an equation, it
is treated like an equation of the form `X = 0'.

   This command also works for inequalities, as in `y < 3x + 6'.  Some
inequalities cannot be solved where the analogous equation could be;
for example, solving `a < b c' for `b' is impossible without knowing
the sign of `c'.  In this case, `a S' will produce the result `b != a/c'
(using the not-equal-to operator) to signify that the direction of the
inequality is now unknown.  The inequality `a <= b c' is not even
partially solved.  *Note 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 `a S' are `a .'
(*note Logical Operations::), which converts `x = y/3 - 2' to `y/3 -
2', and `s l' (*note Let Command::) which evaluates another formula
with `x' set equal to `y/3 - 2'.

* Menu:

* Multiple Solutions::
* Solving Systems of Equations::
* Decomposing Polynomials::


File: calc,  Node: Multiple Solutions,  Next: Solving Systems of Equations,  Prev: Solving Equations,  Up: Solving Equations

12.6.1 Multiple Solutions
-------------------------

Some equations have more than one solution.  The Hyperbolic flag (`H a
S') [`fsolve'] tells the solver to report the fully general family of
solutions.  It will invent variables `n1', `n2', ..., which represent
independent arbitrary integers, and `s1', `s2', ..., which represent
independent arbitrary signs (either +1 or -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
`n1' and `s1' are not given any special interpretation in Calc except by
the equation solver itself.  As usual, you can use the `s l'
(`calc-let') command to obtain solutions for various actual values of
these variables.

   For example, `' x^2 = y <RET> H a S x <RET>' solves to get `x = s1
sqrt(y)', indicating that the two solutions to the equation are
`sqrt(y)' and `-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, `sqrt' chooses to return the
positive result.  Then `H a S' doctors this result using `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 `sqrt(y) = x' for `y'.  Calc squares both sides to get `y = x^2'.
This is correct, except that it introduces some dubious solutions.
Consider solving `sqrt(y) = -3': Calc will report `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
`sqrt'.  This happens for both `a S' and `H a S'.

   If you store a positive integer in the Calc variable `GenCount',
then Calc will generate formulas of the form `as(N)' for arbitrary
signs, and `an(N)' for arbitrary integers, where N represents
successive values taken by incrementing `GenCount' by one.  While the
normal arbitrary sign and integer symbols start over at `s1' and `n1'
with each new Calc command, the `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 `as(n)'.  The `s l' command only works on variables, but you can
use the `a b' (`calc-substitute') command to substitute actual values
for function calls like `as(3)'.

   The `s G' (`calc-edit-GenCount') command is a convenient way to
create or edit this variable.  Press `C-c C-c' to finish.

   If you have not stored a value in `GenCount', or if the value in
that variable is not a positive integer, the regular `s1'/`n1' notation
is used.

   With the Inverse flag, `I a S' [`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, `I a S x' inverts `2x + 6' to `x/2 - 3'.  You can use both
Inverse and Hyperbolic [`ffinv'] to obtain a fully general inverse, as
described above.

   Some equations, specifically polynomials, have a known, finite number
of solutions.  The `a P' (`calc-poly-roots') [`roots'] command uses `H
a S' to solve an equation in general form, then, for all arbitrary-sign
variables like `s1', and all arbitrary-integer variables like `n1' for
which `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, `roots(x^4 = 1, x)'
returns the four solutions `[1, -1, (0, 1), (0, -1)]'.  Generally an
Nth degree polynomial will always have N roots on the complex plane.
(If you have given a `real' declaration for the solution variable, then
only the real-valued solutions, if any, will be reported; *note
Declarations::.)

   Note that because `a P' uses `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 `x^4' can always be
solved exactly; polynomials of higher degree sometimes can be:  `x^6 +
x^3 + 1' is converted to `(x^3)^2 + (x^3) + 1', which can be solved for
`x^3' using the quadratic equation, and then for `x' by taking cube
roots.  But in many cases, like `x^6 + x + 1', Calc does not know how
to rewrite the polynomial into a form it can solve.  The `a P' command
can still deliver a list of numerical roots, however, provided that
Symbolic mode (`m s') is not turned on.  (If you work with Symbolic
mode on, recall that the `N' (`calc-eval-num') key is a handy way to
reevaluate the formula on the stack with Symbolic mode temporarily
off.)  Naturally, `a P' can only provide numerical roots if the
polynomial coefficients are all numbers (real or complex).


File: calc,  Node: Solving Systems of Equations,  Next: Decomposing Polynomials,  Prev: Multiple Solutions,  Up: Solving Equations

12.6.2 Solving Systems of Equations
-----------------------------------

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 `[x + y = a, x - y = b]' on the stack and
typing `a S x,y <RET>' produces the vector of solutions `[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 `x' here could be improved by an
application of the `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.

   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 `a
S y <RET>' with the above system of equations would produce `[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 `elim(V)'
to the variables list.  This says that V should be eliminated from the
equations; the variable will not appear at all in the solution.  For
example, typing `a S y,elim(x)' would yield `[y = a - (b+a)/2]'.

   If the variables list contains only `elim' specifiers, Calc simply
eliminates those variables from the equations and then returns the
resulting set of equations.  For example, `a S elim(x)' produces `[a -
2 y = b]'.  Every variable eliminated will reduce the number of
equations in the system by one.

   Again, `a S' gives you one solution to the system of equations.  If
there are several solutions, you can use `H a S' to get a general
family of solutions, or, if there is a finite number of solutions, you
can use `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 `a F' command, which does least-squares fitting to
satisfy the equations.  *Note Curve Fitting::.


File: calc,  Node: Decomposing Polynomials,  Prev: Solving Systems of Equations,  Up: Solving Equations

12.6.3 Decomposing Polynomials
------------------------------

The `poly' function takes a polynomial and a variable as arguments, and
returns a vector of polynomial coefficients (constant coefficient
first).  For example, `poly(x^3 + 2 x, x)' returns `[0, 2, 0, 1]'.  If
the input is not a polynomial in `x', the call to `poly' is left in
symbolic form.  If the input does not involve the variable `x', the
input is returned in a list of length one, representing a polynomial
with only a constant coefficient.  The call `poly(x, x)' returns the
vector `[0, 1]'.  The last element of the returned vector is guaranteed
to be nonzero; note that `poly(0, x)' returns the empty vector `[]'.
Note also that `x' may actually be any formula; for example,
`poly(sin(x)^2 - sin(x) + 3, sin(x))' returns `[3, -1, 1]'.

   To get the `x^k' coefficient of polynomial `p', use `poly(p,
x)_(k+1)'.  To get the degree of polynomial `p', use `vlen(poly(p, x))
- 1'.  For example, `poly((x+1)^4, x)' returns `[1, 4, 6, 4, 1]', so
`poly((x+1)^4, x)_(2+1)' gives the `x^2' coefficient of this
polynomial, 6.

   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 `gpoly' function, which is used just
like `poly':  `gpoly(EXPR, VAR)'.  If EXPR is a polynomial in some term
which includes VAR, then this function will return a vector `[X, C, A]'
where X is the term that depends on VAR, C is a vector of polynomial
coefficients (like the one returned by `poly'), and A is a multiplier
which is usually 1.  Basically, `EXPR = A*(C_1 + C_2 X + C_3 X^2 +
...)'.  The last element of C is guaranteed to be non-zero, and C will
not equal `[1]' (i.e., the trivial decomposition EXPR = X is not
considered a polynomial).  One side effect is that `gpoly(x, x)' and
`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, `gpoly((x-2)^2, x)' returns `[x, [4, -4, 1], 1]', since
the expanded form of this polynomial is `4 - 4 x + x^2'.

   The term X may itself be a polynomial in VAR.  This is done to
reduce the size of the C vector.  For example, `gpoly(x^4 + x^2 - 1,
x)' returns `[x^2, [-1, 1, 1], 1]', since a quadratic polynomial in
`x^2' is easier to solve than a quartic polynomial in `x'.

   A few more examples of the kinds of polynomials `gpoly' can discover:

     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]

   The `poly' and `gpoly' functions accept a third integer argument
which specifies the largest degree of polynomial that is acceptable.
If this is `n', then only C vectors of length `n+1' or less will be
returned.  Otherwise, the `poly' or `gpoly' call will remain in
symbolic form.  For example, the equation solver can handle quartics
and smaller polynomials, so it calls `gpoly(EXPR, VAR, 4)' to discover
whether EXPR can be treated by its linear, quadratic, cubic, or quartic
formulas.

   The `pdeg' function computes the degree of a polynomial; `pdeg(p,x)'
is the highest power of `x' that appears in `p'.  This is the same as
`vlen(poly(p,x))-1', but is much more efficient.  If `p' is constant
with respect to `x', then `pdeg(p,x) = 0'.  If `p' is not a polynomial
in `x' (e.g., `pdeg(2 cos(x), x)', the function remains unevaluated.
It is possible to omit the second argument `x', in which case `pdeg(p)'
returns the highest total degree of any term of the polynomial,
counting all variables that appear in `p'.  Note that `pdeg(c) =
pdeg(c,x) = 0' for any nonzero constant `c'; the degree of the constant
zero is considered to be `-inf' (minus infinity).

   The `plead' function finds the leading term of a polynomial.  Thus
`plead(p,x)' is equivalent to `poly(p,x)_vlen(poly(p,x))', though again
more efficient.  In particular, `plead((2x+1)^10, x)' returns 1024
without expanding out the list of coefficients.  The value of
`plead(p,x)' will be zero only if `p = 0'.

   The `pcont' function finds the "content" of a polynomial.  This is
the greatest common divisor of all the coefficients of the polynomial.
With two arguments, `pcont(p,x)' effectively uses `poly(p,x)' to get a
list of coefficients, then uses `pgcd' (the polynomial GCD function) to
combine these into an answer.  For example, `pcont(4 x y^2 + 6 x^2 y,
x)' is `2 y'.  The content is basically the "biggest" polynomial that
can be divided into `p' exactly.  The sign of the content is the same
as the sign of the leading coefficient.

   With only one argument, `pcont(p)' computes the numerical content of
the polynomial, i.e., the `gcd' of the numerical coefficients of all
the terms in the formula.  Note that `gcd' is defined on rational
numbers as well as integers; it computes the `gcd' of the numerators
and the `lcm' of the denominators.  Thus `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.

   The `pprim' function finds the "primitive part" of a polynomial,
which is simply the polynomial divided (using `pdiv' if necessary) by
its content.  If the input polynomial has rational coefficients, the
result will have integer coefficients in simplest terms.


File: calc,  Node: Numerical Solutions,  Next: Curve Fitting,  Prev: Solving Equations,  Up: Algebra

12.7 Numerical Solutions
========================

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 `a S' before resorting to these commands.

   (*Note Curve Fitting::, for some other, more specialized, operations
on numerical data.)

* Menu:

* Root Finding::
* Minimization::
* Numerical Systems of Equations::


File: calc,  Node: Root Finding,  Next: Minimization,  Prev: Numerical Solutions,  Up: Numerical Solutions

12.7.1 Root Finding
-------------------

The `a R' (`calc-find-root') [`root'] command finds a numerical
solution (or "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 `X = 0'.)

   The `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
`=', 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 `v h' (`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 `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.

   The `H a R' [`wroot'] command is similar to `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
_is_ differentiable, Calc uses Newton's method which does not require a
bounding interval in order to work.)

   If Calc leaves the `root' or `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 `w' (`calc-why') to get it
back.


File: calc,  Node: Minimization,  Next: Numerical Systems of Equations,  Prev: Root Finding,  Up: Numerical Solutions

12.7.2 Minimization
-------------------

The `a N' (`calc-find-minimum') [`minimize'] command finds a minimum
value for a formula.  It is very similar in operation to `a R'
(`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 variable which minimizes the formula's value, along with the
minimum value itself.

   Note that this command looks for a _local_ minimum.  Many functions
have more than one minimum; some, like `x sin(x)', have infinitely
many.  In fact, there is no easy way to define the "global" minimum of
`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 `17 x'
over `[2..3]' will return `[2, 38]', but minimizing over `(2..3]' would
report no minimum found.  In general, you should use closed intervals
to find literally the minimum value in that range of `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.

   The `H a N' [`wminimize'] command, analogously to `H a R', expands
the guess interval to enclose a minimum rather than requiring that the
minimum lie inside the interval you supply.

   The `a X' (`calc-find-maximum') [`maximize'] and `H a X'
[`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.


File: calc,  Node: Numerical Systems of Equations,  Prev: Minimization,  Up: Numerical Solutions

12.7.3 Systems of Equations
---------------------------

The `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 `a N' (or
maximize with `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 `a R', the formula being minimized should still be a
single formula, _not_ a vector.  Beware that multidimensional
minimization is currently _very_ slow.


File: calc,  Node: Curve Fitting,  Next: Summations,  Prev: Numerical Solutions,  Up: Algebra

12.8 Curve Fitting
==================

The `a F' command fits a set of data to a "model formula", such as `y =
m x + b' where `m' and `b' are parameters to be determined.  For a
typical set of measured data there will be no single `m' and `b' that
exactly fit the data; in this case, Calc chooses values of the
parameters that provide the closest possible fit.  The model formula
can be entered in various ways after the key sequence `a F' is pressed.

   If the letter `P' is pressed after `a F' but before the model
description is entered, the data as well as the model formula will be
plotted after the formula is determined.  This will be indicated by a
"P" in the minibuffer after the help message.

* Menu:

* Linear Fits::
* Polynomial and Multilinear Fits::
* Error Estimates for Fits::
* Standard Nonlinear Models::
* Curve Fitting Details::
* Interpolation::


File: calc,  Node: Linear Fits,  Next: Polynomial and Multilinear Fits,  Prev: Curve Fitting,  Up: Curve Fitting

12.8.1 Linear Fits
------------------

The `a F' (`calc-curve-fit') [`fit'] command attempts to fit a set of
data (`x' and `y' vectors of numbers) to a straight line, polynomial,
or other function of `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 `(x,y)'
data points that we wish to fit to the model `y = m x + b' by adjusting
the parameters `m' and `b' to make the `y' values calculated from the
formula be as close as possible to the actual `y' values in the data
set.  (In a polynomial fit, the model is instead, say, `y = a x^3 + b
x^2 + c x + d'.  In a multilinear fit, we have data points of the form
`(x_1,x_2,x_3,y)' and our model is `y = a x_1 + b x_2 + c x_3 + d'.
These will be discussed later.)

   In the model formula, variables like `x' and `x_2' are called the
"independent variables", and `y' is the "dependent variable".
Variables like `m', `a', and `b' are called the "parameters" of the
model.

   The `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 2xN matrix where the
first row is a list of `x' values and the second row has the
corresponding `y' values.  For the multilinear fit shown above, the
matrix would have four rows (`x_1', `x_2', `x_3', and `y',
respectively).

   If you happen to have an Nx2 matrix instead of a 2xN matrix, just
press `v t' first to transpose the matrix.

   After you type `a F', Calc prompts you to select a model.  For a
linear fit, press the digit `1'.

   Calc then prompts for you to name the variables.  By default it
chooses high letters like `x' and `y' for independent variables and low
letters like `a' and `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

     [ [ 1, 2, 3, 4,  5  ]
       [ 5, 7, 9, 11, 13 ] ]

is on the stack and we wish to do a simple linear fit.  Type `a F',
then `1' for the model, then <RET> to use the default names.  The
result will be the formula `3. + 2. x' on the stack.  Calc has created
the model expression `a + b x', then found the optimal values of `a'
and `b' to fit the data.  (In this case, it was able to find an exact
fit.)  Calc then substituted those values for `a' and `b' in the model
formula.

   The `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: `[a = 3, b = 2]', in
case you'd rather read them in a list than pick them out of the
formula.  (You can type `t y' to move this vector to the stack; see
*note Trail Commands::.

   Specifying a different independent variable name will affect the
resulting formula: `a F 1 k <RET>' produces `3 + 2 k'.  Changing the
parameter names (say, `a F 1 k;b,m <RET>') will affect the equations
that go into the trail.

   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:

     2.6 + 2.2 x

   Evaluating this formula, say with `v x 5 <RET> <TAB> V M $ <RET>',
shows a reasonably close match to the y-values in the data.

     [4.8, 7., 9.2, 11.4, 13.6]

   Since there is no line which passes through all the 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 "chi-square" error
measure

     chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N)

which is clearly zero if `a + b x' exactly fits all data points, and
increases as various `a + b x_i' values fail to match the corresponding
`y_i' values.  There are several reasons why the summand is squared,
one of them being to ensure that `chi^2 >= 0'.  Least-squares fitting
simply chooses the values of `a' and `b' for which the error `chi^2' is
as small as possible.

   Other kinds of models do the same thing but with a different model
formula in place of `a + b x_i'.

   A numeric prefix argument causes the `a F' command to take the data
in some other form than one big matrix.  A positive argument N will
take N items from the stack, corresponding to the N rows of a data
matrix.  In the linear case, N must be 2 since there is always one
independent variable and one dependent variable.

   A prefix of zero or plain `C-u' is a compromise; Calc takes two
items from the stack, an N-row matrix of `x' values, and a vector of
`y' values.  If there is only one independent variable, the `x' values
can be either a one-row matrix or a plain vector, in which case the
`C-u' prefix is the same as a `C-u 2' prefix.


File: calc,  Node: Polynomial and Multilinear Fits,  Next: Error Estimates for Fits,  Prev: Linear Fits,  Up: Curve Fitting

12.8.2 Polynomial and Multilinear Fits
--------------------------------------

To fit the data to higher-order polynomials, just type one of the
digits `2' through `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 `a F 2 <RET>'.

     2.00000000001 x - 1.5e-12 x^2 + 2.99999999999

   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
`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 `m f' first to get Fraction mode.  Then the `x^2' term would
vanish altogether.  Usually, though, the data being fitted will be
approximate floats so Fraction mode won't help.)

   Doing the `a F 2' fit on the data set with 14 instead of 13 gives a
much larger `x^2' contribution, as Calc bends the line slightly to
improve the fit.

     0.142857142855 x^2 + 1.34285714287 x + 3.59999999998

   An important result from the theory of polynomial fitting is that it
is always possible to fit N data points exactly using a polynomial of
degree N-1, sometimes called an "interpolating polynomial".  Using the
modified (14) data matrix, a model number of 4 gives a polynomial that
exactly matches all five data points:

     0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4.

   The actual coefficients we get with a precision of 12, like
`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 `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 `a p' command described
below.  *Note Interpolation::.

   Another generalization of the linear model is to assume the `y'
values are a sum of linear contributions from several `x' values.  This
is a "multilinear" fit, and it is also selected by the `1' digit key.
(Calc decides whether the fit is linear or multilinear by counting the
rows in the data matrix.)

   Given the data matrix,

     [ [  1,   2,   3,    4,   5  ]
       [  7,   2,   3,    5,   2  ]
       [ 14.5, 15, 18.5, 22.5, 24 ] ]

the command `a F 1 <RET>' will call the first row `x' and the second
row `y', and will fit the values in the third row to the model `a + b x
+ c y'.

     8. + 3. x + 0.5 y

   Calc can do multilinear fits with any number of independent variables
(i.e., with any number of data rows).

   Yet another variation is "homogeneous" linear models, in which the
constant term is known to be zero.  In the linear case, this means the
model formula is simply `a x'; in the multilinear case, the model might
be `a x + b y + c z'; and in the polynomial case, the model could be `a
x + b x^2 + c x^3'.  You can get a homogeneous linear or multilinear
model by pressing the letter `h' followed by a regular model key, like
`1' or `2'.  This will be indicated by an "h" in the minibuffer after
the help message.

   It is certainly possible to have other constrained linear models,
like `2.3 + a x' or `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 `a F ' 2.3 +
a x'.

   Another class of models that will work but must be entered by hand
are multinomial fits, e.g., `a + b x + c y + d x^2 + e y^2 + f x y'.


File: calc,  Node: Error Estimates for Fits,  Next: Standard Nonlinear Models,  Prev: Polynomial and Multilinear Fits,  Up: Curve Fitting

12.8.3 Error Estimates for Fits
-------------------------------

With the Hyperbolic flag, `H a F' [`efit'] performs the same fitting
operation as `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 `H a F' gives the results,

     3. + 2. x
     2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x

   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 _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 `Y_I +/- SIGMA_I', then the `chi^2' statistic is
now,

     chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N)

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 `sigma_i' used for the data
point.

   Both `a F' and `H a F' can accept error forms in the input matrix,
although if you are concerned about error analysis you will probably
use `H a F' so that the output also contains error estimates.

   If the input contains error forms but all the `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 (`chi^2' is simply
scaled uniformly by `1 / sigma^2', which doesn't affect where it has a
minimum).  But there _will_ be a difference in the estimated errors of
the coefficients reported by `H a F'.

   Consult any text on statistical modeling of data for a discussion of
where these error estimates come from and how they should be
interpreted.

   With the Inverse flag, `I a F' [`xfit'] produces even more
information.  The result is a vector of six items:

  1. The model formula with error forms for its coefficients or
     parameters.  This is the result that `H a F' would have produced.

  2. 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 `I a F' command.  For polynomials of degree `d', this vector
     will have length `M = d+1' with the constant term first.

  3. The covariance matrix `C' computed from the fit.  This is an MxM
     symmetric matrix; the diagonal elements `C_j_j' are the variances
     `sigma_j^2' of the parameters.  The other elements are covariances
     `sigma_i_j^2' that describe the correlation between pairs of
     parameters.  (A related set of numbers, the "linear correlation
     coefficients" `r_i_j', are defined as `sigma_i_j^2 / sigma_i
     sigma_j'.)

  4. A vector of `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.

  5. The value of `chi^2' for the fit, calculated by the formulas shown
     above.  This gives a measure of the quality of the fit;
     statisticians consider `chi^2 = N - M' to indicate a moderately
     good fit (where again `N' is the number of data points and `M' is
     the number of parameters).

  6. A measure of goodness of fit expressed as a probability `Q'.  This
     is computed from the `utpc' probability distribution function using
     `chi^2' with `N - M' degrees of freedom.  A value of 0.5 implies a
     good fit; some texts recommend that often `Q = 0.1' or even 0.001
     can signify an acceptable fit.  In particular, `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 `Q'.

     The `Q' value is computed only if the input included error
     estimates.  Otherwise, Calc will report the symbol `nan' for `Q'.
     The reason is that in this case the `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.


File: calc,  Node: Standard Nonlinear Models,  Next: Curve Fitting Details,  Prev: Error Estimates for Fits,  Up: Curve Fitting

12.8.4 Standard Nonlinear Models
--------------------------------

The `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 `a F':

`1'
     Linear or multilinear.  a + b x + c y + d z.

`2-9'
     Polynomials.  a + b x + c x^2 + d x^3.

`e'
     Exponential.  a exp(b x) exp(c y).

`E'
     Base-10 exponential.  a 10^(b x) 10^(c y).

`x'
     Exponential (alternate notation).  exp(a + b x + c y).

`X'
     Base-10 exponential (alternate).  10^(a + b x + c y).

`l'
     Logarithmic.  a + b ln(x) + c ln(y).

`L'
     Base-10 logarithmic.  a + b log10(x) + c log10(y).

`^'
     General exponential.  a b^x c^y.

`p'
     Power law.  a x^b y^c.

`q'
     Quadratic.  a + b (x-c)^2 + d (x-e)^2.

`g'
     Gaussian.  (a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2).

`s'
     Logistic _s_ curve.  a/(1 + exp(b (x - c))).

`b'
     Logistic bell curve.  a exp(b (x - c))/(1 + exp(b (x - c)))^2.

`o'
     Hubbert linearization.  (y/x) = a (1 - x/b).

   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, logistics, Hubbert and polynomials can
generalize as shown to any number of independent variables.  Also, all
the built-in models except for the logistic and Hubbert curves have an
additive or multiplicative parameter shown as `a' in the above table
which can be replaced by zero or one, as appropriate, by typing `h'
before the model key.

   Note that many of these models are essentially equivalent, but
express the parameters slightly differently.  For example, `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 `LIN', `LOG', `EXP', and `PWR'.  These correspond to
Calc models `a + b x', `a + b ln(x)', `a exp(b x)', and `a x^b',
respectively.  In each case, `a' is what the HP-48 identifies as the
"intercept," and `b' is what it calls the "slope."

   If the model you want doesn't appear on this list, press `'' (the
apostrophe key) at the model prompt to enter any algebraic formula,
such as `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 `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 (`m' and `b') and two independent
variables (`x' and `y'), with no "dependent" variables.  Model equations
do not need to take this `y =' form.  For example, the implicit line
equation `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 `a,mu,sigma,t,x',
and the data matrix has three rows (meaning two independent variables),
Calc will use `a,mu,sigma' as the default parameters, and the data rows
will be named `t' and `x', respectively.  If you enter an equation
instead of a plain formula, Calc will use `a,mu' as the parameters, and
`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 `a F' command.)  If you list
only independent variables, all the remaining variables in the model
formula will become parameters.

   If there are `$' signs in the model you type, they will stand for
parameters and all other variables (in alphabetical order) will be
independent.  Use `$' for one parameter, `$$' for another, and so on.
Thus `$ x + $$' is another way to describe a linear model.

   If you type a `$' instead of `'' 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, `[MODEL, VARS]' or `[MODEL, VARS, PARAMS]'.  Each of
VARS and PARAMS may be either a variable or a vector of variables.  (If
PARAMS is omitted, all variables in MODEL except those listed as VARS
are parameters.)

   When you enter a model manually with `'', Calc puts a 3-vector
describing the model in the trail so you can get it back if you wish.

   Finally, you can store a model in one of the Calc variables `Model1'
or `Model2', then use this model by typing `a F u' or `a F U'
(respectively).  The value stored in the variable can be any of the
formats that `a F $' would accept for a model on the stack.

   Calc uses the principal values of inverse functions like `ln' and
`arcsin' when doing fits.  For example, when you enter the model `y =
sin(a t + b)' Calc actually uses the easier form `arcsin(y) = a t + b'.
The `arcsin' function always returns results in the range from -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 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 `arcsin(y) = a t
+ b' will grow smoothly with `t', but the lefthand side will bounce
back and forth between -90 and 90.  No values of `a' and `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 `a F' command.
(Unfortunately, Calc does not currently have any facilities for taking
Fourier and related transforms.)


File: calc,  Node: Curve Fitting Details,  Next: Interpolation,  Prev: Standard Nonlinear Models,  Up: Curve Fitting

12.8.5 Curve Fitting Details
----------------------------

Calc's internal least-squares fitter can only handle multilinear
models.  More precisely, it can handle any model of the form `a
f(x,y,z) + b g(x,y,z) + c h(x,y,z)', where `a,b,c' are the parameters
and `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 `a + b
x + c x^2', then `f(x) = 1', `g(x) = x', and `h(x) = x^2' are suitable
functions.

   For most other models, Calc uses a variety of algebraic manipulations
to try to put the problem into the form

     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)

where `Y,A,B,C,F,G,H' are arbitrary functions.  It computes `Y', `F',
`G', and `H' for all the data points, does a standard linear fit to
find the values of `A', `B', and `C', then uses the equation solver to
solve for `a,b,c' in terms of `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 `y = a x^b' with two independent variables and two parameters can
be rewritten as follows:

     y = a x^b
     y = a exp(b ln(x))
     y = exp(ln(a) + b ln(x))
     ln(y) = ln(a) + b ln(x)

which matches the desired form with `Y = ln(y)', `A = ln(a)', `F = 1',
`B = b', and `G = ln(x)'.  Calc thus computes the logarithms of your
`y' and `x' values, does a linear fit for `A' and `B', then solves to
get `a = exp(A)' and `b = B'.

   Another interesting example is the "quadratic" model, which can be
handled by expanding according to the distributive law.

     y = a + b*(x - c)^2
     y = a + b c^2 - 2 b c x + b x^2

which matches with `Y = y', `A = a + b c^2', `F = 1', `B = -2 b c', `G
= x' (the -2 factor could just as easily have been put into `G' instead
of `B'), `C = b', and `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 `Y'.

   The logistic models cannot be put into general linear form.  For
these models, and the Hubbert linearization, Calc computes a rough
approximation for the parameters, then uses the Levenberg-Marquardt
iterative method to refine the approximations.

   Another model that cannot be put into general linear form is a
Gaussian with a constant background added on, i.e., `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 `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-D model can be linearized by
setting `d' (the background) to a constant, or by setting `b' (the
standard deviation) and `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.

   A last desperate step would be to use the general-purpose `minimize'
function rather than `fit'.  After all, both functions solve the
problem of minimizing an expression (the `chi^2' sum) by adjusting
certain parameters in the expression.  The `a F' command is able to use
a vastly more efficient algorithm due to its special knowledge about
linear chi-square sums, but the `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 `minimize' on a call to `fit' which
efficiently takes care of the rest of the parameters.  The thing to be
minimized would be the value of `chi^2' returned as the fifth result of
the `xfit' function:

     minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess)

where `gaus' represents the Gaussian model with background, `data'
represents the data matrix, and `guess' represents the initial guess
for `d' that `minimize' requires.  This operation will only be, shall
we say, extraordinarily slow rather than astronomically slow (as would
be the case if `minimize' were used by itself to solve the problem).

   The `I a F' [`xfit'] command is somewhat trickier when nonlinear
models are used.  The second item in the result is the vector of "raw"
parameters `A', `B', `C'.  The covariance matrix is written in terms of
those raw parameters.  The fifth item is a vector of "filter"
expressions.  This is the empty vector `[]' if the raw parameters were
the same as the requested parameters, i.e., if `A = a', `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 `fitdummy(1)' for `A', `fitdummy(2)' for
`B', and so on.

   When Calc needs to modify the model to return the result, it replaces
`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 `H a F' and `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 `I a F' with a nonlinear model, be sure to remember that
the covariance matrix is in terms of the raw parameters, _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, `x', `y',
and `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 `x' and `y' to be plain
numbers, and makes `z' into an error form with this combined error.
The `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 `sigma_i' for the data point.  If for some reason `Y(x,y,z)' does
not return an error form, the combined error from `z' is used directly
for `sigma_i'.  Finally, `z' is also stripped of its error for use in
computing `F(x,y,z)', `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 `Y(x,y,z)' depends only
on the dependent variable `z', and in fact is often simply equal to
`z'.  For common cases like polynomials and multilinear models, the
combined error is simply used as the `sigma' for the data point with no
further ado.)

   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 `FitRules'.  You can edit this variable using
the `s e FitRules' command; in fact, there is a special `s F' command
just for editing `FitRules'.  *Note Operations on Variables::.

   *Note Rewrite Rules::, for a discussion of rewrite rules.

   Calc uses `FitRules' as follows.  First, it converts the model to an
equation if necessary and encloses the model equation in a call to the
function `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 `fitparam(1)', `fitparam(2)',
and so on, and independent variables are renamed to `fitvar(1)',
`fitvar(2)', etc.  The dependent variable is the highest-numbered
`fitvar'.  For example, the power law model `a x^b' is converted to `y
= a x^b', then to

     fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2))

   Calc then applies the rewrites as if by `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 `fitmodel' call should have been
replaced by a `fitsystem' call that looks like this:

     fitsystem(Y, FGH, ABC)

where Y is a formula that describes the function `Y(x,y,z)', FGH is the
vector of formulas `[F(x,y,z), G(x,y,z), H(x,y,z)]', and ABC is the
vector of parameter filters which refer to the raw parameters as
`fitdummy(1)' for `A', `fitdummy(2)' for `B', etc.  While the number of
raw parameters (the length of the FGH vector) is usually the same as
the number of original parameters (the length of the ABC vector), this
is not required.

   The power law model eventually boils down to

     fitsystem(ln(fitvar(2)),
               [1, ln(fitvar(1))],
               [exp(fitdummy(1)), fitdummy(2)])

   The actual implementation of `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 `exp' and `ln'
either all the way "out" (so that they can be put into Y) or all the
way "in" (so that they can be put into ABC or 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 `fitinv' function, where `fitinv(x)' represents
`1/x' while the `FitRules' are operating.  (The use of `fitinv' makes
recognition of linear-looking forms easier.)  If you modify `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 `fitmodel' to a two-argument form `fitmodel(Y,
MODEL)', where Y is initially zero and MODEL has been changed from `a=b'
to `a-b' form.  It then tries to peel off invertible functions from the
outside of MODEL and put them into Y instead, calling the equation
solver to invert the functions.  Finally, when this is no longer
possible, the `fitmodel' is changed to a four-argument `fitsystem',
where the fourth argument is MODEL and the FGH and ABC vectors are
initially empty.  (The last vector is really ABC, corresponding to raw
parameters, for now.)

   Phase three converts a sum of items in the MODEL to a sum of
`fitpart(A, B, C)' terms which represent terms `A*B*C' of the sum,
where A is all factors that do not involve any variables, B is all
factors that involve only parameters, and 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 `fitpart's with equal B or C components are merged
back together using the distributive law in order to minimize the
number of raw parameters needed.

   Phase four moves the `fitpart' terms into the FGH and 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 ABC vector to
an ABC vector, and removes the fourth MODEL argument (which by now will
be zero) to obtain the three-argument `fitsystem' that the linear
least-squares solver wants to see.

   Two functions which are useful in connection with `FitRules' are
`hasfitparams(x)' and `hasfitvars(x)', which check whether `x' refers
to any parameters or independent variables, respectively.
Specifically, these functions return "true" if the argument contains
any `fitparam' (or `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 N from all the
`fitparam(N)'s or `fitvar(N)'s, respectively, that appear in the
formula.)

   The `fit' function in algebraic notation normally takes four
arguments, `fit(MODEL, VARS, PARAMS, DATA)', where MODEL is the model
formula as it would be typed after `a F '', VARS is the independent
variable or a vector of independent variables, PARAMS likewise gives
the parameter(s), and DATA is the data matrix.  Note that the length of
VARS must be equal to the number of rows in DATA if MODEL is an
equation, or one less than the number of rows if MODEL is a plain
formula.  (Actually, a name for the dependent variable is allowed but
will be ignored in the plain-formula case.)

   If PARAMS is omitted, the parameters are all variables in MODEL
except those that appear in VARS.  If VARS is also omitted, Calc sorts
all the variables that appear in MODEL alphabetically and uses the
higher ones for VARS and the lower ones for PARAMS.

   Alternatively, `fit(MODELVEC, DATA)' is allowed where MODELVEC is a
2- or 3-vector describing the model and variables, as discussed
previously.

   If Calc is unable to do the fit, the `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 `efit' (corresponding to `H a F') and `xfit' (for `I a F')
functions are completely analogous.


File: calc,  Node: Interpolation,  Prev: Curve Fitting Details,  Up: Curve Fitting

12.8.6 Polynomial Interpolation
-------------------------------

The `a p' (`calc-poly-interp') [`polint'] command does a polynomial
interpolation at a particular `x' value.  It takes two arguments from
the stack:  A data matrix of the sort used by `a F', and a single
number which represents the desired `x' value.  Calc effectively does
an exact polynomial fit as if by `a F i', then substitutes the `x'
value into the result in order to get an approximate `y' value based on
the fit.  (Calc does not actually use `a F i', however; it uses a
direct method which is both more efficient and more numerically stable.)

   The result of `a p' is actually a vector of two values:  The `y'
value approximation, and an error measure `dy' that reflects Calc's
estimation of the probable error of the approximation at that value of
`x'.  If the input `x' is equal to any of the `x' values in the data
matrix, the output `y' will be the corresponding `y' value from the
matrix, and the output `dy' will be exactly zero.

   A prefix argument of 2 causes `a p' to take separate x- and
y-vectors from the stack instead of one data matrix.

   If `x' is a vector of numbers, `a p' will return a matrix of
interpolated results for each of those `x' values.  (The matrix will
have two columns, the `y' values and the `dy' values.)  If `x' is a
formula instead of a number, the `polint' function remains in symbolic
form; use the `a "' command to expand it out to a formula that
describes the fit in symbolic terms.

   In all cases, the `a p' command leaves the data vectors or matrix on
the stack.  Only the `x' value is replaced by the result.

   The `H a p' [`ratint'] command does a rational function
interpolation.  It is used exactly like `a p', except that it uses as
its model the quotient of two polynomials.  If there are `N' data
points, the numerator and denominator polynomials will each have degree
`N/2' (if `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 `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 `[uinf, uinf]'.

   There is no way to get the actual coefficients of the rational
function used by `H a p'.  (The algorithm never generates these
coefficients explicitly, and quotients of polynomials are beyond `a F''s
capabilities to fit.)


File: calc,  Node: Summations,  Next: Logical Operations,  Prev: Curve Fitting,  Up: Algebra

12.9 Summations
===============

The `a +' (`calc-summation') [`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, `' k^2 <RET> ' k <RET> 1
<RET> 5 <RET> a + <RET>' produces the result 55.

   The choice of index variable is arbitrary, but it's best not to use
a variable with a stored value.  In particular, while `i' is often a
favorite index variable, it should be avoided in Calc because `i' has
the imaginary constant `(0, 1)' as a value.  If you pressed `=' on a
sum over `i', it would be changed to a nonsensical sum over the
"variable" `(0, 1)'!  If you really want to use `i' as an index
variable, use `s u i <RET>' first to "unstore" this variable.  (*Note
Storing Variables::.)

   A numeric prefix argument steps the index by that amount rather than
by one.  Thus `' a_k <RET> C-u -2 a + k <RET> 10 <RET> 0 <RET>' yields
`a_10 + a_8 + a_6 + a_4 + a_2 + a_0'.  A prefix argument of plain `C-u'
causes `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 `C-u' prefix, `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,
`sum(6 k^2, k, 1, n) = 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 `sum(EXPR, VAR, LOW,
HIGH, STEP)'.  If STEP is omitted, it defaults to one.  If HIGH is
omitted, LOW is actually the upper limit and the lower limit is one.
If LOW is also omitted, the limits are `-inf' and `inf', respectively.

   Infinite sums can sometimes be evaluated:  `sum(.5^k, k, 1, inf)'
returns `1'.  This is done by evaluating the sum in closed form (to `1.
- 0.5^n' in this case), then evaluating this formula with `n' set to
`inf'.  Calc's usual rules for "infinite" arithmetic can find the
answer from there.  If infinite arithmetic yields a `nan', or if the
sum cannot be solved in closed form, Calc leaves the `sum' function in
symbolic form.  *Note 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 valid
subscripts for the vector.  For example, the sum `sum(k
[a,b,c,d,e,f,g]_(2k),k)' evaluates to `b + 2 d + 3 f'.

   The limits of a sum do not need to be integers.  For example,
`sum(a_k, k, 0, 2 n, n)' produces `a_0 + a_n + a_(2 n)'.  Calc computes
the number of iterations using the formula `1 + (HIGH - LOW) / STEP',
which must, after simplification as if by `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 invalid 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, `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 -1.  Thus
`sum(f(k), k, n, n-1)' is zero but the sum from `n' to `n-2' may report
a nonzero value if Calc used a closed form solution.

   Calc's logical predicates like `a < b' return 1 for "true" and 0 for
"false."  *Note Logical Operations::.  This can be used to advantage
for building conditional sums.  For example, `sum(prime(k)*k^2, k, 1,
20)' is the sum of the squares of all prime numbers from 1 to 20; the
`prime' predicate returns 1 if its argument is prime and 0 otherwise.
You can read this expression as "the sum of `k^2', where `k' is prime."
Indeed, `sum(prime(k)*k^2, k)' would represent the sum of _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, `sum((k != k_0) * f(k), k, 1, n)' is the sum of
`f(k)' for all `k' from 1 to `n', excluding one value `k_0'.  Slightly
more tricky is the summand `(k != k_0) / (k - k_0)', which is an
attempt to describe the sum of all `1/(k-k_0)' except at `k = k_0',
where this would be a division by zero.  But at `k = k_0', this formula
works out to the indeterminate form `0 / 0', which Calc will not assume
is zero.  Better would be to use `(k != k_0) ? 1/(k-k_0) : 0'; the `?
:' operator does an "if-then-else" test:  This expression says, "if `k
!= k_0', then `1/(k-k_0)', else zero."  Now the formula `1/(k-k_0)'
will not even be evaluated by Calc when `k = k_0'.

   The `a -' (`calc-alt-summation') [`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 `(-1)^(k-LOW)'.  This formula is
adjusted appropriately if the step value is other than one.  For
example, the Taylor series for the sine function is `asum(x^k / k!, k,
1, inf, 2)'.  (Calc cannot evaluate this infinite series, but it can
approximate it if you replace `inf' with any particular odd number.)
Calc converts this series to a regular sum with a step of one, namely
`sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)'.

   The `a *' (`calc-product') [`prod'] command is the analogous way to
take a product of many terms.  Calc also knows some closed forms for
products, such as `prod(k, k, 1, n) = n!'.  Conditional products can be
written `prod(k^prime(k), k, 1, n)' or `prod(prime(k) ? k : 1, k, 1,
n)'.

   The `a T' (`calc-tabulate') [`table'] command evaluates a formula at
a series of iterated index values, just like `sum' and `prod', but its
result is simply a vector of the results.  For example, `table(a_i, i,
1, 7, 2)' produces `[a_1, a_3, a_5, a_7]'.