FX_ROOT

The FX_ROOT function computes a real or complex root of a univariate nonlinear function using an optimal Müller's method.

FX_ROOT uses an algorithm that is described in section 9.5 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission.

This routine is written in the IDL language. Its source code can be found in the file fx_root.pro in the lib subdirectory of the IDL distribution.

Syntax

Result = FX_ROOT(X, Func [, /DOUBLE] [, ITMAX=value] [, /STOP] [, TOL=value] )

Return Value

The return value is the real or complex root of a univariate nonlinear function. Which root results depends on the initial guess provided for this routine.

Arguments

X

A 3-element real or complex initial guess vector. Real initial guesses may result in real or complex roots. Complex initial guesses will result in complex roots.

Func

A scalar string specifying the name of a user-supplied IDL function that defines the univariate nonlinear function. This function must accept the argument X, and must return a three-element vector containing the function value at the three points in X.

For example, suppose we wish to find a root of the following function:

We write a function FUNC to express the function in the IDL language:

FUNCTION func, X
RETURN, EXP(SIN(X)^2 + COS(X)^2 - 1) - 1
END

Keywords

DOUBLE

Set this keyword to force the computation to be done in double-precision arithmetic.

ITMAX

The maximum allowed number of iterations. The default is 100.

STOP

Use this keyword to specify the stopping criterion used to judge the accuracy of a computed root r(k). Setting STOP = 0 (the default) checks whether the absolute value of the difference between two successively-computed roots, | r(k) - r(k+1) | is less than the stopping tolerance TOL. Setting STOP = 1 checks whether the absolute value of the function FUNC at the current root, | FUNC(r(k)) |, is less than TOL.

TOL

Use this keyword to specify the stopping error tolerance. The default is 1.0 x 10^-4.

Examples

This example finds the roots of the function FUNC defined above:

; First define a real 3-element initial guess vector:
x = [0.0, -!pi/2, !pi]

; Compute a root of the function using double-precision
; arithmetic:
root = FX_ROOT(X, 'FUNC', /DOUBLE)

; Check the accuracy of the computed root:
PRINT, EXP(SIN(ROOT)^2 + COS(ROOT)^2 - 1) - 1

IDL prints:

0.0000000

We can also define a complex 3-element initial guess vector:

x = [COMPLEX(-!PI/3, 0), COMPLEX(0, !PI), COMPLEX(0, -!PI/6)]

; Compute the root of the function:
root = FX_ROOT(x, 'FUNC')

; Check the accuracy of the computed complex root:
PRINT, EXP(SIN(ROOT)^2 + COS(ROOT)^2 - 1) - 1