```help mata mm_root()
-------------------------------------------------------------------------------

Title

mm_root() -- Brent's univariate zero (root) finder

Syntax

rc = mm_root(x, f, lo, up [, tol, itr, ...])

where

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

x:  will be replaced by a real scalar containing solution

f:  pointer scalar containing address of function whose zero will
be sought for; usually this is coded &funcname()

lo:  real scalar containing lower endpoint of the search interval

up:  real scalar containing upper endpoint of the search interval

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 f

Description

mm_root() searches the interval from lo to up for the root of function f
with respect to its first argument.  That is, mm_root() approximates the
value x for which f(x [, ...]) evaluates to zero. The accuracy of the
approximation is 4*epsilon(x) + tol.

mm_root() 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

2: f(lo) and f(up) do not have opposite signs and f(lo) is closer to
zero than f(up); x will be set to lo

3: f(lo) and f(up) do not have opposite signs and f(up) is closer to
zero than f(lo); x will be set to up

mm_root() is a (slightly modified) translation of the C realization of
Brent's zero finder provided in http://www.netlib.org/c/brent.shar. A
description of the algorithm and details on the modifications can be
found in the source of mm_root() (see below).

Remarks

Example:

: function myfunc(x, a) return(x^2 - a)

: a = 2/3

: mm_root(x=., &myfunc(), 0, 1, 0, 1000, a)
0

: x
.8164965809

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

: x
.8168350168

: sqrt(a)
.8164965809

Conformability

mm_root(x, f, lo, up, tol, itr, ...):
x:  input: anything; output: 1 x 1
f:  1 x 1
lo:  1 x 1
up:  1 x 1
tol:  1 x 1
itr:  1 x 1
...:  (depending on function f)
result:  1 x 1

Diagnostics

x will be set to missing if f evaluates to missing at some point in the
algorithm.

Source code

mm_root.mata

Author

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

Also see

```