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.

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

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

IDL prints:

Computed Answer:
9.00000

Continue:

PM, 'Exact - Computed:', 3^2 - ans

IDL prints:

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.

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 (optional)

Set this keyword to perform computations using double precision.

ERR_ABS (optional)

Set this keyword to a value specifying the accuracy desired. The default value is SQRT(ε), where ε is the machine precision.

ERR_EST (optional)

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

ERR_REL (optional)

Set this keyword to a value specifying the relative accuracy desired. The default value is SQRT(ε), where ε is the machine precision.

MAX_SUBINTER (optional)

Set this keyword to the number of subintervals allowed. The default value is 500.

N_SUBINTER (optional)

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

N_EVALS (optional)

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

Version History


6.4

Introduced