help mata mm_root()


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


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


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


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 A description of the algorithm and details on the modifications can be found in the source of mm_root() (see below).



: 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


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


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

Source code



Ben Jann, ETH Zurich,

Also see