Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_rand_quasi_uniform (g05ym)

## Purpose

nag_rand_quasi_uniform (g05ym) generates a uniformly distributed low-discrepancy sequence as proposed by Sobol, Faure or Niederreiter. It must be preceded by a call to one of the initialization functions nag_rand_quasi_init (g05yl) or nag_rand_quasi_init_scrambled (g05yn).

## Syntax

[quas, iref, ifail] = g05ym(n, iref, 'rcord', rcord)
[quas, iref, ifail] = nag_rand_quasi_uniform(n, iref, 'rcord', rcord)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 24: rcord was made optional

## Description

Low discrepancy (quasi-random) sequences are used in numerical integration, simulation and optimization. Like pseudorandom numbers they are uniformly distributed but they are not statistically independent, rather they are designed to give more even distribution in multidimensional space (uniformity). Therefore they are often more efficient than pseudorandom numbers in multidimensional Monte–Carlo methods.
nag_rand_quasi_uniform (g05ym) generates a set of points ${x}^{1},{x}^{2},\dots ,{x}^{N}$ with high uniformity in the $S$-dimensional unit cube ${I}^{S}={\left[0,1\right]}^{S}$.
Let $G$ be a subset of ${I}^{S}$ and define the counting function ${S}_{N}\left(G\right)$ as the number of points ${x}^{i}\in G$. For each $x=\left({x}_{1},{x}_{2},\dots ,{x}_{S}\right)\in {I}^{S}$, let ${G}_{x}$ be the rectangular $S$-dimensional region
 $G x = 0, x 1 × 0, x 2 ×⋯× 0, x S$
with volume ${x}_{1},{x}_{2},\dots ,{x}_{S}$. Then one measure of the uniformity of the points ${x}^{1},{x}^{2},\dots ,{x}^{N}$ is the discrepancy:
 $DN* x1,x2,…,xN = sup x∈IS SN Gx - N x1 , x2 , … , xS .$
which has the form
 $DN*x1,x2,…,xN≤CSlog⁡NS+Olog⁡NS-1 for all N≥2.$
The principal aim in the construction of low-discrepancy sequences is to find sequences of points in ${I}^{S}$ with a bound of this form where the constant ${C}_{S}$ is as small as possible.
The type of low-discrepancy sequence generated by nag_rand_quasi_uniform (g05ym) depends on the initialization function called and can include those proposed by Sobol, Faure or Niederreiter. If the initialization function nag_rand_quasi_init_scrambled (g05yn) was used then the sequence will be scrambled (see Description in nag_rand_quasi_init_scrambled (g05yn) for details).

## References

Bratley P and Fox B L (1988) Algorithm 659: implementing Sobol's quasirandom sequence generator ACM Trans. Math. Software 14(1) 88–100
Fox B L (1986) Algorithm 647: implementation and relative efficiency of quasirandom sequence generators ACM Trans. Math. Software 12(4) 362–376

## Parameters

Note: the following variables are used in the parameter descriptions:

### Compulsory Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
The number of quasi-random numbers required.
Constraint: ${\mathbf{n}}\ge 0$ and ${\mathbf{n}}+\text{previous number of generated values}\le {2}^{31}-1$.
2:     $\mathrm{iref}\left(\mathit{liref}\right)$int64int32nag_int array
Contains information on the current state of the sequence.

### Optional Input Parameters

1:     $\mathrm{rcord}$int64int32nag_int scalar
Default: $1$
The order in which the generated values are returned.
Constraint: ${\mathbf{rcord}}=1$ or $2$.

### Output Parameters

1:     $\mathrm{quas}\left(\mathit{ldquas},\mathit{tdquas}\right)$ – double array
Contains the n quasi-random numbers of dimension idim.
If ${\mathbf{rcord}}=1$, ${\mathbf{quas}}\left(i,j\right)$ holds the $j$th value for the $i$th dimension.
If ${\mathbf{rcord}}=2$, ${\mathbf{quas}}\left(i,j\right)$ holds the $i$th value for the $j$th dimension.
2:     $\mathrm{iref}\left(\mathit{liref}\right)$int64int32nag_int array
Contains updated information on the state of the sequence.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
Constraint: ${\mathbf{n}}\ge 0$.
On entry, value of n would result in too many calls to the generator.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{rcord}}=1$ or $2$.
${\mathbf{ifail}}=4$
Constraint: if ${\mathbf{rcord}}=1$, $\mathit{ldquas}\ge \mathit{idim}$.
Constraint: if ${\mathbf{rcord}}=2$, $\mathit{ldquas}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=5$
On entry, iref has either not been initialized or has been corrupted.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

None.

## Example

This example calls nag_rand_quasi_init (g05yl) and nag_rand_quasi_uniform (g05ym) to estimate the value of the integral
 $∫01 ⋯ ∫01 ∏ i=1 s 4xi-2 dx1, dx2, …, dxs = 1 .$
In this example the number of dimensions $S$ is set to $8$.
```function g05ym_example

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

% Initialize the Sobol generator, skipping some variates
iskip = int64(1000);
idim  = int64(8);
genid = int64(1);
% Initialize the Sobol generator
[iref, ifail] = g05yl( ...
genid,idim,iskip);

% Number of variates
n = int64(200);

% Generate N quasi-random variates
[quas, iref, ifail] = g05ym( ...
n, iref);

% Evaluate the function, and sum
p(1:n) = prod(abs(4*quas(1:idim,:)-2));
fsum = sum(p);

% Convert sum to mean value
vsbl = fsum/double(n);
fprintf('Value of integral = %8.4f\n\n', vsbl);
fprintf('First 10 variates\n');
for i = 1:10
fprintf(' %3d', i);
fprintf(' %7.4f', quas(1:idim,i));
fprintf('\n');
end

```
```g05ym example results

Value of integral =   1.0410

First 10 variates
1  0.7197  0.5967  0.0186  0.1768  0.7803  0.4072  0.5459  0.3994
2  0.9697  0.3467  0.7686  0.9268  0.5303  0.1572  0.2959  0.1494
3  0.4697  0.8467  0.2686  0.4268  0.0303  0.6572  0.7959  0.6494
4  0.3447  0.4717  0.1436  0.3018  0.1553  0.7822  0.4209  0.0244
5  0.8447  0.9717  0.6436  0.8018  0.6553  0.2822  0.9209  0.5244
6  0.5947  0.2217  0.3936  0.0518  0.9053  0.0322  0.1709  0.7744
7  0.0947  0.7217  0.8936  0.5518  0.4053  0.5322  0.6709  0.2744
8  0.0635  0.1904  0.0498  0.4580  0.6240  0.2510  0.9521  0.8057
9  0.5635  0.6904  0.5498  0.9580  0.1240  0.7510  0.4521  0.3057
10  0.8135  0.4404  0.2998  0.2080  0.3740  0.5010  0.7021  0.0557
```