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

```