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 scalarcontaining initial guess;xwill be replaced by areal scalarcontaining solution

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

tol:real scalarspecifying acceptable tolerance for the root estimate (default istol=0 to find the root as accurate as possible)

itr:real scalarspecifying the maximum number of iterations (default isitr=1000)

...: up to 10 additional arguments to pass on to functionfdf

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 valuexfor which the function evaluates to zero. The accuracy of the approximation is 4e+4*epsilon(x) +tol.

mm_nrroot()stores the found solution inxand issues return coderc. Possible return codes are:0: everything went well

1: convergence has not been reached within the maximum number of iterations;

xwill contain the current approximation

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

RemarksExample:

: 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: 1x1fdf: 1x1tol: 1x1itr: 1x1...: (depending on functionfdf)result: 1x1

Diagnostics

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

Source codemm_nrroot.mata

ReferencesPress, 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/

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

Also see