NAG Library Routine Document

d01esf  (md_sgq_multi_vec)

1

Purpose

2

Specification

3

Description

3.1

Comparing Quadrature Over Full and Sparse Grids

3.2

Sparse Grid Quadrature

3.3

Using d01esf

4

References

5

Arguments

1:     $\mathbf{ni}$ – IntegerInput

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

Constraint: $\mathbf{ni}\ge 1$.

2:     $\mathbf{ndim}$ – IntegerInput

On entry: $d$, the number of dimensions.

Constraint: $\mathbf{ndim}\ge 1$.

3:     $\mathbf{f}$ – Subroutine, supplied by the user.External Procedure

f must return the value of the integrands $f_j$ at a set of $n_x$ $d$-dimensional points ${\mathbf{x}}_i$, implicitly supplied as columns of a matrix $X\left(d,n_x\right)$. If $X$ was supplied explicitly you would find that most of the elements attain the same value, $x_{\mathrm{tr}}$; the larger the number of dimensions, the greater the proportion of elements of $X$ would be equal to $x_{\mathrm{tr}}$. So, $X$ is effectively a sparse matrix, except that the ‘zero’ elements are replaced by elements that are all equal to the value $x_{\mathrm{tr}}$. For this reason $X$ is supplied, as though it were a sparse matrix, in compressed column storage (CCS) format (see the F11 Chapter Introduction).

Individual entries $x_{\mathit{k},i}$ of $X$, for $\mathit{k}=1,2,\dots ,d$, are either trivially valued, in which case $x_{k,i}=x_{\mathrm{tr}}$, or are non-trivially valued. For point $i$, the non-trivial row indices and corresponding abscissae values are supplied in elements $c\left(\mathit{i}\right)=\mathbf{icolzp}\left(\mathit{i}\right),\dots ,\mathbf{icolzp}\left(\mathit{i}+1\right)-1$, for $\mathit{i}=1,2,\dots ,n_x$, of the arrays irowix and xs, respectively. Hence the $i$th column of the matrix $X$ is retrievable as

$$\begin{array}{l}X\left(\mathbf{irowix}\left(c\left(i\right)\right),i\right)=\mathbf{xs}\left(c\left(i\right)\right)\text{,}\\ \\ X\left(k\notin \mathbf{irowix}\left(c\left(i\right)\right),i\right)=x_{\mathrm{tr}}\text{.}\end{array}$$

An equivalent integer valued matrix $Q$ is also implicitly provided. This contains the unique indices $q_{k,i}$ of the underlying one-dimensional quadrature rule corresponding to the individual abscissae $x_{k,i}$. For trivial abscissae, the implicit index $q_{k,i}=1$. $Q$ is supplied in the same CCS format as $X$, with the non-trivial values supplied in qs.

The specification of f is:

Fortran Interface

Subroutine f ( ni, ndim, nx, xtr, nntr, icolzp, irowix, xs, qs, fm, iflag, iuser, ruser) Integer, Intent (In) :: ni, ndim, nx, nntr, icolzp(nx+1), irowix(nntr), qs(nntr) Integer, Intent (Inout) :: iflag, iuser(*) Real (Kind=nag_wp), Intent (In) :: xtr, xs(nntr) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Real (Kind=nag_wp), Intent (Out) :: fm(ni,nx)

C Header Interface

#include nagmk26.h void  f ( const Integer *ni, const Integer *ndim, const Integer *nx, const double *xtr, const Integer *nntr, const Integer icolzp[], const Integer irowix[], const double xs[], const Integer qs[], double fm[], Integer *iflag, Integer iuser[], double ruser[])

1:     $\mathbf{ni}$ – IntegerInput

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

2:     $\mathbf{ndim}$ – IntegerInput

On entry: $d$, the number of dimensions.

3:     $\mathbf{nx}$ – IntegerInput

On entry: $n_x$, the number of points $x_i$, corresponding to the number of columns of $X$, at which the set of integrands must be evaluated.

4:     $\mathbf{xtr}$ – Real (Kind=nag_wp)Input

On entry: $x_{\mathrm{tr}}$, the value of the trivial elements of $X$.

5:     $\mathbf{nntr}$ – IntegerInput

On entry: if $\mathbf{iflag}>0$, the number of non-trivial elements of $X$.

If $\mathbf{iflag}=0$, the total number of abscissae from the underlying one-dimensional quadrature.

6:     $\mathbf{icolzp}\left(\mathbf{nx}+1\right)$ – Integer arrayInput

On entry: the set $\left\{\mathbf{icolzp}\left(\mathit{i}\right),\dots ,\mathbf{icolzp}\left(\mathit{i}+1\right)-1\right\}$ contains the indices of irowix and xs corresponding to the non-trivial elements of column $\mathit{i}$ of $X$ and hence of the point ${\mathbf{x}}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n_x$.

7:     $\mathbf{irowix}\left(\mathbf{nntr}\right)$ – Integer arrayInput

On entry: the row indices corresponding to the non-trivial elements of $X$.

8:     $\mathbf{xs}\left(\mathbf{nntr}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: $x_{k,i}\ne x_{\mathrm{tr}}$, the non-trivial entries of $X$.

9:     $\mathbf{qs}\left(\mathbf{nntr}\right)$ – Integer arrayInput

On entry: $q_{k,i}\ne 1$, the indices of the underlying quadrature rules corresponding to $x_{k,i}\ne x_{\mathrm{tr}}$.

10:   $\mathbf{fm}\left(\mathbf{ni},\mathbf{nx}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: $\mathbf{fm}\left(\mathit{p},\mathit{i}\right)=f_{\mathit{p}}\left({\mathbf{x}}_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,n_x$ and $\mathit{p}=1,2,\dots ,n_{\mathit{i}}$.

11:   $\mathbf{iflag}$ – IntegerInput/Output

On entry: if $\mathbf{iflag}=0$, this is the first call to f. $n_x=1$, and the entire point ${\mathbf{x}}_1$ will satisfy $x_{\mathit{k},1}=x_{\mathrm{tr}}$, for $\mathit{k}=1,2,\dots ,d$. In addition, nntr contains the total number of abscissae from the underlying one-dimensional quadrature; xs contains the complete set of abscissae and qs contains the corresponding quadrature indices, with $\mathbf{xs}\left(1\right)=x_{\mathrm{tr}}$ and $\mathbf{qs}\left(1\right)=1$. This will always be called in serial.

In subsequent calls to f, $\mathbf{iflag}=1$. Subsequent calls may be made from within an OpenMP parallel region. See Section 8 for details.

On exit: set $\mathbf{iflag}<0$ if you wish to force an immediate exit from d01esf with $\mathbf{ifail}=-\mathbf{1}$.

12:   $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

13:   $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

f is called with the arguments iuser and ruser as supplied to d01esf. You should use the arrays iuser and ruser to supply information to f.

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

Note: f should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d01esf. If your code inadvertently does return any NaNs or infinities, d01esf is likely to produce unexpected results.

4:     $\mathbf{maxdlv}\left(\mathbf{ndim}\right)$ – Integer arrayInput

On entry: $\mathbf{m}$, the array of maximum levels for each dimension. $\mathbf{maxdlv}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,d$, contains $m_{\mathit{j}}$, the maximum level of quadrature rule dimension j will support.

The default value, $\min \left(m_q,L\right)$ will be used if either $\mathbf{maxdlv}\left(j\right)\le 0$ or $\mathbf{maxdlv}\left(j\right)\ge \min \left(m_q,L\right)$ (for details on the default values for $m_q$ and $L$ and on how to change these values see the options Maximum Level, Maximum Quadrature Level and Quadrature Rule).

If $\mathbf{maxdlv}\left(j\right)=1$ for all $j$, only one evaluation will be performed, and as such no error estimation will be possible.

Suggested value: $\mathbf{maxdlv}\left(j\right)=0$ for all $j=1,2,\dots ,d$.

Note: setting non-default values for some dimensions makes the assumption that the contribution from the omitted subspaces is $0$. The integral and error estimates will only be based on included subspaces, which if the $0$ contribution assumption is not valid will be erroneous.

5:     $\mathbf{dinest}\left(\mathbf{ni}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: $\mathbf{dinest}\left(\mathit{p}\right)$ contains the final estimate ${\hat{F}}_{\mathit{p}}$ of the definite integral $F_p$, for $\mathit{p}=1,2,\dots ,n_i$.

6:     $\mathbf{errest}\left(\mathbf{ni}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: $\mathbf{errest}\left(\mathit{p}\right)$ contains the final error estimate $E_p$ of the definite integral $F_p$, for $\mathit{p}=1,2,\dots ,n_i$.

7:     $\mathbf{ivalid}\left(\mathbf{ni}\right)$ – Integer arrayOutput

On exit: $\mathbf{ivalid}\left(\mathit{p}\right)$ indicates the final state of integral $\mathit{p}$, for $\mathit{p}=1,2,\dots ,n_i$.

$\mathbf{ivalid}\left(p\right)=0$

The error estimate for integral $p$ was below the requested tolerance.

$\mathbf{ivalid}\left(p\right)=1$

The error estimate for integral $p$ was below the requested tolerance. The final level used was non-isotropic.

$\mathbf{ivalid}\left(p\right)=2$

The error estimate for integral $p$ was above the requested tolerance.

$\mathbf{ivalid}\left(p\right)=3$

The error estimate for integral $p$ was above $\max \left(0.1\left|{\hat{F}}_p\right|,0.01\right)$.

$\mathbf{ivalid}\left(p\right)<0$

You aborted the evaluation before an error estimate could be made.

8:     $\mathbf{iopts}\left(100\right)$ – Integer arrayCommunication Array

9:     $\mathbf{opts}\left(100\right)$ – Real (Kind=nag_wp) arrayCommunication Array

The arrays iopts and opts must not be altered between calls to any of the routines d01esf, d01zkf and d01zlf.

10:   $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace

11:   $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

iuser and ruser are not used by d01esf, but are passed directly to f and may be used to pass information to this routine.

12:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation 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 arguments 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$

The requested accuracy was not achieved for at least one integral.

$\mathbf{ifail}=2$

No accuracy was achieved for at least one integral.

$\mathbf{ifail}=11$

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

$\mathbf{ifail}=21$

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

$\mathbf{ifail}=1001$

Either the option arrays iopts and opts have not been initialized for d01esf, or they have become corrupted.

$\mathbf{ifail}=-1$

Exit requested from f with $\mathbf{iflag}=〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

8.1

Direct Threading

8.2

Parallelization of f

9

Further Comments

10

Example

10.1

Program Text

Program Text (d01esfe.f90)

10.2

Program Data

10.3

Program Results

Program Results (d01esfe.r)

11

Optional Parameters

• Absolute Tolerance
• Index Level
• Maximum Level
• Maximum Nx
• Maximum Quadrature Level
• Minimum Level
• Quadrature Rule
• Relative Tolerance
• Serial Levels
• Summation Precision

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.