uniroot                package:stats                R Documentation

_O_n_e _D_i_m_e_n_s_i_o_n_a_l _R_o_o_t (_Z_e_r_o) _F_i_n_d_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     uniroot(f, interval, ...,
             lower = min(interval), upper = max(interval),
             f.lower = f(lower, ...), f.upper = f(upper, ...),
             tol = .Machine$double.eps^0.25, maxiter = 1000)

_A_r_g_u_m_e_n_t_s:

       f: the function for which the root is sought.

interval: a vector containing the end-points of the interval to be
          searched for the root.

     ...: 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.

     tol: the desired accuracy (convergence tolerance).

 maxiter: the maximum number of iterations.

_D_e_t_a_i_l_s:

     Note that arguments after '...' must be matched exactly.

     Either 'interval' or both 'lower' and 'upper' must be specified:
     the upper endpoint must be strictly larger than the lower
     endpoint.  The function values at the endpoints must be of
     opposite signs (or zero).

     The function uses Fortran subroutine '"zeroin"' (from Netlib)
     based on 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.

_V_a_l_u_e:

     A list with four components: 'root' and 'f.root' give the location
     of the root and the value of the function evaluated at that point.
     'iter' and 'estim.prec' give the number of iterations used and an
     approximate estimated precision for 'root'.  (If the root occurs
     at one of the endpoints, the estimated precision is 'NA'.)

_S_o_u_r_c_e:

     Based on 'zeroin.c' in <URL: http://www.netlib.org/c/brent.shar>.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'polyroot' for all complex roots of a polynomial; 'optimize',
     'nlm'.

_E_x_a_m_p_l_e_s:

     require(utils) # for str

     f <- function (x,a) x - a
     str(xmin <- uniroot(f, c(0, 1), tol = 0.0001, a = 1/3))
     str(uniroot(function(x) x*(x^2-1) + .5, lower = -2, upper = 2,
                 tol = 0.0001), dig = 10)
     str(uniroot(function(x) x*(x^2-1) + .5, lower = -2, upper = 2,
                 tol = 1e-10 ), dig = 10)

     ## Find the smallest value x for which exp(x) > 0 (numerically):
     r <- uniroot(function(x) 1e80*exp(x)-1e-300, c(-1000,0), tol = 1e-15)
     str(r, digits= 15) ##> around -745, depending on the platform.

     exp(r$root)     # = 0, but not for r$root * 0.999...
     minexp <- r$root * (1 - 10*.Machine$double.eps)
     exp(minexp)     # typically denormalized