\HeaderA{uniroot}{One Dimensional Root (Zero) Finding}{uniroot}
\keyword{optimize}{uniroot}
\begin{Description}\relax
The function \code{uniroot} searches the interval from \code{lower}
to \code{upper} for a root (i.e., zero) of the function \code{f} with
respect to its first argument.
\end{Description}
\begin{Usage}
\begin{verbatim}
uniroot(f, interval, ...,
        lower = min(interval), upper = max(interval),
        f.lower = f(lower, ...), f.upper = f(upper, ...),
        tol = .Machine$double.eps^0.25, maxiter = 1000)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{f}] the function for which the root is sought.
\item[\code{interval}] a vector containing the end-points of the interval
to be searched for the root.
\item[\code{...}] additional named or unnamed arguments to be passed
to \code{f}
\item[\code{lower, upper}] the lower and upper end points of the interval to
be searched.
\item[\code{f.lower, f.upper}] the same as \code{f(upper)} and
\code{f(lower)}, respectively.  Passing these values from the caller
where they are often known is more economical as soon as \code{f()}
contains non-trivial computations.
\item[\code{tol}] the desired accuracy (convergence tolerance).
\item[\code{maxiter}] the maximum number of iterations.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Note that arguments after \code{...} must be matched exactly.

Either \code{interval} or both \code{lower} and \code{upper} must be
specified: the upper endpoint must be strictly larger than the lower
endpoint.  The function values at the endpoints must be of opposite
signs (or zero).

The function uses Fortran subroutine \file{"zeroin"} (from Netlib)
based on algorithms given in the reference below.  They assume a
continuous function (which then is known to have at least one root in
the interval).

Convergence is declared either if \code{f(x) == 0} or the change in
\code{x} for one step of the algorithm is less than \code{tol} (plus an
allowance for representation error in \code{x}).

If the algorithm does not converge in \code{maxiter} steps, a warning
is printed and the current approximation is returned.

\code{f} will be called as \code{f(\var{x}, ...)} for a numeric value
of \var{x}.
\end{Details}
\begin{Value}
A list with four components: \code{root} and \code{f.root} give the
location of the root and the value of the function evaluated at that
point. \code{iter} and \code{estim.prec} give the number of iterations
used and an approximate estimated precision for \code{root}.  (If the
root occurs at one of the endpoints, the estimated precision is
\code{NA}.)
\end{Value}
\begin{Source}\relax
Based on \file{zeroin.c} in \url{http://www.netlib.org/c/brent.shar}.
\end{Source}
\begin{References}\relax
Brent, R. (1973)
\emph{Algorithms for Minimization without Derivatives.}
Englewood Cliffs, NJ: Prentice-Hall.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{polyroot}{polyroot}} for all complex roots of a polynomial;
\code{\LinkA{optimize}{optimize}}, \code{\LinkA{nlm}{nlm}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(utils) # for str

f <- function (x,a) x - a
str(xmin <- uniroot(f, c(0, 1), tol = 0.0001, a = 1/3))
str(uniroot(function(x) x*(x^2-1) + .5, lower = -2, upper = 2,
            tol = 0.0001), dig = 10)
str(uniroot(function(x) x*(x^2-1) + .5, lower = -2, upper = 2,
            tol = 1e-10 ), dig = 10)

## Find the smallest value x for which exp(x) > 0 (numerically):
r <- uniroot(function(x) 1e80*exp(x)-1e-300, c(-1000,0), tol = 1e-15)
str(r, digits= 15) ##> around -745, depending on the platform.

exp(r$root)     # = 0, but not for r$root * 0.999...
minexp <- r$root * (1 - 10*.Machine$double.eps)
exp(minexp)     # typically denormalized
\end{ExampleCode}
\end{Examples}

