hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_quad_md_sgq_multi_vec (d01es)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

nag_quad_md_sgq_multi_vec (d01es) approximates a vector of definite integrals F over the unit hypercube Ω=0,1d, given the vector of integrands fx.
F = Ω fx dx = 0 1 0 1 0 1 f x1,x2,,xd dx1 dx2 dxd .  
The function uses a sparse grid discretisation, allowing for computationally feasible estimations of integrals of high dimension (dO100).

Syntax

[dinest, errest, ivalid, user, ifail] = d01es(ni, f, maxdlv, iopts, opts, 'ndim', ndim, 'user', user)
[dinest, errest, ivalid, user, ifail] = nag_quad_md_sgq_multi_vec(ni, f, maxdlv, iopts, opts, 'ndim', ndim, 'user', user)

Description

nag_quad_md_sgq_multi_vec (d01es) uses a sparse grid to generate a vector of approximations F^ to a vector of integrals F over the unit hypercube Ω=0,1d, that is,
F^ F = 0,1 d fx dx .  

Comparing Quadrature Over Full and Sparse Grids

Before illustrating the sparse grid construction, it is worth comparing integration over a sparse grid to integration over a full grid.
Given a one-dimensional quadrature rule with N abscissae, which accurately evaluates a polynomial of order PN, a full tensor product over d dimensions, a full grid, may be constructed with Nd multidimensional abscissae. Such a product will accurately integrate a polynomial where the maximum power of any dimension is PN. For example if d=2 and PN=3, such a rule will accurately integrate any polynomial whose highest order term is x13x23. Such a polynomial may be said to have a maximum combined order of PNd, provided no individual dimension contributes a power greater than PN. However, the number of multidimensional abscissae, or points, required increases exponentially with the dimension, rapidly making such a construction unusable.
The sparse grid technique was developed by Smolyak (Smolyak (1963)). In this, multiple one-dimensional quadrature rules of increasing accuracy are combined in such a way as to provide a multidimensional quadrature rule which will accurately evaluate the integral of a polynomial whose maximum order appears as a monomial. Hence a sparse grid construction whose highest level quadrature rule has polynomial order PN will accurately integrate a polynomial whose maximum combined order is also PN. Again taking PN=3, one may, theoretically, accurately integrate a polynomial such as x3+x2y+y3, but not a polynomial such as x3y3+xy. Whilst this has a lower maximum combined order than the full tensor product, the number of abscissae required increases significantly slower than the equivalent full grid, making some classes of integrals of dimension dO100 tractable. Specifically, if a one-dimensional quadrature rule of level  has NO2 abscissae, the corresponding full grid will have O 2 d  multidimensional abscissae, whereas the sparse grid will have O 2 d -1 . Figure 1 demonstrates this using a Gauss–Patterson rule with 15 points in 3 dimensions. The full grid requires 3375 points, whereas the sparse grid only requires 111.
Three-dimensional full (left) and sparse (right) grids, constructed from the 15 point Gauss–Patterson rule
Figure 1: Three-dimensional full (left) and sparse (right) grids, constructed from the 15 point Gauss–Patterson rule

Sparse Grid Quadrature

We now include a brief description of the sparse grid construction, sufficient for the understanding of the use of this routine. For a more detailed analysis, see Gerstner and Griebel (1998).
Consider a one-dimensional n-point quadrature rule of level , Q. The action of this rule on a integrand f is to approximate its definite one-dimensional integral F 1  as,
F 1 = 0 1 fx dx Qf = i=1 n w,i × fx,i ,  
using weights w,i and abscissae x,i, for i=1,2,,n.
Now construct a set of one-dimensional quadrature rules, Q =1,,L , such that the accuracy of the quadrature rule increases with the level number. In this routine we exclusively use quadrature rules which are completely nested, implying that if an abscissae x,k is in level , it is also in level +1. The quantity L denotes some maximum level appropriate to the rules that have been selected.
Now define the action of the tensor product of d rules as,
Q1 Qd f = i1=1 n 1 i d =1 n d w 1 , i1 w d , id f x 1 , i1 ,, x d , id ,  
where the individual level indices j are not necessarily ordered or unique. Each tensor product of d rules defines an action of the quadrature rules Q, =1,2,,d over a subspace, which is given a level = j=1 d j. If all rule levels are equal, this is the full tensor product of that level.
The sparse grid construction of level  can then be declared as the sum of all actions of the quadrature differences Δk = Qk - Qk-1 , over all subspaces having a level at most -d+1,
F d Q d f = level at most ​-d+1 Δk1 Δkd f . (1)
By definition, all subspaces used for level -1 must also be used for level , and as such the difference between the result of all actions over subsequent sparse grid constructions may be used as an error estimate.
Let L be the maximum level allowable in a sparse grid construction. The classical sparse grid construction of =L allows each dimension to support a one-dimensional quadrature rule of level at most L, with such a quadrature rule being used in every dimension at least once. Such a construction lends equal weight to each dimension of the integration, and is termed here ‘isotropic’.
Define the set m=mj,j=1,2,,d, where mj is the maximum quadrature rule allowed in the jth dimension, and mq  to be the maximum quadrature rule used by any dimension. Let a subspace be identified by its quadrature difference levels, k = k1,k2,,kd.
The classical construction may be extended by allowing different dimensions to have different values mj, and by allowing mqL. This creates non-isotropic constructions. These are especially useful in higher dimensions, where some dimensions contribute more than others to the result, as they can drastically reduce the number of function evaluations required.
For example, consider the two-dimensional construction with L=4. The classical isotropic construction would have the following subspaces.
Subspaces generated by a classical sparse grid with L=4.
Level Subspaces
1 1,1 
2 2,1, 1,2 
3 3,1, 2,2, 1,3 
4 4,1, 3,2, 2,3, 1,4 
If the variation in the second dimension is sufficiently accurately described by a quadrature rule of level 2, the contributions of the subspaces 1,3 and 1,4 are probably negligible. Similarly, if the variation in the first dimension is sufficiently accurately described by a quadrature rule of level 3, the subspace 4,1 is probably negligible. Furthermore the subspace 2,3 would also probably have negligible impact, whereas the subspaces 2,2 and 3,2 would not. Hence restricting the first dimension to a maximum level of 3, and the second dimension to a maximum level of 2 would probably give a sufficiently acceptable estimate, and would generate the following subspaces.
Subspaces generated by a non-isotropic sparse grid with L=4, mq=3 and m=3,2.
Level Subspaces
1 1,1 
2 2,1, 1,2 
3 3,1, 2,2 
4 4,1, 3,2 
Taking this to the extreme, if the variation in the first and second dimensions are sufficiently accurately described by a level 2 quadrature rule, restricting the maximum level of both dimensions to 2 would generate the following subspaces.
Subspaces generated by a sparse grid construction with L=4, mq=2 and m=2,2.
Level Subspaces
1 1,1 
2 2,1, 1,2 
3 2,2 
4 None
Hence one subspace is generated at level 3, and no subspaces are generated at level 4. The level 3 subspace 2,2 actually indicates that this is the full grid of level 2.

Using nag_quad_md_sgq_multi_vec (d01es)

nag_quad_md_sgq_multi_vec (d01es) uses optional parameters, supplied in the option arrays iopts and opts. Before calling nag_quad_md_sgq_multi_vec (d01es), these option arrays must be initialized using nag_quad_opt_set (d01zk). Once initialized, the required options may be set and queried using nag_quad_opt_set (d01zk) and nag_quad_opt_get (d01zl) respectively. A complete list of the options available may be found in Optional Parameters.
You may control the maximum level required, L, using the optional parameter Maximum Level. Furthermore, you may control the first level at which the error comparison will take place using the optional parameter Minimum Level, allowing for the forced evaluation of a predetermined number of levels before the routine attempts to complete. Completion is flagged when the error estimate is sufficiently small:
F^ d k - F^ d k-1 maxεa, εr × F^ d k ,  
where εa and εr are the absolute and relative error tolerances, respectively, and kL is the highest level at which computation was performed. The tolerances εa and εr can be controlled by setting the optional parameters Absolute Tolerance and Relative Tolerance.
Owing to the interlacing nature of the quadrature rules used herein, abscissae x required in lower level subspaces will also appear in higher-level subspaces. This allows for calculations which will be repeated later to be stored and re-used. However, this is naturally at the expense of memory. It may also be at the expense of computational time, depending on the complexity of the integrands, as the lookup time for a given value is (at worst) Od. Furthermore, as the sparse grid level increases, fewer subsequent levels will require values from the current level. You may control the number of levels for which values are stored by setting the optional parameter Index Level.
Two different sets of interlacing quadrature rules are selectable using the optional parameter Quadrature Rule: Gauss–Patterson and Clenshaw–Curtis. Gauss–Patterson rules offer greater polynomial accuracy, whereas Clenshaw–Curtis rules are often effective for oscillatory integrands. Clenshaw–Curtis rules require function values to be evaluated on the boundary of the hypercube, whereas Gauss–Patterson rules do not. Both of these rules use precomputed weights, and as such there is an effective limit on mq; see the description of the optional parameter Quadrature Rule. The value of mq is returned by the queriable optional parameter Maximum Quadrature Level.
nag_quad_md_sgq_multi_vec (d01es) also allows for non-isotropic sparse grids to be constructed. This is done by appropriately setting the array maxdlv. It should be emphasised that a non-isometric construction should only be used if the integrands behave in a suitable way. For example, they may decay toward zero as the lesser dimensions approach their bounds of Ω. It should also be noted that setting maxdlvk=1 will not reduce the dimension of the integrals, it will simply indicate that only one point in dimension k should be used. It is also advisable to approximate the integrals several times, once with an isometric construction of some level, and then with a non-isometric construction with higher levels in various dimensions. If the difference between the solutions is significantly more than the returned error estimates, the assumptions of dimensional importance are probably incorrect.
The abscissae in each subspace are generally expressible in a sparse manner, because many of the elements of each abscissa will in fact be the centre point of the dimension, which is termed here the ‘trivial’ element. In this function the trivial element is always returned as 0.5 owing to the restriction to the 0,1  hypercube. As such, the function f returns the abscissae in Compressed Column Storage (CCS) format (see the F11 Chapter Introduction). This has particular advantages when using accelerator hardware to evaluate the required functions, as much less data must be forwarded. It also, potentially, allows for calculations to be computed faster, as any sub-calculations dependent upon the trivial value may be potentially re-used. See the example in Example.

References

Caflisch R E, Morokoff W and Owen A B (1997) Valuation of mortgage backed securities using Brownian bridges to reduce effective dimension Journal of Computational Finance 1 27–46
Gerstner T and Griebel M (1998) Numerical integration using sparse grids Numerical Algorithms 18 209–232
Smolyak S A (1963) Quadrature and interpolation formulas for tensor products of certain classes of functions Dokl. Akad. Nauk SSSR 4 240–243

Parameters

Compulsory Input Parameters

1:     ni int64int32nag_int scalar
ni, the number of integrands.
Constraint: ni1.
2:     f – function handle or string containing name of m-file
f must return the value of the integrands fj at a set of nx d-dimensional points xi, implicitly supplied as columns of a matrix Xd,nx. If X was supplied explicitly you would find that most of the elements attain the same value, xtr; the larger the number of dimensions, the greater the proportion of elements of X would be equal to xtr. So, X is effectively a sparse matrix, except that the ‘zero’ elements are replaced by elements that are all equal to the value xtr. 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 xk,i of X, for k=1,2,,d, are either trivially valued, in which case xk,i=xtr, or are non-trivially valued. For point i, the non-trivial row indices and corresponding abscissae values are supplied in elements ci=icolzpi,,icolzpi+1-1, for i=1,2,,nx, of the arrays irowix and xs, respectively. Hence the ith column of the matrix X is retrievable as
X irowix ci ,i = xs ci , X k irowix ci ,i = xtr .  
An equivalent integer valued matrix Q is also implicitly provided. This contains the unique indices qk,i of the underlying one-dimensional quadrature rule corresponding to the individual abscissae xk,i. For trivial abscissae, the implicit index qk,i=1. Q is supplied in the same CCS format as X, with the non-trivial values supplied in qs.
[fm, iflag, user] = f(ni, ndim, nx, xtr, nntr, icolzp, irowix, xs, qs, iflag, user)

Input Parameters

1:     ni int64int32nag_int scalar
ni, the number of integrands.
2:     ndim int64int32nag_int scalar
d, the number of dimensions.
3:     nx int64int32nag_int scalar
nx, the number of points xi, corresponding to the number of columns of X, at which the set of integrands must be evaluated.
4:     xtr – double scalar
xtr, the value of the trivial elements of X.
5:     nntr int64int32nag_int scalar
If iflag>0, the number of non-trivial elements of X.
If iflag=0, the total number of abscissae from the underlying one-dimensional quadrature.
6:     icolzpnx+1 int64int32nag_int array
The set icolzpi,,icolzpi+1 - 1 contains the indices of irowix and xs corresponding to the non-trivial elements of column i of X and hence of the point xi, for i=1,2,,nx.
7:     irowixnntr int64int32nag_int array
The row indices corresponding to the non-trivial elements of X.
8:     xsnntr – double array
xk,ixtr, the non-trivial entries of X.
9:     qsnntr int64int32nag_int array
qk,i1, the indices of the underlying quadrature rules corresponding to xk,ixtr.
10:   iflag int64int32nag_int scalar
If iflag=0, this is the first call to f. nx=1, and the entire point x1 will satisfy xk,1=xtr, for k=1,2,,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 xs1 = xtr  and qs1 = 1 . This will always be called in serial.
In subsequent calls to f, iflag=1. Subsequent calls may be made from within an OpenMP parallel region. See Parallelism and Performance for details.
11:   user – Any MATLAB object
f is called from nag_quad_md_sgq_multi_vec (d01es) with the object supplied to nag_quad_md_sgq_multi_vec (d01es).

Output Parameters

1:     fmninx – double array
fmpi = fp xi , for i=1,2,,nx and p=1,2,,ni.
2:     iflag int64int32nag_int scalar
Set iflag<0 if you wish to force an immediate exit from nag_quad_md_sgq_multi_vec (d01es) with ifail=-1.
3:     user – Any MATLAB object
3:     maxdlvndim int64int32nag_int array
Suggested value: maxdlvj=0 for all j=1,2,,d.
m, the array of maximum levels for each dimension. maxdlvj, for j=1,2,,d, contains mj, the maximum level of quadrature rule dimension j will support.
The default value, minmq,L  will be used if either maxdlvj0 or maxdlvjminmq,L (for details on the default values for mq and L and on how to change these values see the options Maximum Level, Maximum Quadrature Level and Quadrature Rule).
If maxdlvj=1 for all j, only one evaluation will be performed, and as such no error estimation will be possible.
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.
4:     iopts100 int64int32nag_int array
5:     opts100 – double array
The arrays iopts and opts must not be altered between calls to any of the functions nag_quad_md_sgq_multi_vec (d01es), nag_quad_opt_set (d01zk) and nag_quad_opt_get (d01zl).

Optional Input Parameters

1:     ndim int64int32nag_int scalar
Default: the dimension of the array maxdlv.
d, the number of dimensions.
Constraint: ndim1.
2:     user – Any MATLAB object
user is not used by nag_quad_md_sgq_multi_vec (d01es), but is passed to f. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

Output Parameters

1:     dinestni – double array
dinestp contains the final estimate F^p of the definite integral Fp, for p=1,2,,ni.
2:     errestni – double array
errestp contains the final error estimate Ep of the definite integral Fp, for p=1,2,,ni.
3:     ivalidni int64int32nag_int array
ivalidp indicates the final state of integral p, for p=1,2,,ni.
ivalidp=0
The error estimate for integral p was below the requested tolerance.
ivalidp=1
The error estimate for integral p was below the requested tolerance. The final level used was non-isotropic.
ivalidp=2
The error estimate for integral p was above the requested tolerance.
ivalidp=3
The error estimate for integral p was above max0.1F^p,0.01.
ivalidp<0
You aborted the evaluation before an error estimate could be made.
4:     user – Any MATLAB object
5:     ifail int64int32nag_int scalar
ifail=0 unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Note: nag_quad_md_sgq_multi_vec (d01es) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
   ifail=1
The requested accuracy was not achieved for at least one integral.
   ifail=2
No accuracy was achieved for at least one integral.
   ifail=11
Constraint: ni1.
   ifail=21
Constraint: ndim1.
   ifail=1001
Either the option arrays iopts and opts have not been initialized for nag_quad_md_sgq_multi_vec (d01es), or they have become corrupted.
   ifail=-1
Exit requested from f with iflag=_.
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

For each integral p, an error estimate Ep is returned, where,
Ep = F^ p k - F^ p k-1 F^p - Fp ,  
where k L is the highest level at which computation was performed.

Further Comments

Not applicable.

Example

The example program evaluates an estimate to the set of integrals
F = Ω sin1+x sinni+x logx d x  
where x = j=1 d jxj.
function d01es_example


fprintf('d01es example results\n\n');

% Evaluate an estimate to the set of integrals of sin(n+|x|)log(|x|),
% with |x| = sum(j*x(j)), for n=1:10 on a hypercube of dimension 4.

ni = int64(10);
d  = int64(4);

% Initialize d01es and set options
iopts = zeros(100,1,'int64');
opts  = zeros(100,1);
[iopts, opts, ifail] = d01zk('Initialize = d01es', iopts, opts);
[iopts, opts, ifail] = d01zk('Absolute Tolerance = 0.0', iopts, opts);
[iopts, opts, ifail] = d01zk('Relative Tolerance = 1.0e-3', iopts, opts);
[iopts, opts, ifail] = d01zk('Maximum Level = 6', iopts, opts);
[iopts, opts, ifail] = d01zk('Index Level = 5', iopts, opts);

maxdlv = zeros(d,1,'int64');
[dinest, errest, ivalid, user, ifail] = d01es(ni, @f, maxdlv, iopts, opts);

fprintf('%10s%13s%13s%14s\n','integrand', 'integral','error','state');
for i = 1:ni
  fprintf('%7d%16.6f%15.2e%10d\n',i,dinest(i),errest(i),ivalid(i));
end



function [fm, iflag, user] = ...
         f(ni, ndim, nx, xtr, nntr, icolzp, irowix, xs, qs, iflag, user)

  fm = zeros(ni,nx);

  % Decompose |x| as |x_{tr}| + |(x_{non-tr} - x_{tr})|:
  % Here is |x_{tr}|:
  s_tr = xtr*double(ndim*(ndim+1))/2;

  for i = 1:nx
    i1 = icolzp(i);
    i2 = icolzp(i+1)-1;
    
    % Here is |(x_{non-tr} - x_{tr})|:
    s_ntr = sum(double(irowix(i1:i2)).*(xs(i1:i2)-xtr));
    
    for j = 1:ni
      fm(j,i) = sin(double(j)+s_ntr+s_tr)*log(s_ntr+s_tr);
    end
  end
d01es example results

 integrand     integral        error         state
      1        0.038352       2.40e-05         0
      2        0.401177       1.70e-05         0
      3        0.395161       5.66e-06         0
      4        0.025836       2.31e-05         0
      5       -0.367242       1.93e-05         0
      6       -0.422680       2.25e-06         0
      7       -0.089508       2.17e-05         0
      8        0.325958       2.12e-05         0
      9        0.441739       1.21e-06         0
     10        0.151388       1.99e-05         0

Optional Parameters

Several optional parameters in nag_quad_md_sgq_multi_vec (d01es) control aspects of the algorithm, methodology used, logic or output. Their values are contained in the arrays iopts and opts; these must be initialized before calling nag_quad_md_sgq_multi_vec (d01es) by first calling nag_quad_opt_set (d01zk) with optstr set to "Initialize = nag_quad_md_sgq_multi_vec (d01es)".
Each optional parameter has an associated default value; to set any of them to a non-default value, or to reset any of them to the default value, use nag_quad_opt_set (d01zk). The current value of an optional parameter can be queried using nag_quad_opt_get (d01zl).
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in Description of the s.

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
The following symbol represent various machine constants:
All options accept the value ‘DEFAULT’ in order to return single options to their default states.
Keywords and character values are case insensitive, however they must be separated by at least one space.
Queriable options will return the appropriate value when queried by calling nag_quad_opt_get (d01zl). They will have no effect if passed to nag_quad_opt_set (d01zk).
For nag_quad_md_sgq_multi_vec (d01es) the maximum length of the argument cvalue used by nag_quad_opt_get (d01zl) is 15.
Absolute Tolerance  r
Default =ε
r=εa, the absolute tolerance required.
Index Level  i
Default =4
The maximum level at which function values are stored for later use. Larger values use increasingly more memory, and require more time to access specific elements. Lower levels result in more repeated computation.
Constraint: i1.
Maximum Level  i
Default =5
i=L, the maximum number of levels to evaluate.
Constraint: 1<i20.
Note: the maximum allowable level in any single dimension, mq, is governed by the Quadrature Rule selected. If a value greater than mq is set, only a subset of subspaces from higher levels will be used. Should this subset be empty for a given level, computation will consider the preceding level to be the maximum level and will terminate.
Maximum Nx  i
Default =128
i=maxnx, the maximum number of points to evaluate in a single call to f.
Constraint: 1i16384.
Maximum Quadrature Level  i
Queriable only
i=mq, the maximum level of the underlying one-dimensional quadrature rule (see Quadrature Rule).
Minimum Level  i
Default =2
The minimum number of levels which must be evaluated before an error estimate is used to determine convergence.
Constraint: i>1.
Note: if the minimum level is greater than the maximum computable level, the maximum level will be used.
Quadrature Rule  a
Default =Gauss–Patterson
The underlying one-dimensional quadrature rule to be used in the construction. Open rules do not require evaluations at boundaries.
Quadrature Rule=Gauss–Patterson or GP
The interlacing Gauss–Patterson rules. Level  uses 2-1 abscissae. All levels are open. These rules provide high order accuracy. mq=9.
Quadrature Rule=Clenshaw–Curtis or CC
The interlacing Clenshaw–Curtis rules. Level  uses 2-1+1 abscissae. All levels above level 1 are closed. mq=12.
Relative Tolerance  r
Default =ε
r=εa, the relative tolerance required.
Summation Precision  a
Default =HIGHER
Determines whether nag_quad_md_sgq_multi_vec (d01es) uses working precision or higher-than-working precision to accumulate the actions over subspaces.
Summation Precision=HIGHER or H
Higher-than-working precision is used to accumulate the action over a subspace, and for the accumulation of all such actions. This is more expensive computationally, although this is probably negligible in comparison to the cost of evaluating the integrands and the overall runtime. This significantly reduces variation in the result when changing the number of threads.
Summation Precision=WORKING or W
Working precision is used to accumulate the actions over subspaces. This may provide some speedup, particularly if ni or nt is large. The results of parallel simulations will however be more prone to variation.
Note: the following option is relevant only to multithreaded implementations of the NAG Library..
Serial Levels  i
Default =1
i=sl, the number of levels to be evaluated in serial before initializing parallelization. For relatively trivial integrands, this may need to be set greater than the default to reduce parallel overhead.

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015