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 \(x_0\), that is, if the function is increasing or decreasing there, Sig can be specified, typically as \(S := \pm 1\), to require \(S = \mathrm{sign}(f(x_0 + \epsilon))\) 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\).

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

Examples

Run this code

# NOT RUN {
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) )
# }