copula (version 1.1-4)

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)

Value

A list with four components, root, f.root, iter

and estim.prec; see uniroot.

Arguments

f

function

interval

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

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.

See Also

uniroot.

Examples

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) )