uniroot
Find a Root of a Univariate Function

Description

Approximates a root or zero of a continuous univariate function for a specified interval. If the endpoints of the function do not have opposite signs, the search interval is allowed to be auto-extended by setting extendInt as non-"no" string.

Usage

uniroot(f, interval, ..., lower = min(interval), upper = max(interval),
    f.lower = f(lower, ...), f.upper = f(upper, ...),
    extendInt = c("no", "yes", "downX", "upX"), check.conv = FALSE,
    tol = .Machine$double.eps^0.25, maxiter = 1000, trace = 0)

Arguments

f a real-valued function of one or more arguments. The first argument, no matter what its name, is varied in the search for a root. The other arguments should be supplied as the ... argument to uniroot.
interval a vector of 2 numeric values whose maximum and minimum values specify the interval over which the minimization is be determined. Not required if you specify both lower and upper.
... additional arguments for f.
lower n numeric value that specifies the lower endpoint of the initial interval to search.
upper a numeric value that specifies the upper endpoint of the initial interval to search. Should be greater than lower.
f.lower the numeric value of f at the lower endpoint of the initial interval. Its default value is f(lower,...) so it is almost never required. Try it if f has value NaN at lower, but you know the limiting value there.
f.upper the numeric value of f at the upper endpoint of the initial interval.
extendInt One of the character strings "no" (the default), "yes", "downX", or "upX", determining how to extend the interval if the function does not cross zero in the given interval. See Details for their descriptions.
check.conv a logical value. If FALSE (the default), just warn if the root could not be found to to desired accuracy. If TRUE, give an error in that case.
tol a numeric value indicating the desired accuracy in the final result.
maxiter an integer that specifies the maximum number of iterations.
trace a non-negative integer specifying the trace level while extending the initial interval. Can be one of the following.
0 no trace information
1 simple trace information
2 more detailed trace information
See Examples for their difference.

Details

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).
To ensure that f has a root within [lower,upper], the function f must have opposite signs or be zero at the initial endpoints lower and upper before calling the function zeroin.
It can be difficult to determine how big to make the interval, so you can use the extendInt argument to have the original interval extended, little by little, until it the function has a root in the extended interval. If a satisfactory interval cannot be found, an error is given.
Value
returns a named list that contains the following elements:
root a numeric value that is within the accuracy value specified in tol of a zero of f in the range [lower,upper](maybe the modified).
f.root value of f at root.
iter the number of iterations required to find the root. This value includes the iterations required to extend the interval.
init.it an integer value specifying the number of steps required to extend the the interval so that f crossed zero in this expanded interval. NA if the interval did not need to be expanded.
estim.prec a numeric value that shows the approximate estimated precision for root.
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
optimize, polyroot.
Examples
cubic <- function(x, c2, c1, c0) {(x - c2) *  
                 (x - c1) * (x - c0)} 
uniroot(cubic, c(1,3), c2=-2, c1=-0.5, c0=2) # root at 2
uniroot(cubic, c(-1,1), c2=-2, c1=-0.5, c0=2) # root at -0.5

try(uniroot(cubic, c(3,5), c2=-2, c1=-0.5, c0=2))
uniroot(cubic, c(3,5), c2=-2, c1=-0.5, c0=2, extendInt = "yes", trace=2)

# convergence checking
try(uniroot(cubic, c(1,5), c2=-2, c1=-0.5, c0=2, maxiter=3, check.conv=TRUE)) # Error stop
uniroot(cubic, c(1,5), c2=-2, c1=-0.5, c0=2, maxiter=3)  # just warning.
Package stats version 6.1.2-7
Package Index