Root Finder for Continuous Univariate Functions.

DESCRIPTION:

Approximates a root or zero of a continuous univariate function given an interval for which the function has opposite signs at the endpoints.

USAGE:

uniroot(f, interval, 
        lower = min(interval), upper = max(interval), 
        tol = .Machine$double.eps^.25, keep.xy = F, 
        f.lower = NA,  f.upper = NA, ...) 

REQUIRED ARGUMENTS:

f
a real-valued S-PLUS function of the form f(x,<additional arguments>), where x is the variable in question. Users can accumulate information through attributes of the function value. If the attributes includes additional arguments of f, the next function call will use the new values of those arguments.
interval
a vector of values whose maximum and minimum specify the interval over which the minimization is to take place. (Optional if both lower and upper are specified.)

OPTIONAL ARGUMENTS:

lower
left endpoint of the initial interval.
upper
right endpoint of the initial interval.
tol
desired length of the interval of uncertainty in the final result.
keep.xy
tells whether or not to accumulate the points used by uniroot and the corresponding function values as x and y components in the output.
f.lower
The value of f at the left endpoint of the initial interval.
f.upper
The value of f at the right endpoint of the initial interval.
...
additional arguments for f.

VALUE:

a list containing the following elements :
root
a point that is within tol of a root or zero of f in [lower,upper].
f.root
the value of f at root.
singularity
if a singularity is encountered, this gives the point at which it occurs together with the corresponding function value (NA, NaN, or Inf).
nf
the number of times f was evaluated.
neg, pos
the closest point to root for which the sign of f is known to be negative/positive. May be used as interval endpoints when restarting the algorithm with a smaller value of tolerance.
f.neg, f.pos
the values of f at neg and pos, respectively.
message
a statement of the reason for termination.
aux
the list of attributes returned after the last function call.
call
a copy of the call to uniroot.
x
the vector of points at which f is evaluated by uniroot (in order). Present only if keep.xy = T.
y
the function values associated with x. Present only if keep.xy = T.

NOTE:

The function f must have opposite signs at the initial endpoints lower and upper, in order to ensure that f actually has a root within [lower,upper] . Function values should be computed in C or Fortran within the outer S-PLUS function for greater efficiency. The uniroot function may not be called recursively, that is, f may not call uniroot . Recursive calls would overwrite information that is stored internally.

METHOD:

Implements Brent's safeguarded polynomial interpolation procedure for solving a univariate nonlinear equation, based on the Fortran function zeroin from NETLIB (Dongarra and Grosse 1987).

REFERENCES:

Brent, R. (1973). Algorithms for Minimization without Derivatives. Prentice-Hall, Englewood Cliffs, NJ, USA. Dongarra, J. J., and Grosse, E. (1987). Distribution of mathematical software via electronic mail, Communications of the ACM 30 , pp. 403-407.

SEE ALSO:

, , , . To solve a system of nonlinear equations, see ; that help file contains an example solveNonlinear function.

EXAMPLES:

cubic <- function(x, c2, c1, c0) {(x - c2) *  
                 (x - c1) * (x - c0)} 
uniroot(cubic, c(1,3), keep.xy=T, c2=-2, c1=0, c0=2) 
cubic <- function(x, c2, c1, c0, nf=0, 
                  all=list(x=NULL, y=NULL)) {
value <- (x - c0) * (x - c1) * (x - c2) 
attributes(value) <- list(nf=nf + length(x), 
      all=list(x=c(all$x, x), y=c(all$y, value)))
value } 
uniroot(cubic, lower=1, upper=3, c2=-2, c1=0, c0=2)