\name{safeUroot}
\alias{safeUroot}
\title{One Dimensional Root (Zero) Finding - Extra "Safety" for Convenience}
\usage{
safeUroot(f, interval, \dots,
       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)
}
\description{
  \code{safeUroot()} as a \dQuote{safe} version of
  \code{\link{uniroot}()} searches for a root (i.e., zero) of the
  function \code{f} with respect to its first argument.

  \dQuote{Safety} is provided by a search for the correct \code{interval
    = c(lower,upper)} in case \code{sign(f(x))} does not of the satisfy the
  requirements at the interval end points, see the \sQuote{Details}
  section.
}
\arguments{
  \item{f}{function}
  \item{interval}{interval}
  \item{\dots}{additional named or unnamed arguments to be passed
    to \code{f}}
  \item{lower, upper}{lower and upper endpoint of search interval}
  \item{f.lower, f.upper}{function value at \code{lower} or \code{upper}
    endpoint, respectively.}
  \item{Sig}{\emph{desired} sign of \code{f(upper)}, or \code{\link{NULL}}.}
  \item{check.conv}{logical indicating if a convergence warning from the
    underlying \code{\link{uniroot}} should be caught as an error.}
  \item{tol}{the desired accuracy, i.e., convergence tolerance.}
  \item{maxiter}{maximal number of iterations}
  \item{trace}{number determining tracing}
}
\details{
  If it is \emph{known how} \eqn{f} changes sign at the root
  \eqn{x_0}{x0}, i.e., if the function is increasing or decreasing there,
  \code{Sig} can be specified, typically as \eqn{S := \pm 1}{S:= +/- 1},
  to require \eqn{S = \mathrm{sign}(f(x_0 + \epsilon))}{S = sign(f(x0 + eps))}
  at the solution.  In that case, the search interval \eqn{[l,u]} must
  be such that \eqn{S * f(l) <= 0} and \eqn{S * f(u) >= 0}.

  Otherwise, by default, when \code{Sig=NULL}, the search interval
  \eqn{[l,u]} must satisfy \eqn{f(l) * f(u) <= 0}.

  In both cases, when the requirement is not satisfied, \code{safeUroot()}
  tries to enlarge the interval until the requirement \emph{is} satisfied.

  %% in the Sig case, typically only *one* side of the interval is
  %% enlarged; in the other (usual) case, it is enlarged on both sides
  %% at the same time.
}
\author{Martin Maechler (from Martin's \R package \pkg{nor1mix}).
}
\value{
  A list with four components, \code{root}, \code{f.root}, \code{iter}
  and \code{estim.prec}, see \code{\link{uniroot}}.
}
\seealso{
  \code{\link{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) )
}
\keyword{optimize}