IMSL_ZEROFCN

Syntax | Return Value | Arguments | Keywords | Discussion | Example | Errors | Version History

The IMSL_ZEROFCN function finds the real zeros of a real function using Müller's method.

Note
This routine requires an IDL Advanced Math and Stats license. For more information, contact your ITT Visual Information Solutions sales or technical support representative.

Syntax

Result = IMSL_ZEROFCN(f [, /DOUBLE] [, ERR_ABS=value] [, ERR_REL=value] [, ETA=value] [, EPS=value] [, INFO=array] [, ITMAX=value] [, N_ROOTS=value] [, XGUESS=array] )

Return Value

An array containing the zeros x of the function.

Arguments

f

Scalar string specifying a user-supplied function for which the zeros are to be found. The f function accepts one scalar parameter from which the function is evaluated and returns a scalar of the same type.

Keywords

DOUBLE

If present and nonzero, double precision is used.

ERR_ABS

First stopping criterion. A zero, x_i, is accepted if | f (x_i) | < ERR_ABS. Default: ERR_ABS = SQRT(ε), where ε is the machine precision

ERR_REL

Second stopping criterion. A zero, x_i, is accepted if the relative change of two successive approximations to x_i is less than ERR_REL. Default: ERR_REL = SQRT(ε), where ε is the machine precision

ETA

Spread criteria for multiple zeros. If the zero, x_i, has been computed and
| x_i – x_j | < EPS, where x_j is a previously computed zero, then the computation is restarted with a guess equal to x_i + ETA. Default: ETA = 0.01

EPS

See ETA. Default: EPS = SQRT(ε), where ε is the machine precision.

INFO

Array of length N_ROOTS containing convergence information. The value INFO
(j – 1) is the number of iterations used in finding the j-th zero when convergence is achieved. If convergence is not obtained in ITMAX iterations, INFO (j – 1) is greater than ITMAX.

ITMAX

Maximum number of iterations per zero. Default: ITMAX = 100.

N_ROOTS

Number of roots for IMSL_ZEROFCN to find. Default: N_ROOTS = 1.

XGUESS

Array with N_ROOTS components containing the initial guesses for the zeros. Default: XGUESS = 0

Discussion

The IMSL_ZEROFCN function computes n real zeros of a real function f. Given a user-supplied function f (x) and an n-vector of initial guesses x₀, x₁, ..., x_n–1, the function uses Müller's method to locate n real zeros of f. The function has two convergence criteria. The first criterion requires that | f (x_i^(m)) | be less than ERR_ABS. The second criterion requires that the relative change of any two successive approximations to an x_i be less than ERR_REL. Here, x_i^(m) is the m-th approximation to x_i. Let ERR_ABS be denoted by ε₁, and ERR_REL be denoted by ε₂. The criteria can be stated mathematically as follows.

IMSL_ZEROFCN has two convergence criteria; "convergence" is the satisfaction of either criterion.

Criterion 1:

Criterion 2:

"Convergence" is the satisfaction of either criterion.

Example

This example finds a real zero of the third-degree polynomial:

f(x) = x³ – 3x² + 3x – 1

The results are shown in Figure 10-1.

.RUN 
; Define function f. 
FUNCTION f, x 
   return, x^3 - 3 * x^2 + 3 * x - 1 
END 
 
zero = IMSL_ZEROFCN('f') 
; Compute the real zero(s). 
x = 2 * FINDGEN(100)/99 
PLOT, x, f(x) 
; Plot results. 
OPLOT, [zero], [f(zero)], Psym = 6 
XYOUTS, .5, .5, 'Computed zero is at x = ' + $ 
   STRING(zero(0)), Charsize = 1.5 

Figure 10-1: IMSL_ZEROFCN Function

Errors

Warning Errors

MATH_NO_CONVERGE_MAX_ITER—Function failed to converge within ITMAX iterations for at least one of the N_ROOTS roots.

Version History