rstpm2 (version 1.4.5)

vuniroot: Vectorised One Dimensional Root (Zero) Finding

Description

The function vuniroot searches the interval from lower to upper for a root (i.e., zero) of the vectorised function f with respect to its first argument.

Usage

vuniroot(f, …,
        lower, upper,
        f.lower = f(lower, …), f.upper = f(upper, …),
        check.conv = FALSE,
        tol = .Machine$double.eps^0.25, maxiter = 1000, trace = 0)

Arguments

f

the function for which the root is sought.

…

additional named or unnamed arguments to be passed to f

lower, upper

the lower and upper end points of the interval to be searched.

f.lower, f.upper

the same as f(upper) and f(lower), respectively. Passing these values from the caller where they are often known is more economical as soon as f() contains non-trivial computations.

check.conv

logical indicating whether a convergence warning of the underlying vuniroot should be caught as an error and if non-convergence in maxiter iterations should be an error instead of a warning.

tol

the desired accuracy (convergence tolerance).

maxiter

the maximum number of iterations.

trace

integer number; if positive, tracing information is produced. Higher values giving more details.

Value

A list with at least three components: root and f.root give the location of the root and the value of the function evaluated at that point. iter gives the number of iterations used.

Details

Note that arguments after … must be matched exactly.

Both lower and upper must be specified: the endpoint are re-ordered if necessary (cf. uniroot). The function values at the endpoints must be of opposite signs (or zero).

vuniroot() uses a C++ subroutine based on "zeroin" (from Netlib) and 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 f(x) == 0 or the change in x for one step of the algorithm is less than tol (plus an allowance for representation error in x).

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

f will be called as f(x, ...) for a numeric value of x.

The argument passed to f has special semantics and used to be shared between calls. The function should not copy it.

References

Brent, R. (1973) Algorithms for Minimization without Derivatives. Englewood Cliffs, NJ: Prentice-Hall.

See Also

uniroot for the standard single root solver polyroot for all complex roots of a polynomial; optimize, nlm.

Examples

# NOT RUN {
require(utils) # for str

## some platforms hit zero exactly on the first step:
## if so the estimated precision is 2/3.
f <- function (x, a) x - a
str(xmin <- vuniroot(f, lower=c(0, 0), upper=c(1,1), tol = 0.0001, a = c(1/3,2/3)))

## handheld calculator example: fixed point of cos(.):
vuniroot(function(x) cos(x) - x, lower = -pi, upper = pi, tol = 1e-9)$root
# }
# NOT RUN {
<!-- % donttest because printed output is so much platform dependent -->
# }
# NOT RUN {
# }