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