NAG Library Routine Document

D01RBF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     MONIT – SUBROUTINE, supplied by the NAG Library or the user.External Procedure

MONIT allows you to examine details of the adaptive process after a call of D01RAF returning $\mathbf{IREVCM}=11$ or $12$. Additionally, after a call of D01RAF returning $\mathbf{IREVCM}=0$, MONIT may overwrite that information.

If no monitoring is required, MONIT may be the dummy monitoring routine D01RBM. (D01RBM is included in the NAG Library.)

The specification of MONIT is:

SUBROUTINE MONIT ( NI, NS, DINEST, ERREST, FCOUNT, SINFOI, EVALS, LDI, SINFOR, FS, ES, LDR, IUSER, RUSER) INTEGER  NI, NS, FCOUNT(NI), SINFOI(LDI,*), EVALS(LDI,*), LDI, LDR, IUSER(*) REAL (KIND=nag_wp)  DINEST(NI), ERREST(NI), SINFOR(LDR,*), FS(LDR,*), ES(LDR,*), RUSER(*)

1:     NI – INTEGERInput

On entry: $n_i$, the number of integrands specified in D01RAF.

2:     NS – INTEGERInput

On entry: $n_s$, the number of segments formed during the adaptive procedure that can currently be examined. $n_s=2n_{\mathit{sdiv}}+s_{\mathit{pri}}$, where $n_{\mathit{sdiv}}$ is the number of segments that have been subdivided (the number of subdivisions).

3:     DINEST(NI) – REAL (KIND=nag_wp) arrayInput/Output

On entry: $\mathbf{DINEST}\left(\mathit{j}\right)$ contains the current estimate of the definite integral of integrand $\mathit{j}$, for $\mathit{j}=1,2,\dots ,n_i$.

On exit: you may refine the estimates in DINEST. This should only be done after D01RAF has returned $\mathbf{IREVCM}=0$.

4:     ERREST(NI) – REAL (KIND=nag_wp) arrayInput/Output

On entry: $\mathbf{ERREST}\left(\mathit{j}\right)$ contains the current error estimate associated with integral $\mathit{j}$, for $\mathit{j}=1,2,\dots ,n_i$.

On exit: you may refine the estimates in ERREST. This should only be done after D01RAF has returned $\mathbf{IREVCM}=0$.

5:     FCOUNT(NI) – INTEGER arrayInput

On entry: $\mathbf{FCOUNT}\left(\mathit{j}\right)$ contains the number of different approximations of integral $\mathit{j}$ calculated so far, for $\mathit{j}=1,2,\dots ,n_i$.

6:     SINFOI(LDI,$*$) – INTEGER arrayInput

On entry: contains information about the hierarchy of splitting.

For $k=1,\dots ,n_s$:

$\mathbf{SINFOI}\left(1,k\right)$

Contains a unique identifier, the SID, related to segment $k$.

$\mathbf{SINFOI}\left(2,k\right)$

Contains the parent segment number of segment $k$, the reference to the segment that was split to create segment $k$.

$\mathbf{SINFOI}\left(3,k\right)$ and $\mathbf{SINFOI}\left(4,k\right)$

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.

$\mathbf{SINFOI}\left(5,k\right)$

Contains the level at which the segment exists, corresponding to $n_a+1$, where $n_a$ is the number of ancestor segments of segment $k$.

If $\mathbf{SINFOI}\left(5,k\right)<0$, this segment is considered too small for further splitting, and its level is $\left|\mathbf{SINFOI}\left(5,k\right)\right|$.

7:     EVALS(LDI,$*$) – INTEGER arrayInput

On entry: contains information to indicate whether an estimate of the integral $\mathit{j}$ has been obtained over segment $\mathit{k}$, and if so whether this evaluation still contributes to the approximation in $\mathbf{DINEST}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,n_i$ and $\mathit{k}=1,2,\dots ,n_s$.

$\mathbf{EVALS}\left(j,k\right)=0$

Indicates that integral $j$ has not been evaluated over segment $k$.

$\mathbf{EVALS}\left(j,k\right)=1$

Indicates that integral $j$ has been evaluated over segment $k$, and that this evaluation contributes to the total approximation $\mathbf{DINEST}\left(j\right)$.

$\mathbf{EVALS}\left(j,k\right)=2$

Indicates that integral $j$ has been evaluated over segment $k$, that this evaluation contributes to the total approximation $\mathbf{DINEST}\left(j\right)$, and that you have requested no further evaluation of this integral at this segment by setting $\mathbf{NEEDI}\left(j\right)<0$.

$\mathbf{EVALS}\left(j,k\right)=3$

Indicates that integral $j$ has been evaluated over segment $k$, and this evaluation no longer contributes to $\mathbf{DINEST}\left(j\right)$.

$\mathbf{EVALS}\left(j,k\right)=4$

Indicates that integral $j$ has been evaluated over segment $k$, that this evaluation contributes to the total approximation $\mathbf{DINEST}\left(j\right)$, 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 $\mathbf{IFAIL}=\mathbf{2}$ or $\mathbf{3}$, indicating extremely bad behaviour.

$\mathbf{EVALS}\left(j,k\right)=5$

Indicates that integral $j$ has been evaluated over segment $k$, that this evaluation contributes to the total approximation of $\mathbf{DINEST}\left(j\right)$, and that this segment is too small for any further splitting to be performed. The local error estimate is however below the requested tolerance.

8:     LDI – INTEGERInput

On entry: the leading dimension of arrays SINFOI and EVALS.

9:     SINFOR(LDR,$*$) – REAL (KIND=nag_wp) arrayInput

On entry: SINFOR contains the bounds of each segment $\mathit{k}$, for $\mathit{k}=1,2,\dots ,n_s$.

$\mathbf{SINFOR}\left(1,k\right)$

Contains the lower bound of segment $k$.

$\mathbf{SINFOR}\left(2,k\right)$

Contains the upper bound of segment $k$.

10:   FS(LDR,$*$) – REAL (KIND=nag_wp) arrayInput

On entry: the $\mathit{j}$th element of the $\mathit{k}$th column of FS contains the definite integral estimate of the $\mathit{j}$th integral over the $\mathit{k}$th segment, for $\mathit{j}=1,2,\dots ,n_i$ and $\mathit{k}=1,2,\dots ,n_s$.

11:   ES(LDR,$*$) – REAL (KIND=nag_wp) arrayInput

On entry: the $\mathit{j}$th elements of the $\mathit{k}$th column of ES contains the definite integral error estimate of the $\mathit{j}$th integral over the $\mathit{k}$th segment, for $\mathit{j}=1,2,\dots ,n_i$ and $\mathit{k}=1,2,\dots ,n_s$.

12:   LDR – INTEGERInput

On entry: the leading order of arrays SINFOR, FS and ES.

13:   IUSER($*$) – INTEGER arrayUser Workspace

14:   RUSER($*$) – REAL (KIND=nag_wp) arrayUser Workspace

MONIT is called with the parameters IUSER and RUSER as supplied to D01RBF. You are free to use the arrays IUSER and RUSER to supply information to MONIT as an alternative to using COMMON global variables.

MONIT must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which D01RBF is called. Parameters denoted as Input must not be changed by this procedure.

2:     NI – INTEGERInput

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

3:     DINEST(NI) – REAL (KIND=nag_wp) arrayInput/Output

On entry: $\mathbf{DINEST}\left(\mathit{j}\right)$ contains the current estimate of the definite integral of integrand $\mathit{j}$, for $\mathit{j}=1,2,\dots ,n_i$.

On exit: DINEST is not altered by D01RBF directly. It may be changed by MONIT.

4:     ERREST(NI) – REAL (KIND=nag_wp) arrayInput/Output

On entry: $\mathbf{ERREST}\left(\mathit{j}\right)$ contains the current error estimate associated with integral $\mathit{j}$, for $\mathit{j}=1,2,\dots ,n_i$.

On exit: ERREST is not altered by D01RBF directly. It may be changed by MONIT.

5:     ICOM(LICOM) – INTEGER arrayCommunication Array

On entry: the elements of this array must not be changed.

6:     LICOM – INTEGERInput

On entry: the dimension of the array ICOM as declared in the (sub)program from which D01RBF is called. Normally this will be the same value LICOM passed to D01RAF.

Constraint: $\mathbf{LICOM}\ge 50$.

Note: if $\mathbf{LICOM}<\mathbf{LICUSD}$, (i.e., LICOM is less than the value passed to D01RAF) not all segments may be investigated using MONIT (see parameter NS) and D01RBF will return $\mathbf{IFAIL}=\mathbf{1}$.

7:     LICUSD – INTEGEROutput

On exit: the number of elements of the array ICOM, passed to D01RAF, actually used.

8:     COM(LCOM) – REAL (KIND=nag_wp) arrayCommunication Array

On entry: the elements of this array must not be changed.

9:     LCOM – INTEGERInput

On entry: the dimension of the array COM as declared in the (sub)program from which D01RBF is called. The dimension of the array COM. Normally this will be the same value LCOM passed to D01RAF.

Constraint: $\mathbf{LCOM}\ge 50$.

Note: if $\mathbf{LCOM}<\mathbf{LCUSD}$, (i.e., LCOM is less than the value passed to D01RAF) not all segments may be investigated using MONIT (see parameter NS) and D01RBF will return $\mathbf{IFAIL}=\mathbf{1}$.

10:   LCUSD – INTEGEROutput

On exit: the number of elements of COM used by D01RAF.

11:   IUSER($*$) – INTEGER arrayUser Workspace

12:   RUSER($*$) – REAL (KIND=nag_wp) arrayUser Workspace

IUSER and RUSER are not used by D01RBF, but are passed directly to MONIT and may be used to pass information to this routine as an alternative to using COMMON global variables.

13:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if $\mathbf{IFAIL}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }1$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

On entry, LICOM or LCOM is insufficient for a complete examination of the communication arrays.
A maximum $⟨\mathit{\text{value}}⟩$ segments out of $⟨\mathit{\text{value}}⟩$ are examinable.
On entry, $\mathbf{LICOM}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{LICOM}\ge ⟨\mathit{\text{value}}⟩$.
On entry, $\mathbf{LCOM}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{LCOM}\ge ⟨\mathit{\text{value}}⟩$.

$\mathbf{IFAIL}=21$

On entry, NI is not consistent with that used to construct the communication arrays.
On entry, $\mathbf{NI}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{NI}=⟨\mathit{\text{value}}⟩$.

$\mathbf{IFAIL}=61$

On entry, $\mathbf{LICOM}<50$.

$\mathbf{IFAIL}=91$

On entry, $\mathbf{LCOM}<50$.

$\mathbf{IFAIL}=1101$

Either the communication arrays have not been created by D01RAF, or they have become corrupted.

7  Accuracy

8  Further Comments

9  Example