safeUroot: One-dimensional Root (Zero) Finding - Extra "Safety" for Convenience

Description

safeUroot() as a “safe” version of uniroot() searches for a root (that is, zero) of the function f with respect to its first argument.

“Safe” means searching for the correct interval = c(lower,upper) if sign(f(x)) does not satisfy the requirements at the interval end points; see the ‘Details’ section.

Usage

safeUroot(f, interval, ..., lower = min(interval), upper = max(interval), f.lower = f(lower, ...), f.upper = f(upper, ...), Sig = NULL, check.conv = FALSE, tol = .Machine$double.eps^0.25, maxiter = 1000, trace = 0)

Arguments

function

interval

...

additional named or unnamed arguments to be passed to f

lower, upper

lower and upper endpoint of search interval

f.lower, f.upper

function value at lower or upper endpoint, respectively.

Sig

desired sign of f(upper), or NULL.

check.conv

logical indicating whether a convergence warning of the underlying uniroot should be caught as an error.

tol

the desired accuracy, that is, convergence tolerance.

maxiter

maximal number of iterations

trace

number determining tracing

Value

A list with four components, root, f.root, iter and estim.prec; see uniroot.

Details

If it is known how $f$ changes sign at the root $x0$, that is, if the function is increasing or decreasing there, Sig can be specified, typically as $S:= +/- 1$, to require $S = sign(f(x0 + eps))$ at the solution. In that case, the search interval $[l,u]$ must be such that $S * f(l) <= 0$="" and="" $s="" *="" f(u)="">= 0$.

Otherwise, by default, when Sig=NULL, the search interval $[l,u]$ must satisfy $f(l) * f(u) <= 0$.<="" p="">

In both cases, when the requirement is not satisfied, safeUroot() tries to enlarge the interval until the requirement is satisfied.

Examples

Run this code

f1 <- function(x) (121 - x^2)/(x^2+1)
f2 <- function(x) exp(-x)*(x - 12)

try(uniroot(f1, c(0,10)))
try(uniroot(f2, c(0,2)))
##--> error: f() .. end points not of opposite sign

## where as safeUroot() simply first enlarges the search interval:
safeUroot(f1, c(0,10),trace=1)
safeUroot(f2, c(0,2), trace=2)

## no way to find a zero of a positive function:
try( safeUroot(exp, c(0,2), trace=TRUE) )

## Convergence checking :
safeUroot(sinc, c(0,5), maxiter=4) #-> "just" a warning
try( # an error, now with  check.conv=TRUE
  safeUroot(sinc, c(0,5), maxiter=4, check.conv=TRUE) )