help mata mm_nrroot()
-------------------------------------------------------------------------------

Title

    mm_nrroot() -- Newton-Raphson univariate zero (root) finder


Syntax

        rc = mm_nrroot(x, fdf [, tol, itr, ...])

    where

           rc:  the return code; rc!=0 indicates that no valid solution has
                been found

            x:  real scalar containing initial guess; x will be replaced by a
                real scalar containing solution

          fdf:  pointer scalar containing address of function supplying the
                function value and the first derivative; usually this is
                coded &funcname()

          tol:  real scalar specifying acceptable tolerance for the root
                estimate (default is tol=0 to find the root as accurate as
                possible)

          itr:  real scalar specifying the maximum number of iterations
                (default is itr=1000)

          ...:  up to 10 additional arguments to pass on to function fdf


Description

    mm_nrroot() uses the Newton-Raphson method to search for the root of a
    function with respect to its first argument.  That is, mm_nrroot()
    approximates the value x for which the function evaluates to zero. The
    accuracy of the approximation is 4e+4*epsilon(x) + tol.

    mm_nrroot() stores the found solution in x and issues return code rc.
    Possible return codes are:

         0: everything went well

         1: convergence has not been reached within the maximum number of
            iterations; x will contain the current approximation

    mm_nrroot() is based on the example given in Press et al. (1992:365-366).


Remarks

    Example:

        : function myfunc(x, a) {
        >         fn = x^2 - a
        >         df = 2*x
        >         return(fn, df)
        > }

        : a = 2/3
        
        : mm_nrroot(x=1, &myfunc(), 0, 1000, a)
          0

        : x
          .8164965809

        : mm_nrroot(x=1, &myfunc(), 0.01, 1000, a)
          0

        : x
          .8164965986

        : sqrt(a)
          .8164965809


Conformability

    mm_nrroot(x, fdf, tol, itr, ...):
           x:  1 x 1
         fdf:  1 x 1
         tol:  1 x 1
         itr:  1 x 1
         ...:  (depending on function fdf)
      result:  1 x 1


Diagnostics

    x will be set to missing if the function value or the derivative
    evaluates to missing at some point in the algorithm.


Source code

    mm_nrroot.mata


References

    Press, William H., Saul A. Teukolsky, William T. Vetterling, Brian P.
        Flannery (1992). Numerical Recipes in C. The Art of Scientific
        Computing. Second Edition. Cambridge University Press.  
        http://www.numerical-recipes.com/


Author

    Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch


Also see