NAG C Library Function Document

nag_quad_1d_gen_vec_multi_rcomm (d01rac)

1

Purpose

2

Specification

3

Description

liopts = 100
lopts = 100
allocate(iopts(liopts),opts(lopts))
d01zkc('initialize = d01rac',iopts,liopts,opts,lopts,fail)
d01zkc('option = value',iopts,liopts,opts,lopts,fail)
...
d01rcc(ni,lenxrq,ldfmrq,sdfmrq,licmin,licmax,lcmin,lcmax,
       iopts,opts,fail)
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))

irevcm = 1
while irevcm≠0
    d01rac(irevcm,ni,a,b,sid,needi,x,lenx,nx,fm,ldfm,
           dinest,errest,iopts,opts,icom,licom,com,
           lcom,fail)
    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 fail
    end select
end while

d01zlc('option',ivalue,rvalue,cvalue,optype,iopts,opts,fail)
...

4

References

5

Arguments

1:    $\mathbf{irevcm}$ – Integer *Input/Output

On initial entry: $\mathbf{irevcm}=1$.

$\mathbf{irevcm}=1$

Sets up data structures in icom and com and starts a new integration.

Constraint: $\mathbf{irevcm}=1$ on initial entry.

On intermediate exit: $\mathbf{irevcm}=11$ or $12$.

irevcm requests the integrands $f_j\left(x_i\right)$ be evaluated for all required $j\in 1,\dots ,n_i$ as indicated by needi, and at all the points $x_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n_x$. Abscissae $x_i$ are provided in $\mathbf{x}\left[i-1\right]$ and $f_j\left(x_i\right)$ must be returned in $\mathbf{FM}\left(j,i\right)$.

During the initial solve phase:

$\mathbf{irevcm}=11$

Function values are required to construct the initial estimates of the definite integrals.

If $\mathbf{needi}\left[j-1\right]=1$, $f_j\left(x_i\right)$ must be supplied in $\mathbf{FM}\left(j,i\right)$. This will be the case unless you have abandoned the evaluation of specific integrals on a previous call.

If $\mathbf{needi}\left[j-1\right]=0$, you have previously abandoned the evaluation of integral $j$, and hence should not supply the value of $f_j\left(x_i\right)$.

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, $\mathbf{needi}\left[\mathit{j}-1\right]$, for $\mathit{j}=1,2,\dots ,n_i$, will be set to this negative value and $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_USER_STOP will be returned.

During the adaptive solve phase:

$\mathbf{irevcm}=12$

Function values are required to improve the estimates of the definite integrals.

If $\mathbf{needi}\left[j-1\right]=0$, any evaluation of $f_j\left(x_i\right)$ will be discarded, so there is no need to provide them.

If $\mathbf{needi}\left[j-1\right]=1$, $f_j\left(x_i\right)$ must be provided in $\mathbf{FM}\left(j,i\right)$.

If $\mathbf{needi}\left[j-1\right]=2$, $3$ or $4$, the current error estimate of integral $j$ does not require integrand $j$ to be evaluated and provided in $\mathbf{FM}\left(j,i\right)$. Should you choose to, integrand $j$ can be evaluated in which case $\mathbf{needi}\left[j-1\right]$ 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 $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_ACCURACY or NE_QUAD_BAD_SUBDIV_INT 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, nag_quad_1d_gen_vec_multi_rcomm (d01rac) will terminate, (see $\mathbf{irevcm}=11$ and $\mathbf{irevcm}=12$ above).

On final exit: $\mathbf{irevcm}=0$.

$\mathbf{irevcm}=0$

Indicates the algorithm has completed.

Note: any values you return to nag_quad_1d_gen_vec_multi_rcomm (d01rac) 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 nag_quad_1d_gen_vec_multi_rcomm (d01rac). If your code inadvertently does return any NaNs or infinities, nag_quad_1d_gen_vec_multi_rcomm (d01rac) is likely to produce unexpected results.

2:    $\mathbf{ni}$ – IntegerInput

On entry: $n_i$, the number of integrands.

3:    $\mathbf{a}$ – doubleInput

On entry: $a$, the lower bound of the domain.

4:    $\mathbf{b}$ – doubleInput

On entry: $b$, the upper bound of the domain.

If $\left|b-a\right|<10\epsilon$, where $\epsilon$ is the machine precision (see nag_machine_precision (X02AJC)), nag_quad_1d_gen_vec_multi_rcomm (d01rac) will return $\mathbf{dinest}\left[\mathit{j}-1\right]=\mathbf{errest}\left[\mathit{j}-1\right]=0.0$, for $\mathit{j}=1,2,\dots ,n_i$.

5:    $\mathbf{sid}$ – Integer *Output

For advanced users.

On intermediate exit: sid identifies a specific set of abscissae, $\mathbf{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 $\mathbf{x}$, and reuse them should nag_quad_1d_gen_vec_multi_rcomm (d01rac) return the same value of sid, i.e., the same set of abscissae was used.

6:    $\mathbf{needi}\left[\mathbf{ni}\right]$ – IntegerInput/Output

On initial entry: need not be set.

On intermediate exit: $\mathbf{needi}\left[j-1\right]$ indicates what action must be taken for integral $j=1,2,\dots n_i$ (see irevcm).

$\mathbf{needi}\left[j-1\right]=0$

Do not provide $f_j\left(x_i\right)$. Any provided values will be ignored.

$\mathbf{needi}\left[j-1\right]=1$

The values $f_j\left(x_{\mathit{i}}\right)$ must be provided in $\mathbf{FM}\left(j,\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n_x$.

$\mathbf{needi}\left[j-1\right]=2$

The values $f_j\left(x_i\right)$ 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 $\mathbf{needi}\left[j-1\right]=1$, and supply $f_j\left(x_{\mathit{i}}\right)$ in $\mathbf{FM}\left(j,\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n_x$.

$\mathbf{needi}\left[j-1\right]=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 $f_j\left(x_i\right)$ 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 $\mathbf{needi}\left[j-1\right]=1$, and supply $f_j\left(x_{\mathit{i}}\right)$ in $\mathbf{FM}\left(j,\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n_x$.

$\mathbf{needi}\left[j-1\right]=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 $\mathbf{dinest}\left[j-1\right]$ 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 $x_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n_x$, and setting $\mathbf{needi}\left[j-1\right]=1$. Integral and error estimation will be performed again during the next iteration.

On intermediate re-entry: $\mathbf{needi}\left[j-1\right]$ may be used to indicate what action you have taken for integral $j$.

$\mathbf{needi}\left[j-1\right]=1$

You have provided the values $f_j\left(x_{\mathit{i}}\right)$ in $\mathbf{FM}\left(j,\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n_x$.

$\mathbf{needi}\left[j-1\right]<0$

You are abandoning the evaluation of integral $j$. The current values of $\mathbf{dinest}\left[j-1\right]$ and $\mathbf{errest}\left[j-1\right]$ will be returned on final completion.

Otherwise you have not provided the value $f_j\left(x_i\right)$.

On final exit: $\mathbf{needi}\left[j-1\right]$ indicates the final state of integral $j$.

$\mathbf{needi}\left[j-1\right]=0$

The error estimate for $F_j$ is below the requested tolerance.

$\mathbf{needi}\left[j-1\right]=1$

The error estimate for $F_j$ is below the requested tolerance after extrapolation.

$\mathbf{needi}\left[j-1\right]=2$

The error estimate for $F_j$ is above the requested tolerance.

$\mathbf{needi}\left[j-1\right]=3$

The error estimate for $F_j$ is above the requested tolerance, and extremely bad behaviour of integral $j$ has been detected.

$\mathbf{needi}\left[j-1\right]<0$

You prohibited further evaluation of integral $j$.

7:    $\mathbf{x}\left[\mathbf{lenx}\right]$ – doubleInput/Output

On initial entry: if $\mathbf{Primary\; Division\; Mode}=\mathrm{AUTOMATIC}$, x need not be set. This is the default behaviour.

If $\mathbf{Primary\; Division\; Mode}=\mathrm{MANUAL}$, x is used to supply a set of initial ‘break-points’ inside the domain of integration. Specifically, $\mathbf{x}\left[i-1\right]$ must contain a break-point $x_{\mathit{i}}^0$, for $\mathit{i}=1,2,\dots ,\left(s_{\mathit{pri}}-1\right)$, where $s_{\mathit{pri}}$ is the number of $\mathbf{Primary\; Divisions}$.

Constraint: if break-points are supplied, $x_{\mathit{i}}^0\in \left(a,b\right)$, $\left|x_{\mathit{i}}^0-a\right|>10.0\epsilon$, $\left|x_{\mathit{i}}^0-b\right|>10.0\epsilon$, for $\mathit{i}=1,2,\dots ,\left(s_{\mathit{pri}}-1\right)$.

On intermediate exit: $\mathbf{x}\left[\mathit{i}-1\right]$ is the abscissa $x_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n_x$, at which the appropriate integrals must be evaluated.

8:    $\mathbf{lenx}$ – IntegerInput

On entry: the dimension of the array x. Currently $\mathbf{lenx}=\max \left(122,s_{\mathit{pri}}-1\right)$ will be sufficient for all cases.

Constraint: $\mathbf{lenx}\ge \mathit{lenxrq}$, where $\mathit{lenxrq}$ is dependent upon the options currently set (see Section 11). $\mathit{lenxrq}$ is returned as lenxrq from nag_quad_1d_gen_vec_multi_dimreq (d01rcc).

9:    $\mathbf{nx}$ – Integer *Input/Output

On initial entry: need not be set.

On intermediate exit: $n_x$, the number of abscissae at which integrands are required.

On intermediate re-entry: must not be changed.

10:  $\mathbf{fm}\left[\mathit{dim}\right]$ – const doubleInput

Note: the dimension, dim, of the array fm must be at least $\mathbf{ldfm}\times \mathit{sdfmrq}$, where $\mathit{sdfmrq}$ is dependent upon $n_i$ and the options currently set. $\mathit{sdfmrq}$ is returned as sdfmrq from nag_quad_1d_gen_vec_multi_dimreq (d01rcc). If default options are chosen, $\mathit{sdfmrq}=\mathit{lenxrq}$.

On initial entry: need not be set.

On intermediate re-entry: if indicated by $\mathbf{needi}\left[j-1\right]$ you must supply the values $f_j\left(x_i\right)$ in $\mathbf{FM}\left(\mathit{j},\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n_x$ and $\mathit{j}=1,2,\dots ,n_i$.

11:  $\mathbf{ldfm}$ – IntegerInput

On entry: the stride separating matrix row elements in the array fm.

Constraint: $\mathbf{ldfm}\ge \mathit{ldfmrq}$, where $\mathit{ldfmrq}$ is dependent upon $n_i$ and the options currently set. $\mathit{ldfmrq}$ is returned as ldfmrq from nag_quad_1d_gen_vec_multi_dimreq (d01rcc). If default options are chosen, $\mathit{ldfmrq}=n_i$, implying $\mathbf{ldfm}\ge \mathbf{ni}$.

12:  $\mathbf{dinest}\left[\mathbf{ni}\right]$ – doubleInput/Output

$\mathbf{dinest}\left[j-1\right]$ contains the current estimate of the definite integral $F_j$.

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 $\mathbf{irevcm}=0$, this will be the final solution.

13:  $\mathbf{errest}\left[\mathbf{ni}\right]$ – doubleInput/Output

$\mathbf{errest}\left[j-1\right]$ contains the current error estimate of the definite integral $F_j$.

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 $\mathbf{irevcm}=0$, errest contains the final error estimates of the ni integrals.

14:  $\mathbf{iopts}\left[100\right]$ – const IntegerCommunication Array

15:  $\mathbf{opts}\left[100\right]$ – const doubleCommunication Array

The arrays iopts and opts MUST NOT be altered between calls to any of the functions nag_quad_1d_gen_vec_multi_rcomm (d01rac), nag_quad_1d_gen_vec_multi_dimreq (d01rcc), nag_quad_opt_set (d01zkc) and nag_quad_opt_get (d01zlc).

16:  $\mathbf{icom}\left[\mathbf{licom}\right]$ – IntegerCommunication Array

icom contains details of the integration procedure, including information on the integration of the $n_i$ integrals over individual segments. This data is stored sequentially in the order that segments are created. For further information see Section 9.1.

17:  $\mathbf{licom}$ – IntegerInput

On entry: the dimension of the array icom.

Constraint: $\mathbf{licom}\ge \mathit{licmin}$, where $\mathit{licmin}$ is dependent upon ni and the current options set. $\mathit{licmin}$ is returned as licmin from nag_quad_1d_gen_vec_multi_dimreq (d01rcc). If the default options are set, $\mathit{licmin}=55+6\times \mathbf{ni}$. Larger values than $\mathit{licmin}$ are recommended if you anticipate that any integrals will require the domain to be further subdivided.

The maximum value that may be required, $\mathit{licmax}$, is returned as licmax from nag_quad_1d_gen_vec_multi_dimreq (d01rcc). If default options are chosen, except for possibly increasing the value of $s_{\mathit{pri}}$, $\mathit{licmax}=50+5\times \mathbf{ni}+\left(s_{\mathit{pri}}+100\right)\times \left(5+\mathbf{ni}\right)$.

18:  $\mathbf{com}\left[\mathbf{lcom}\right]$ – doubleCommunication Array

com contains details of the integration procedure, including information on the integration of the $n_i$ integrals over individual segments. This data is stored sequentially in the order that segments are created. For further information see Section 9.1.

19:  $\mathbf{lcom}$ – IntegerInput

On entry: the dimension of the array com.

Constraint: $\mathbf{lcom}>\mathit{lcmin}$, where $\mathit{lcmin}$ is dependent upon ni, $s_{\mathit{pri}}$ and the current options set. $\mathit{lcmin}$ is returned as lcmin from nag_quad_1d_gen_vec_multi_dimreq (d01rcc). If default options are set, $\mathit{lcmin}=96+12\times \mathbf{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, $\mathit{lcmax}$, of lcom that may be required, is returned as lcmax from nag_quad_1d_gen_vec_multi_dimreq (d01rcc). If default options are chosen, $\mathit{lcmax}=94+9\times \mathbf{ni}+⌈\mathbf{ni}/2⌉+\left(s_{\mathit{pri}}+100\right)\times \left(2+⌈\mathbf{ni}/2⌉+2\times \mathbf{ni}\right)$.

20:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ACCURACY

At least one error estimate exceeded the requested tolerances.

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_INT

irevcm had an illegal value.
On entry, $\mathbf{irevcm}=〈\mathit{\text{value}}〉$.

On entry, $\mathbf{ni}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ni}\ge 1$.

NE_INT_2

$\mathbf{ldfm}<\mathit{ldfmrq}$. If default options are chosen, this implies $\mathbf{ldfm}<\mathbf{ni}$.
On entry, $\mathbf{ldfm}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldfm}\ge 〈\mathit{\text{value}}〉$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_INVALID_ARRAY

On entry, one of icom and com has become corrupted.

NE_INVALID_OPTION

Either the option arrays iopts and opts have not been initialized for nag_quad_1d_gen_vec_multi_rcomm (d01rac), or they have become corrupted.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

NE_QUAD_BAD_SUBDIV_INT

Extremely bad behaviour was detected for at least one integral.

Extremely bad behaviour was detected for at least one integral. At least one other integral error estimate was above the requested tolerance.

NE_QUAD_BRKPTS_INVAL

On entry, $\mathbf{Primary\; Division\; Mode}=\mathrm{MANUAL}$ and at least one supplied break-point in x is outside of the domain of integration.

NE_TOO_SMALL

lcom is insufficient for additional subdivision.
On entry, $\mathbf{lcom}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lcom}\ge 〈\mathit{\text{value}}〉$.

lenx is insufficient for the chosen options.
On entry, $\mathbf{lenx}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lenx}\ge 〈\mathit{\text{value}}〉$.

licom is insufficient for additional subdivision.
On entry, $\mathbf{licom}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{licom}\ge 〈\mathit{\text{value}}〉$.

NE_USER_STOP

Evaluation of all integrals has been stopped during the initial phase.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

9.1

Details of the Computation

10

Example

10.1

Program Text

Program Text (d01race.c)

10.2

Program Data

10.3

Program Results

Program Results (d01race.r)

11

Optional Parameters

• Absolute Interval Minimum
• Absolute Tolerance
• Extrapolation
• Extrapolation Safeguard
• Maximum Subdivisions
• Primary Division Mode
• Primary Divisions
• Prioritize Error
• Quadrature Rule
• Relative Interval Minimum
• Relative Tolerance

11.1

Description of the Optional Parameters

• the keywords, where the minimum abbreviation of each keyword is underlined;
• a parameter value, where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
• the default value.

AUTOMATIC

nag_quad_1d_gen_vec_multi_rcomm (d01rac) will automatically generate $s_{\mathit{pri}}$ segments of equal size covering the interval $\left[a,b\right]$.

MANUAL

nag_quad_1d_gen_vec_multi_rcomm (d01rac) will use the break-points $x_{\mathit{i}}^0$, for $\mathit{i}=1,2,\dots ,s_{\mathit{pri}}-1$, supplied in x on initial entry to generate the initial segments covering $\left[a,b\right]$. 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.

11.2

Diagnostic Options