NAG FL Interface
d01raf (dim1_​gen_​vec_​multi_​rcomm)

Note: this routine uses optional parameters to define choices in the problem specification and in the details of the algorithm. If you wish to use default settings for all of the optional parameters, you need only read Sections 1 to 10 of this document. If, however, you wish to reset some or all of the settings please refer to Section 11 for a detailed description of the specification of the optional parameters.
Settings help

FL Name Style:


FL Specification Language:


1 Purpose

d01raf is a general purpose adaptive integrator which calculates an approximation to a vector of definite integrals F over a finite range [a,b] , given the vector of integrands f(x).
F = a b f(x) d x  
If the same subdivisions of the range are equally good for functions f1(x) and f2(x), because f1(x) and f2(x) have common areas of the range where they vary slowly and where they vary quickly, then we say that f1(x) and f2(x) are ‘similar’. d01raf is particularly effective for the integration of a vector of similar functions.

2 Specification

Fortran Interface
Subroutine d01raf ( irevcm, ni, a, b, sid, needi, x, lenx, nx, fm, ldfm, dinest, errest, iopts, opts, icom, licom, com, lcom, ifail)
Integer, Intent (In) :: ni, lenx, ldfm, iopts(100), licom, lcom
Integer, Intent (Inout) :: irevcm, needi(ni), nx, icom(licom), ifail
Integer, Intent (Out) :: sid
Real (Kind=nag_wp), Intent (In) :: a, b, fm(ldfm,*), opts(100)
Real (Kind=nag_wp), Intent (Inout) :: x(lenx), dinest(ni), errest(ni), com(lcom)
C Header Interface
#include <nag.h>
void  d01raf_ (Integer *irevcm, const Integer *ni, const double *a, const double *b, Integer *sid, Integer needi[], double x[], const Integer *lenx, Integer *nx, const double fm[], const Integer *ldfm, double dinest[], double errest[], const Integer iopts[], const double opts[], Integer icom[], const Integer *licom, double com[], const Integer *lcom, Integer *ifail)
The routine may be called by the names d01raf or nagf_quad_dim1_gen_vec_multi_rcomm.

3 Description

d01raf is an extension to various QUADPACK routines, including QAG, QAGS and QAGP. The extensions made allow multiple integrands to be evaluated simultaneously, using a vectorized interface and reverse communication.
The quadrature scheme employed by d01raf can be chosen by you. Six Gauss–Kronrod schemes are available. The algorithm incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)), optionally together with the ε-algorithm (see Wynn (1956)) to perform extrapolation. The local error estimation is described in Piessens et al. (1983).
d01raf is the integration routine in the suite of routines d01raf and d01rcf. It also uses optional parameters, which can be set and queried using the routines d01zkf and d01zlf respectively. The options available are described in Section 11.
First, the option arrays iopts and opts must be initialized using d01zkf. Thereafter any required options must be set before calling d01raf, or the routine d01rcf.
A typical usage of this suite of routines is (in pseudo-code for clarity),
Setup phase
liopts = 100
lopts = 100
allocate(iopts(liopts),opts(lopts))
Call d01zkf('initialize = d01raf',iopts,liopts,opts,lopts,ifail)
Call d01zkf('option = value',iopts,liopts,opts,lopts,ifail)
...
Call d01rcf(ni,lenxrq,ldfmrq,sdfmrq,licmin,licmax,lcmin,lcmax, &
     iopts,opts,ifail)
lenx = lenxrq
ldfm = ldfmrq
sdfm = sdfmrq
licom = licmax
lcom = lcmax
allocate(icom(licom),com(lcom),x(lenx),fm(ldfm,sdfm),needi(ni), &
              dinest(ni),errest(ni))
Solve phase
irevcm = 1
While irevcm≠0
    Call d01raf(irevcm,ni,a,b,sid,needi,x,lenx,nx,fm,ldfm,   &
                dinest,errest,iopts,opts,icom,licom,com, &
                lcom,ifail)
    Select Case(irevcm)
    Case(11)
          Initial solve phase 
          evaluate fm(1:ni,1:nx)
    Case(12)
          Adaptive solve phase 
          evaluate fm(needi(1:ni)=1,1:nx)
    Case(0)
          investigate ifail
    End Select
End While
Diagnostic phase
Call d01zlf('option',ivalue,rvalue,cvalue,optype,iopts,opts,ifail)
...
During the initial solve phase, the first estimation of the definite integral and error estimate is constructed over the interval [a,b] . This will have been divided into spri level 1 segments, where spri is the number of Primary Divisions, and will use any provided break-points if Primary Division Mode=MANUAL.
Once a complete integral estimate over [a,b] is available, i.e., after all the estimates for the level 1 segments have been evaluated, the routine enters the adaptive phase. The estimated errors are tested against the requested tolerances εa and εr , corresponding to the Absolute Tolerance and Relative Tolerance respectively. Should this test fail, and additional subdivision be allowed, a segment is selected for subdivision, and is subsequently replaced by two new segments at the next level of refinement. How this segment is chosen may be altered by setting Prioritize Error to either favour the segment with the maximum error, or the segment with the lowest level supporting an unacceptable (although potentially non-maximal) error. Up to maxsdiv subdivisions are allowed if sufficient memory is provided, where maxsdiv is the value of Maximum Subdivisions.
Once a sufficient number of error estimates have been constructed for a particular integral, the routine may optionally use Extrapolation to attempt to accelerate convergence. This may significantly lower the amount of work required for a given integration. To minimize the risk of premature convergence from extrapolation, a safeguard εsafe can be set using Extrapolation Safeguard, and the extrapolated solution will only be considered if εsafe εq εex , where εq and εex are the estimated error directly from the quadrature and from the extrapolation respectively. If extrapolation is successful for the computation of integral j, the extrapolated solution will be returned in dinest(j) on completion of d01raf. Otherwise the direct solution will be returned in dinest(j). This is indicated by the value of needi(j) on completion.

4 References

Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R (1973) An algorithm for automatic integration Angew. Inf. 15 399–401
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Wynn P (1956) On a device for computing the em(Sn) transformation Math. Tables Aids Comput. 10 91–96

5 Arguments

Note: this routine uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument irevcm. Between intermediate exits and re-entries, all arguments other than irevcm, needi and fm must remain unchanged.
1: irevcm Integer Input/Output
On initial entry: irevcm=1.
irevcm=1
Sets up data structures in icom and com and starts a new integration.
Constraint: irevcm=1 on initial entry.
On intermediate exit: irevcm=11 or 12.
irevcm requests the integrands fj(xi) be evaluated for all required j1,,ni as indicated by needi, and at all the points xi, for i=1,2,,nx. Abscissae xi are provided in x(i) and fj(xi) must be returned in fm(j,i).
During the initial solve phase:
irevcm=11
Function values are required to construct the initial estimates of the definite integrals.
If needi(j)=1, fj(xi) must be supplied in fm(j,i). This will be the case unless you have abandoned the evaluation of specific integrals on a previous call.
If needi(j)=0, you have previously abandoned the evaluation of integral j, and hence should not supply the value of fj(xi).
dinest and errest contain incomplete information during this phase. As such you should not abandon the evaluation of any integrals during this phase unless you do not require their estimate.
If irevcm is set to a negative value during this phase, needi(j), for j=1,2,,ni, will be set to this negative value and ifail=-1 will be returned.
During the adaptive solve phase:
irevcm=12
Function values are required to improve the estimates of the definite integrals.
If needi(j)=0, any evaluation of fj(xi) will be discarded, so there is no need to provide them.
If needi(j)=1, fj(xi) must be provided in fm(j,i).
If needi(j)=2, 3 or 4, the current error estimate of integral j does not require integrand j to be evaluated and provided in fm(j,i). Should you choose to, integrand j can be evaluated in which case needi(j) must be set to 1.
dinest and errest contain complete information during this phase.
If irevcm is set to a negative value during this phase ifail=1, 2 or 3 will be returned and the elements of needi will reflect the current state of the adaptive process.
On intermediate re-entry: irevcm should normally be left unchanged. However, if irevcm is set to a negative value, d01raf will terminate, (see irevcm=11 and irevcm=12 above).
On final exit: irevcm=0.
irevcm=0
Indicates the algorithm has completed.
Note: any values you return to d01raf as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by d01raf. If your code does inadvertently return any NaNs or infinities, d01raf is likely to produce unexpected results.
2: ni Integer Input
On entry: ni, the number of integrands.
3: a Real (Kind=nag_wp) Input
On entry: a, the lower bound of the domain.
4: b Real (Kind=nag_wp) Input
On entry: b, the upper bound of the domain.
If |b-a|<10ε, where ε is the machine precision (see x02ajf), d01raf will return dinest(j)=errest(j)=0.0, for j=1,2,,ni.
5: sid Integer Output
For advanced users.
On intermediate exit: sid identifies a specific set of abscissae, x, returned during the integration process. When a new set of abscissae are generated the value of sid is incremented by 1. Advanced users may store calculations required for an identified set x, and reuse them should d01raf return the same value of sid, i.e., the same set of abscissae was used.
6: needi(ni) Integer array Input/Output
On initial entry: need not be set.
On intermediate exit: needi(j) indicates what action must be taken for integral j=1,2,ni (see irevcm).
needi(j)=0
Do not provide fj(xi). Any provided values will be ignored.
needi(j)=1
The values fj(xi) must be provided in fm(j,i), for i=1,2,,nx.
needi(j)=2
The values fj(xi) are not required, however the error estimate for integral j is still above the requested tolerance. If you wish to provide values for the evaluation of integral j, set needi(j)=1, and supply fj(xi) in fm(j,i), for i=1,2,,nx.
needi(j)=3
The error estimate for integral j cannot be improved to below the requested tolerance directly, either because no more new splits may be performed due to exhaustion, or due to the detection of extremely bad integrand behaviour. However, providing the values fj(xi) may still lead to some improvement, and may lead to an acceptable error estimate indirectly using Wynn's epsilon algorithm. If you wish to provide values for the evaluation of integral j, set needi(j)=1, and supply fj(xi) in fm(j,i), for i=1,2,,nx.
needi(j)=4
The error estimate of integral j is below the requested tolerance. If you believe this to be false, if for example the result in dinest(j) is greatly different to what you may expect, you may force the algorithm to re-evaluate this conclusion by including the evaluations of integrand j at xi, for i=1,2,,nx, and setting needi(j)=1. Integral and error estimation will be performed again during the next iteration.
On intermediate re-entry: needi(j) may be used to indicate what action you have taken for integral j.
needi(j)=1
You have provided the values fj(xi) in fm(j,i), for i=1,2,,nx.
needi(j)<0
You are abandoning the evaluation of integral j. The current values of dinest(j) and errest(j) will be returned on final completion.
Otherwise you have not provided the value fj(xi).
On final exit: needi(j) indicates the final state of integral j.
needi(j)=0
The error estimate for Fj is below the requested tolerance.
needi(j)=1
The error estimate for Fj is below the requested tolerance after extrapolation.
needi(j)=2
The error estimate for Fj is above the requested tolerance.
needi(j)=3
The error estimate for Fj is above the requested tolerance, and extremely bad behaviour of integral j has been detected.
needi(j)<0
You prohibited further evaluation of integral j.
7: x(lenx) Real (Kind=nag_wp) array Input/Output
On initial entry: if Primary Division Mode=AUTOMATIC, x need not be set. This is the default behaviour.
If Primary Division Mode=MANUAL, x is used to supply a set of initial ‘break-points’ inside the domain of integration. Specifically, x(i) must contain a break-point xi0, for i=1,2,,(spri-1), where spri is the number of Primary Divisions.
Constraint: if break-points are supplied, xi0(a,b), |xi0-a|>10.0ε, |xi0-b|>10.0ε, for i=1,2,,(spri-1).
On intermediate exit: x(i) is the abscissa xi, for i=1,2,,nx, at which the appropriate integrals must be evaluated.
8: lenx Integer Input
On entry: the dimension of the array x as declared in the (sub)program from which d01raf is called. Currently lenx=max(122,spri-1) will be sufficient for all cases.
Constraint: lenxlenxrq, where lenxrq is dependent upon the options currently set (see Section 11). lenxrq is returned as lenxrq from d01rcf.
9: nx Integer Input/Output
On initial entry: need not be set.
On intermediate exit: nx, the number of abscissae at which integrands are required.
On intermediate re-entry: must not be changed.
10: fm(ldfm,*) Real (Kind=nag_wp) array Input
Note: the second dimension of the array fm must be at least sdfmrq, where sdfmrq is dependent upon ni and the options currently set. sdfmrq is returned as sdfmrq from d01rcf. If default options are chosen, sdfmrq=lenxrq.
On initial entry: need not be set.
On intermediate re-entry: if indicated by needi(j) you must supply the values fj(xi) in fm(j,i), for i=1,2,,nx and j=1,2,,ni.
11: ldfm Integer Input
On entry: the first dimension of the array fm as declared in the (sub)program from which d01raf is called.
Constraint: ldfmldfmrq, where ldfmrq is dependent upon ni and the options currently set. ldfmrq is returned as ldfmrq from d01rcf. If default options are chosen, ldfmrq=ni, implying ldfmni.
12: dinest(ni) Real (Kind=nag_wp) array Input/Output
dinest(j) contains the current estimate of the definite integral Fj.
On initial entry: need not be set.
On intermediate re-entry: must not be altered.
On exit: contains the current estimates of the ni integrals. If irevcm=0, this will be the final solution.
13: errest(ni) Real (Kind=nag_wp) array Input/Output
errest(j) contains the current error estimate of the definite integral Fj.
On initial entry: need not be set.
On intermediate re-entry: must not be altered.
On exit: contains the current error estimates for the ni integrals. If irevcm=0, errest contains the final error estimates of the ni integrals.
14: iopts(100) Integer array Communication Array
15: opts(100) Real (Kind=nag_wp) array Communication Array
The arrays iopts and opts must not be altered between calls to any of the routines d01raf, d01rcf, d01zkf and d01zlf.
16: icom(licom) Integer array Communication Array
icom contains details of the integration procedure, including information on the integration of the ni integrals over individual segments. This data is stored sequentially in the order that segments are created. For further information see Section 9.1.
17: licom Integer Input
On entry: the dimension of the array icom.
Constraint: licomlicmin, where licmin is dependent upon ni and the current options set. licmin is returned as licmin from d01rcf. If the default options are set, licmin=55+6×ni. Larger values than licmin are recommended if you anticipate that any integrals will require the domain to be further subdivided.
The maximum value that may be required, licmax, is returned as licmax from d01rcf. If default options are chosen, except for possibly increasing the value of spri, licmax=50+5×ni+(spri+100)×(5+ni).
18: com(lcom) Real (Kind=nag_wp) array Communication Array
com contains details of the integration procedure, including information on the integration of the ni integrals over individual segments. This data is stored sequentially in the order that segments are created. For further information see Section 9.1.
19: lcom Integer Input
On entry: the dimension of the array com.
Constraint: lcom>lcmin, where lcmin is dependent upon ni, spri and the current options set. lcmin is returned as lcmin from d01rcf. If default options are set, lcmin =96+12×ni. Larger values are recommended if you anticipate that any integrals will require the domain to be further subdivided.
Given the current options and arguments, the maximum value, lcmax, of lcom that may be required, is returned as lcmax from d01rcf. If default options are chosen, lcmax=94+9×ni+ni/2 +(spri+100)×(2+ni/2+2×ni).
20: ifail Integer Input/Output
On initial entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value −1 is recommended since useful values can be provided in some output arguments even when ifail0 on exit. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On final exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or −1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
Note: in some cases d01raf may return useful information.
ifail=1
At least one error estimate exceeded the requested tolerances.
ifail=2
Extremely bad behaviour was detected for at least one integral.
ifail=3
Extremely bad behaviour was detected for at least one integral. At least one other integral error estimate was above the requested tolerance.
ifail=11
irevcm had an illegal value.
On entry, irevcm=value.
ifail=21
On entry, ni=value.
Constraint: ni1.
ifail=71
On entry, Primary Division Mode=MANUAL and at least one supplied break-point in x is outside of the domain of integration.
ifail=81
lenx is insufficient for the chosen options.
On entry, lenx=value.
Constraint: lenxvalue.
ifail=111
ldfm<ldfmrq. If default options are chosen, this implies ldfm<ni.
On entry, ldfm=value.
Constraint: ldfmvalue.
ifail=171
licom is insufficient for additional subdivision.
On entry, licom=value.
Constraint: licomvalue.
ifail=191
lcom is insufficient for additional subdivision.
On entry, lcom=value.
Constraint: lcomvalue.
ifail=1001
Either the option arrays iopts and opts have not been initialized for d01raf, or they have become corrupted.
ifail=1101
On entry, one of icom and com has become corrupted.
ifail=-1
Evaluation of all integrals has been stopped during the initial phase.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

d01raf cannot guarantee, but in practice usually achieves, the following accuracy for each integral Fj:
|Fj-dinest(j)| tol  
where
tol = max(εa, εr × |Fj| )  
εa and εr are the error tolerances Absolute Tolerance and Relative Tolerance respectively. Moreover, it returns errest, the entries of which in normal circumstances satisfy,
|Fj-dinest(j)| errest(j) tol .  

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
d01raf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
d01raf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time required by d01raf is usually dominated by the time required to evaluate the values of the integrands fj.
d01raf will be most efficient if any badly behaved integrands provided have irregularities over similar subsections of the domain. For example, evaluation of the integrals,
0 1 ( log(x) x-12 x2 ) dx  
will be quite efficient, as the irregular behaviour of the first two integrands is at x=0. On the contrary, the evaluation of the integrals,
0 1 ( log(x) log(1-x) ) dx  
will be less efficient, as the two integrands have singularities at opposite ends of the domain, which will result in subdivisions which are only of use to one integrand. In such cases, it will be more efficient to use two sets of calls to d01raf.
d01raf will flag extremely bad behaviour if a sub-interval k¯ with bounds [ak¯,bk¯] satisfying |bk¯-ak¯| < max(δa, δr × |b-a| ) has a local error estimate greater than the requested tolerance for at least one integral. The values δa and δr can be set through the optional parameters Absolute Interval Minimum and Relative Interval Minimum respectively.

9.1 Details of the Computation

This section is recommended for expert users only. It describes the contents of the arrays com and icom upon exit from d01raf with ifail=0, 1, 2 or 3, and provided at least one iteration completed, failure due to insufficient licom or lcom.
The arrays icom and com contain details of the integration, including various scalars, one-dimensional arrays, and (effectively) two-dimensional arrays. The dimensions of these arrays vary depending on the arguments and options used and the progress of the algorithm. Here we describe some of these details, including how and where they are stored in icom and com.
Scalar quantities:
The indices in icom including the following scalars are available via query only options, see Section 11.2. For example, Ildi is the integer value returned by the option Index LDI.
ldi The leading dimension of the two-dimensional integer arrays stored in icom detailed below.
ldi=icom(Ildi).
ldr The leading dimension of the two-dimensional real arrays stored in com detailed below.
ldr=icom(Ildr).
nsdiv The number of segments that have been subdivided during the adaptive process.
nsdiv=icom(Insdiv).
nseg The total number of segments formed.
nseg=2nsdiv+spri.
nseg=icom(Inseg).
dsp The reference of the first element of the array ds stored in com.
dsp=icom(Idsp).
esp The reference of the first element of the array es stored in com.
esp=icom(Iesp).
evalsp The reference of the first element of the array evals stored in icom.
evalsp=icom(Ievalsp).
fcp The reference of the first element of the array fcount stored in icom.
fcp=icom(Ifcp).
sinforp The reference of the first element of the array sinfor stored in com.
sinforp=icom(Isinforp).
sinfoip The reference of the first element of the array sinfoi stored in icom.
sinfoip=icom(Isinfoip).
One-dimensional arrays:
fcount(ni)
fcount(1)=icom(fcp).
fcount(j) contains the number of different approximations of integral j calculated, for j=1,2,,ni.
Two-dimensional arrays:
sinfoi(5,nseg)
sinfoi(1,1)=icom(sinfoip).
sinfoi contains information about the hierarchy of splitting.
sinfoi(1,k) contains the split identifier for segment k, for k=1,2,,nseg.
sinfoi(2,k) contains the parent segment number of segment k (i.e., the segment was split to create segment k), for k=1,2,,nseg.
sinfoi(3,k) and sinfoi(4,k) contain the segment numbers of the two child segments formed from segment k, if segment k has been split. If segment k has not been split, these will be negative.
sinfoi(5,k) contains the level at which the segment exists, corresponding to na+1, where na is the number of ancestor segments of segment k, for k=1,2,,nseg. A negative level indicates that segment k will not be split further, the level is then given by the absolute value of sinfoi(5,k).
sinfor(2,nseg)
sinfor(1,1)=com(sinforp).
sinfor contains the bounds of each segment.
sinfor(1,k) contains the lower bound of segment k, for k=1,2,,nseg.
sinfor(2,k) contains the upper bound of segment k, for k=1,2,,nseg.
evals(ni,nseg)
evals(1,1)=icom(evalsp).
evals contains information to indicate whether an estimate of the integral j has been obtained over segment k, and if so whether this evaluation still contributes to the direct estimate of Fj, for j=1,2,,ni and k=1,2,,nseg.
evals(j,k)=0 indicates that integral j has not been evaluated over segment k.
evals(j,k)=1 indicates that integral j has been evaluated over segment k, and that this evaluation contributes to the direct estimate of Fj.
evals(j,k)=2 indicates that integral j has been evaluated over segment k, that this evaluation contributes to the direct estimate of Fj, and that you have requested no further evaluation of this integral at this segment by setting needi(j)<0.
evals(j,k)=3 indicates that integral j has been evaluated over segment k, and this evaluation no longer contributes to the direct estimate of Fj.
evals(j,k)=4 indicates that integral j has been evaluated over segment k, that this evaluation contributes to the direct estimate of Fj, and that this segment is too small for any further splitting to be performed. Integral j also has a local error estimate over this segment above the requested tolerance. Such segments cause d01raf to return ifail=2 or 3, indicating extremely bad behaviour.
evals(j,k)=5 indicates that integral j has been evaluated over segment k, that this evaluation contributes to the direct estimate of Fj, and that this segment is too small for any further splitting to be performed. The local error estimate is however below the requested tolerance.
ds(ni,nseg)
ds(1,1)=com(dsp).
ds(j,k) contains the definite integral estimate of the jth integral over the kth segment, dsj,k, provided it has been evaluated, for j=1,2,,ni and k=1,2,,nseg.
es(ni,nseg)
es(1,1)=com(esp).
es(j,k) contains the definite integral error estimate of the jth integral over the kth segment, esj,k, provided it has been evaluated, for j=1,2,,ni and k=1,2,,nseg.
For each integral j, the direct approximation Dj of Fj, and its error estimate Ej, may be constructed as,
Fj Dj = Kj dsj,k , |Fj-Dj| Ej = Kj esj,k ,  
where Kj is the set of all contributing segments, Kj={kevals(j,k)=1, ​2, ​4​ or ​5, ​1knseg}. Dj will have been returned in dinest(j), unless extrapolation was successful, as indicated by needi(j).
Similarly, Ej will have been returned in errest(j) unless extrapolation was successful, in which case the error estimate from the extrapolation will have been returned. If for a given integral j one or more contributing segments have unacceptable error estimates, it may be possible to improve the direct approximation by replacing the contributions from these segments with more accurate estimates should these be calculable by some means. Indeed for any segment k¯k, with lower bound ak¯=sinfor(1,k¯) and upper bound bk¯=sinfor(2,k¯), one may alter the direct approximation Dj by the following,
ds j,k¯ new ak¯ bk¯ fj(x) ​ ​ dx Dj = Kj ds j,k - ds j , k¯ + ds j,k¯ new .  
The error estimate Ej may be altered similarly.

10 Example

This example integrates
F = 0 π ( x sin(2x) cos(15x) x2 sin(2x) cos(50x) ) dx .  

10.1 Program Text

Program Text (d01rafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (d01rafe.r)

11 Optional Parameters

This section can be skipped if you wish to use the default values for all optional parameters, otherwise, the following is a list of the optional parameters available. A full description of each optional parameter is provided in Section 11.1.
The following optional parameters, see Section 11.2, may be utilized by expert users in conjunction with the information provided in Section 9.1.

11.1 Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
The following symbol represents various machine constants:
All options accept the value ‘DEFAULT’ in order to return single options to their default states.
Keywords and character values are case insensitive, however they must be separated by at least one space.
Unsetable options will return the appropriate value when calling d01zlf. They will have no effect if passed to d01zkf.
For d01raf the maximum length of the argument cvalue used by d01zlf is 15.
Absolute Interval MinimumrDefault =128.0ε
r=δa, the absolute lower limit for a segment to be considered for subdivision. See also Relative Interval Minimum and Section 9.
Constraint: r128ε.
Absolute TolerancerDefault =1024ε
r=εa, the absolute tolerance required. See also Relative Tolerance and Section 3.
Constraint: r0.0.
ExtrapolationaDefault =ON
Activate or deactivate the use of the ε algorithm (Wynn (1956)). Extrapolation often reduces the number of iterations required to achieve the desired solution, but it can occasionally lead to premature convergence towards an incorrect answer.
ON
Use extrapolation.
OFF
Disable extrapolation.
Extrapolation SafeguardrDefault =1.0E−12
r=εsafe. If εq is the estimated error from the quadrature evaluation alone, and εex is the error estimate determined using extrapolation, then the extrapolated solution will only be accepted if εsafe εq εex.
Maximum SubdivisionsiDefault =50
i=maxsdiv, the maximum number of subdivisions the algorithm may use in the adaptive phase, forming at most an additional (2×maxsdiv) segments.
Primary DivisionsiDefault =1
i=spri, the number of initial segments of the domain [a,b]. By default the initial segment is the entire domain.
Constraint: 0<i<1000000.
Primary Division ModeaDefault =AUTOMATIC
Determines how the initial set of spri segments will be generated.
AUTOMATIC
d01raf will automatically generate spri segments of equal size covering the interval [a,b].
MANUAL
d01raf will use the break-points xi0, for i=1,2,,spri-1, supplied in x on initial entry to generate the initial segments covering [a,b]. These may be supplied in any order, however it will be more efficient to supply them in ascending (or descending if a>b) order. Repeated break-points are allowed, although this will generate fewer initial segments.
Note: an absolute bound on the size of an initial segment of 10.0ε is automatically applied in all cases, and will result in fewer initial subdivisions being generated if automatically generated or supplied break-points result in segments smaller than this.
Prioritize ErroraDefault =LEVEL
Indicates how new subdivisions of segments sustaining unacceptable local errors for integrals should be prioritized.
LEVEL
Segments with lower level with unsatisfactory error estimates will be chosen over segments with greater error on higher levels. This will probably lead to more integrals being improved in earlier iterations of the algorithm, and hence will probably lead to fewer repeated returns (see argument sid), and to more integrals being satisfactorily estimated if computational exhaustion occurs.
MAXERR
The segment with the worst overall error will be split, regardless of level. This will more rapidly improve the worst integral estimates, although it will probably result in the fewest integrals being improved in earlier iterations, and may hence lead to more repeated returns (see argument sid), and potentially fewer integrals satisfying the requested tolerances if computational exhaustion occurs.
Quadrature RuleaDefault =GK15
The basic quadrature rule to be used during the integration. Currently 6 Gauss–Kronrod rules are available, all identifiable by the letters GK followed by the number of points required by the Kronrod rule. Higher order rules generally provide higher accuracy with fewer subdivisons. However, for integrands with sharp singularities, lower order rules may be more efficient, particularly if the integrand away from the singularity is well behaved. With higher order rules, you may need to increase the Absolute Interval Minimum and the Relative Interval Minimum to maintain numerical difference between the abscissae and the segment bounds.
GK15
The Gauss–Kronrod rule based on 7 Gauss points and 15 Kronrod points.
GK21
The Gauss–Kronrod rule based on 10 Gauss points and 21 Kronrod points. This is the rule used by d01rjf.
GK31
The Gauss–Kronrod rule based on 15 Gauss points and 31 Kronrod points.
GK41
The Gauss–Kronrod rule based on 20 Gauss points and 41 Kronrod points.
GK51
The Gauss–Kronrod rule based on 25 Gauss points and 51 Kronrod points.
GK61
The Gauss–Kronrod rule based on 30 Gauss points and 61 Kronrod points. This is the highest order rule, most suitable for highly oscilliatory integrals.
Relative Interval MinimumrDefault =1.0E−6
r=δr, the relative factor in the lower limit, δr|b-a|, for a segment to be considered for subdivision. See also Absolute Interval Minimum and Section 9.
Constraint: r0.0.
Relative TolerancerDefault =ε
r=εr, the required relative tolerance. See also Absolute Tolerance and Section 3.
Constraint: r0.0.
Note: setting both εr=εa=0.0 is possible, although it will most likely result in an excessive amount of computational effort.

11.2 Diagnostic Options

These options are provided for expert users who wish to examine and modify the precise details of the computation. They should only be used after d01raf returns, as opposed to the options listed in Section 11.1 which must be used before the first call to d01raf.
Index LDIiquery only
Ildi, the index of icom required for obtaining ldi. See Section 9.1.
Index LDRiquery only
Ildr, the index of icom required for obtaining ldr. See Section 9.1.
Index NSDIViquery only
Insdiv, the index of icom required for obtaining nsdiv. See Section 9.1.
Index NSEGiquery only
Inseg, the index of icom required for obtaining nseg. See Section 9.1.
Index FCPiquery only
Ifcp, the index of icom required for obtaining fcp. See Section 9.1.
Index EVALSPiquery only
Ievalsp, the index of icom required for obtaining evalsp. See Section 9.1.
Index DSPiquery only
Idsp, the index of icom required for obtaining dsp. See Section 9.1.
Index ESPiquery only
Iesp, the index of icom required for obtaining esp. See Section 9.1.
Index SINFOIPiquery only
Isinfoip, the index of icom required for obtaining sinfoip. See Section 9.1.
Index SINFORPiquery only
Isinforp, the index of icom required for obtaining sinforp. See Section 9.1.