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.