IMSL_INTFCN

Syntax | Return Value | Arguments | Keywords | Discussion of Default Method | Example | Errors | Version History

The IMSL_INTFCN function integrates a user-supplied function. Using different combinations of keywords and parameters, several types of integration can be performed including the following:

Different types of integration are specified by supplying different sets of parameters and keywords to the IMSL_INTFCN function. Refer to the discussion that pertains to the type of integration you wish to perform for the corresponding function syntax.

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_INTFCN(f, a, b [, /DOUBLE] [, ERR_ABS=value] [, ERR_EST=variable] [, ERR_REL=value] [, MAX_SUBINTER=value] [, N_SUBINTER=variable] [, N_EVALS=variable])

Return Value

An estimate of the desired integral. If no value can be computed, the floating-point value NaN (Not a Number) is returned.

Arguments

f

A scalar string specifying the name of a user-supplied function to be integrated. The function f accepts one scalar parameter and returns a single scalar of the same type.

a

A scalar expression specifying the lower limit of integration.

b

A scalar expression specifying the upper limit of integration.

Keywords

The following keywords can be used in any combination with each method of integration except the nonadaptive method, which is triggered by the keyword SMOOTH.

DOUBLE

Set this keyword to perform computations using double precision.

ERR_ABS

Set this keyword to a value specifying the accuracy desired. Default: ERR_ABS=SQRT(ε), where ε is the machine precision.

ERR_EST

Set this keyword equal to a named variable that will contain an estimate of the absolute value of the error.

ERR_REL

Set this keyword to a value specifying the relative accuracy desired. Default: ERR_REL=SQRT(ε), where ε is the machine precision

MAX_SUBINTER

Set this keyword equal to the number of subintervals allowed. Default: MAX_SUBINTER=500.

N_SUBINTER

Set this keyword equal to a named variable that will contain the number of subintervals generated.

N_EVALS

Set this keyword equal to a named variable that will contain the number of evaluations of Function.

Discussion of Default Method

The default method used by IMSL_INTFCN is a general-purpose integrator that uses a globally adaptive scheme to reduce the absolute error. It subdivides the interval [a, b] and uses a 21-point Gauss-Kronrod rule to estimate the integral over each subinterval. The error for each subinterval is estimated by comparison with the 10-point Gauss quadrature rule. The subinterval with the largest estimated error is then bisected, and the same procedure is applied to both halves. The bisection process is continued until either the error criterion is satisfied, the roundoff error is detected, the subintervals become too small, or the maximum number of subintervals allowed is reached. This method uses an extrapolation procedure known as the ε-algorithm. This method is based on the subroutine QAGS by Piessens et al. (1983).

Should the default method fail to produce acceptable results, consider one of the more specialized methods available by using method-specific keywords for this function.

Example

An estimate of:

is computed, then compared to the actual value.

.RUN 
; Define the function to be integrated. 
FUNCTION f, x 
   RETURN, x^2 
END 
 
ans = IMSL_INTFCN('f', 0, 3) 
; Call IMSL_INTFCN to compute the integral. 
PM, 'Computed Answer:', ans 
; Output the results. 
Computed Answer: 
        9.00000 
PM, 'Exact - Computed:', 3^2 - ans 
Exact - Computed: 
        0.00000 

Errors

The integration methods supported by IMSL_INTFCN may generate any of the following errors.

Warning Errors

MATH_ROUNDOFF_CONTAMINATION—Roundoff error, preventing the requested tolerance from being achieved, has been detected.

MATH_PRECISION_DEGRADATION—Degradation in precision has been detected.

MATH_EXTRAPOLATION_ROUNDOFF—Roundoff error in the extrapolation table, preventing requested tolerance from being achieved, has been detected.

MATH_EXTRAPOLATION_PROBLEMS—Extrapolation table, constructed for convergence acceleration of the series formed by the integral contributions of the cycles, does not converge to the requested accuracy.

MATH_BAD_INTEGRAND_BEHAVIOR—Bad integrand behavior occurred in one or more cycles.

Fatal Errors

MATH_DIVERGENT—Integral is probably divergent or slowly convergent.

MATH_MAX_SUBINTERVALS—Maximum number of subintervals allowed has been reached.

MATH_MAX_CYCLES—Maximum number of cycles allowed has been reached.

MATH_MAX_STEPS—Maximum number of steps allowed have been taken. The integrand is too difficult for this routine.

Version History