{smcl} {* 07jul2006}{...} {cmd:help mata mm_root()} {hline} {title:Title} {p 4 19 2} {bf:mm_root() -- Brent's univariate zero (root) finder} {title:Syntax} {p 8 21 2}{it:rc} = {cmd:mm_root(}{it:x}{cmd:,} {it:f}{cmd:,} {it:lo}{cmd:,} {it:up} [{cmd:,} {it:tol}{cmd:,} {it:itr}{cmd:,} {it:...}]{cmd:)} {pstd} where {p 11 16 2} {it:rc}: the return code; {it:rc}!=0 indicates that no valid solution has been found {p 12 16 2} {it:x}: will be replaced by a {it:real scalar} containing solution {p 12 16 2} {it:f}: {it:pointer scalar} containing address of function whose zero will be sought for; usually this is coded {cmd:&}{it:funcname}{cmd:()} {p 11 16 2} {it:lo}: {it:real scalar} containing lower endpoint of the search interval {p 11 16 2} {it:up}: {it:real scalar} containing upper endpoint of the search interval {p 10 16 2} {it:tol}: {it:real scalar} specifying acceptable tolerance for the root estimate (default is {it:tol}=0 to find the root as accurate as possible) {p 10 16 2} {it:itr}: {it:real scalar} specifying the maximum number of iterations (default is {it:itr}=1000) {p 10 16 2} {it:...}: up to 10 additional arguments to pass on to function {it:f} {title:Description} {pstd}{cmd:mm_root()} searches the interval from {it:lo} to {it:up} for the root of function {it:f} with respect to its first argument. That is, {cmd:mm_root()} approximates the value {it:x} for which {it:f}{cmd:(}{it:x} [{cmd:,} {it:...}]{cmd:)} evaluates to zero. The accuracy of the approximation is 4*epsilon({it:x}) + {it:tol}. {pstd}{cmd:mm_root()} stores the found solution in {it:x} and issues return code {it:rc}. Possible return codes are: {phang2}{bind: 0:} everything went well {phang2}{bind: 1:} convergence has not been reached within the maximum number of iterations; {it:x} will contain the current approximation {phang2}{bind: 2:} {it:f}{cmd:(}{it:lo}{cmd:)} and {it:f}{cmd:(}{it:up}{cmd:)} do not have opposite signs and {it:f}{cmd:(}{it:lo}{cmd:)} is closer to zero than {it:f}{cmd:(}{it:up}{cmd:)}; {it:x} will be set to {it:lo} {phang2}{bind: 3:} {it:f}{cmd:(}{it:lo}{cmd:)} and {it:f}{cmd:(}{it:up}{cmd:)} do not have opposite signs and {it:f}{cmd:(}{it:up}{cmd:)} is closer to zero than {it:f}{cmd:(}{it:lo}{cmd:)}; {it:x} will be set to {it:up} {pstd} {cmd:mm_root()} is a (slightly modified) translation of the C realization of Brent's zero finder provided in {browse "http://www.netlib.org/c/brent.shar"}. A description of the algorithm and details on the modifications can be found in the source of {cmd:mm_root()} (see below). {title:Remarks} {pstd}Example: {com}: function myfunc(x, a) return(x^2 - a) : a = 2/3 {res} {com}: mm_root(x=., &myfunc(), 0, 1, 0, 1000, a) {res} 0 {com}: x {res} .8164965809 {com}: mm_root(x=., &myfunc(), 0, 1, 0.01, 1000, a) {res} 0 {com}: x {res} .8168350168 {com}: sqrt(a) {res} .8164965809{txt} {title:Conformability} {pstd} {cmd:mm_root(}{it:x}{cmd:,} {it:f}{cmd:,} {it:lo}{cmd:,} {it:up}{cmd:,} {it:tol}{cmd:,} {it:itr}{cmd:,} {it:...}{cmd:)}:{p_end} {it:x}: input: anything; output: 1 {it:x} 1 {it:f}: 1 {it:x} 1 {it:lo}: 1 {it:x} 1 {it:up}: 1 {it:x} 1 {it:tol}: 1 {it:x} 1 {it:itr}: 1 {it:x} 1 {it:...}: (depending on function {it:f}) {it:result}: 1 {it:x} 1 {title:Diagnostics} {pstd}{it:x} will be set to missing if {it:f} evaluates to missing at some point in the algorithm. {title:Source code} {pstd} {help moremata_source##mm_root:mm_root.mata} {title:Author} {pstd} Ben Jann, University of Bern, jann@soz.unibe.ch {title:Also see} {psee} Online: help for {bf:{help mf_mm_nrroot:mm_nrroot()}}, {bf:{help m2_ftof:[M-2] ftof}}, {bf:{help moremata}}