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 areal scalarcontaining solution

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

lo:real scalarcontaining lower endpoint of the search interval

up:real scalarcontaining upper endpoint of the search interval

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 functionf

Description

mm_root()searches the interval fromlotoupfor the root of functionfwith respect to its first argument. That is,mm_root()approximates the valuexfor whichf(x[,...])evaluates to zero. The accuracy of the approximation is 4*epsilon(x) +tol.

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

f(lo)andf(up)do not have opposite signs andf(lo)is closer to zero thanf(up);xwill be set tolo3:

f(lo)andf(up)do not have opposite signs andf(up)is closer to zero thanf(lo);xwill be set toup

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 ofmm_root()(see below).

RemarksExample:

: 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: 1x1f: 1x1lo: 1x1up: 1x1tol: 1x1itr: 1x1...: (depending on functionf)result: 1x1

Diagnostics

xwill be set to missing iffevaluates to missing at some point in the algorithm.

Source codemm_root.mata

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

Also see