NAG Library Function Document

nag_quad_md_sgq_multi_vec (d01esc)

1  Purpose

2  Specification

3  Description

3.1  Comparing Quadrature Over Full and Sparse Grids

3.2  Sparse Grid Quadrature

3.3  Using nag_quad_md_sgq_multi_vec (d01esc)

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}$ – function, supplied by the userExternal 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\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}-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\left(\mathbf{irowix}\left[c\left(i\right)-1\right],i\right)=\mathbf{xs}\left[c\left(i\right)-1\right]\text{,}\\ \\ X\left(k\notin \mathbf{irowix}\left[c\left(i\right)-1\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.

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

The specification of f is:

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}$ – 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}$ – doubleInput

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

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

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

8:    $\mathbf{xs}\left[\mathbf{nntr}\right]$ – const doubleInput

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

9:    $\mathbf{qs}\left[\mathbf{nntr}\right]$ – const IntegerInput

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]$ – doubleOutput

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 nag_quad_md_sgq_multi_vec (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 nag_quad_md_sgq_multi_vec (d01esc) you may allocate memory and initialize these pointers with various quantities for use by f when called from nag_quad_md_sgq_multi_vec (d01esc) (see Section 2.3.1.1 in How to Use the NAG Library and its Documentation).

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

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 \left(m_q,L\right)$ will be used if either $\mathbf{maxdlv}\left[j-1\right]\le 0$ or $\mathbf{maxdlv}\left[j-1\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 $\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]$ – doubleOutput

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]$ – doubleOutput

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]$ – IntegerOutput

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 \left(0.1\left|{\hat{F}}_p\right|,0.01\right)$.

$\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 IntegerCommunication Array

9:    $\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_md_sgq_multi_vec (d01esc), nag_quad_opt_set (d01zkc) and nag_quad_opt_get (d01zlc).

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

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

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

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

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 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

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.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_INVALID_OPTION

Either the option arrays iopts and opts have not been initialized for nag_quad_md_sgq_multi_vec (d01esc), 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_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

Program Text (d01esce.c)

10.2  Program Data

10.3  Program Results

Program Results (d01esce.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.