NAG CL Interface
d01esc (md_​sgq_​multi_​vec)

1 Purpose

2 Specification

3 Description

3.1 Comparing Quadrature Over Full and Sparse Grids

Figure 1: Three-dimensional full (left) and sparse (right) grids, constructed from the $15$ point Gauss–Patterson rule

3.2 Sparse Grid Quadrature

3.3 Using d01esc

4 References

5 Arguments

1: $\mathbf{ni}$ – Integer Input

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

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

2: $\mathbf{ndim}$ – Integer Input

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

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

3: $\mathbf{f}$ – function, supplied by the user External Function

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(d,n_x)$. 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}-1\right],\dots ,\mathbf{icolzp}\left[\mathit{i}\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(\mathbf{irowix}\left[c\left(i\right)-1\right],i)=\mathbf{xs}\left[c\left(i\right)-1\right]\text{,}\\ \\ X(k\notin \mathbf{irowix}\left[c\left(i\right)-1\right],i)=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.

Note: the values returned in icolzp and irowix are one-based.

The specification of f is:

copy

void  f (Integer ni, Integer ndim, Integer nx, double xtr, Integer nntr, const Integer icolzp[], const Integer irowix[], const double xs[], const Integer qs[], double fm[], Integer *iflag, Nag_Comm *comm)

1: $\mathbf{ni}$ – Integer Input

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

2: $\mathbf{ndim}$ – Integer Input

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

3: $\mathbf{nx}$ – Integer Input

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}$ – double Input

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

5: $\mathbf{nntr}$ – Integer Input

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]$ – const Integer Input

On entry: the set $\{\mathbf{icolzp}\left[\mathit{i}-1\right],\dots ,\mathbf{icolzp}\left[\mathit{i}\right]-1\}$ 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[\mathit{dim}\right]$ – const Integer Input

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

8: $\mathbf{xs}\left[\mathit{dim}\right]$ – const double Input

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

9: $\mathbf{qs}\left[\mathit{dim}\right]$ – const Integer Input

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}\times \mathbf{nx}\right]$ – double Output

On exit: $\mathbf{fm}\left[\left(\mathit{i}-1\right)\times \mathbf{ni}+\mathit{p}-1\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}$ – Integer * Input/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[0\right]=x_{\mathrm{tr}}$ and $\mathbf{qs}\left[0\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 d01esc with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_USER_STOP.

12: $\mathbf{comm}$ – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to f.

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling d01esc you may allocate memory and initialize these pointers with various quantities for use by f when called from d01esc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

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

4: $\mathbf{maxdlv}\left[\mathbf{ndim}\right]$ – const Integer Input

On entry: $\mathbf{m}$, the array of maximum levels for each dimension. $\mathbf{maxdlv}\left[\mathit{j}-1\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 (m_q,L)$ will be used if either $\mathbf{maxdlv}\left[j-1\right]\le 0$ or $\mathbf{maxdlv}\left[j-1\right]\ge \min (m_q,L)$ (for details on the default values for $m_q$ and $L$ and on how to change these values see the options $\mathbf{Maximum\; Level}$, $\mathbf{Maximum\; Quadrature\; Level}$ and $\mathbf{Quadrature\; Rule}$).

If $\mathbf{maxdlv}\left[j-1\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-1\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]$ – double Output

On exit: $\mathbf{dinest}\left[\mathit{p}-1\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]$ – double Output

On exit: $\mathbf{errest}\left[\mathit{p}-1\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 Output

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

$\mathbf{ivalid}\left[p-1\right]=0$

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

$\mathbf{ivalid}\left[p-1\right]=1$

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

$\mathbf{ivalid}\left[p-1\right]=2$

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

$\mathbf{ivalid}\left[p-1\right]=3$

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

$\mathbf{ivalid}\left[p-1\right]<0$

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

8: $\mathbf{iopts}\left[100\right]$ – const Integer Communication Array

9: $\mathbf{opts}\left[100\right]$ – const double Communication Array

The arrays iopts and opts MUST NOT be altered between calls to any of the functions d01esc, d01zkc and d01zlc.

10: $\mathbf{comm}$ – Nag_Comm *

The NAG communication argument (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

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

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ACCURACY

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

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_INT

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

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

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 7.5 in the Introduction to the NAG Library CL Interface for further information.

NE_INVALID_OPTION

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

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

NE_TOTAL_PRECISION_LOSS

No accuracy was achieved for at least one integral.

NE_USER_STOP

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

7 Accuracy

8 Parallelism and Performance

8.1 Direct Threading

8.2 Parallelization of f

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

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.