NAG Toolbox: nag_rand_field_fracbm_generate (g05zt)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{ns}$ – int64int32nag_int scalar

The number of steps (points) to be generated in realizations of the increments of the fractional Brownian motion. This must be the same value as supplied to nag_rand_field_1d_predef_setup (g05zn) when calculating the eigenvalues of the embedding matrix.

Note: in the context of fractional Brownian motion, ns represents the number of steps from a zero starting state. Realizations returned in z include this starting state and so $\mathbf{ns}+1$ values are returned for each realization..

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

2:     $\mathrm{s}$ – int64int32nag_int scalar

$S$, the number of realizations of the fractional Brownian motion to simulate.

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

3:     $\mathrm{xmax}$ – double scalar

The upper bound for the interval over which the fractional Brownian motion is to be simulated, as input to nag_rand_field_1d_user_setup (g05zm) or nag_rand_field_1d_predef_setup (g05zn).

Constraint: $\mathbf{xmax}>0.0$.

4:     $\mathrm{h}$ – double scalar

The Hurst parameter, $H$, for the fractional Brownian motion. This must be the same value as supplied to nag_rand_field_1d_predef_setup (g05zn) in $\mathbf{params}\left(1\right)$, when the eigenvalues of the embedding matrix were calculated.

Constraint: $0.0<\mathbf{h}<1.0$.

5:     $\mathrm{lam}\left(\mathbf{m}\right)$ – double array

Contains the square roots of the eigenvalues of the embedding matrix, as returned by nag_rand_field_1d_user_setup (g05zm) or nag_rand_field_1d_predef_setup (g05zn).

Constraint: $\mathbf{lam}\left(\mathit{i}\right)\ge 0$, for $\mathit{i}=1,2,\dots ,\mathbf{m}$.

6:     $\mathrm{rho}$ – double scalar

Indicates the scaling of the covariance matrix, as returned by nag_rand_field_1d_user_setup (g05zm) or nag_rand_field_1d_predef_setup (g05zn).

Constraint: $0.0<\mathbf{rho}\le 1.0$.

7:     $\mathrm{state}\left(:\right)$ – int64int32nag_int array

Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).

Contains information on the selected base generator and its current state.

Optional Input Parameters

1:     $\mathrm{m}$ – int64int32nag_int scalar

Default: the dimension of the array lam.

The size, $M$, of the embedding matrix, as returned by nag_rand_field_1d_user_setup (g05zm) or nag_rand_field_1d_predef_setup (g05zn).

Constraint: $\mathbf{m}\ge \max \left(1,2\left(\mathbf{ns}-1\right)\right)$.

Output Parameters

1:     $\mathrm{state}\left(:\right)$ – int64int32nag_int array

Contains updated information on the state of the generator.

2:     $\mathrm{z}\left(\mathbf{ns}+1,\mathbf{s}\right)$ – double array

Contains the realizations of the fractional Brownian motion, $Z$. The $\mathit{j}$th realization, for the $\mathit{i}$th point $\mathbf{xx}\left(\mathit{i}\right)$, is stored in $\mathbf{z}\left(\mathit{i},\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{s}$ and $\mathit{i}=1,2,\dots ,\mathbf{ns}+1$.

3:     $\mathrm{xx}\left(\mathbf{ns}+1\right)$ – double array

The points at which values of the fractional Brownian motion are output. The first point is always zero, and the subsequent ns points represent the equispaced steps towards the last point, xmax. Note that in nag_rand_field_1d_user_setup (g05zm) and nag_rand_field_1d_predef_setup (g05zn), the returned ns sample points are the mid-points of the grid returned in xx here.

4:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

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

   $\mathbf{ifail}=2$

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

   $\mathbf{ifail}=3$

Constraint: $\mathbf{m}\ge \max \left(1,2\left(\mathbf{ns}-1\right)\right)$.

   $\mathbf{ifail}=4$

Constraint: $\mathbf{xmax}>0.0$.

   $\mathbf{ifail}=5$

Constraint: $0.0<\mathbf{h}<1.0$.

   $\mathbf{ifail}=6$

On entry, at least one element of lam was negative.
Constraint: all elements of lam must be non-negative.

   $\mathbf{ifail}=7$

Constraint: $0.0<\mathbf{rho}\le 1.0$.

   $\mathbf{ifail}=8$

On entry, state vector has been corrupted or not initialized.

   $\mathbf{ifail}=-99$

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

   $\mathbf{ifail}=-399$

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

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g05zt_example

function g05zt_example


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

% Upper bound for interval
xmax = 2;
% Number of sample points
ns   = int64(10);
% Scaling factor, rho = 1.
icorr = int64(2);

% Set fixed problem specifications for simulating fractional Brownian motion
h     = 0.35;
icov1 = int64(14);
np    = int64(2);
xmin  = 0;
var   = 1;
params = [h, xmax/double(ns)];

% Get square roots of the eigenvalues of the embedding matrix
[lam, xx, m, approx, rho, icount, eig, ifail] = ...
  g05zn( ...
         ns, xmin, xmax, var, icov1, params, ...
         'icorr', icorr, 'maxm', int64(2048));

fprintf('\nSize of embedding matrix = %d\n\n', m);

% Display approximation information if approximation used
if approx == 1
  fprintf('Approximation required\n\n');
  fprintf('rho = %10.5f\n', rho);
  fprintf('eig = %10.5f%10.5f%10.5f\n', eig(1:3));
  fprintf('icount = %d\n', icount);
else
  fprintf('Approximation not required\n\n');
end

% Initialize state array
genid = int64(1);
subid = int64(1);
seed  = [int64(14965)];
[state, ifail] = g05kf( ...
                        genid, subid, seed);

% Compute s fractional Brownian Motion realisations.
s    = int64(5);
[state, z, yy, ifail] = g05zt( ...
                               ns, s, xmax, h, lam(1:m), rho, state);

% Display random field results
% Set row labels to mesh points (column label is realisation number).
rlabs = cell(ns+1, 1);
for i=1:ns+1
  rlabs{i} = sprintf('%6.1f', yy(i));
end

% Matrix printing parameters
mtitle = 'Fractional Brownian motion realisations (x coordinate first):';
matrix = 'General';
diag   = 'Non-unit';
fmt    = 'f10.5';
rlabel = 'Character';
clabel = 'Integer';
clabs  = {' '};
ncols  = int64(80);
indent = int64(0);

[ifail] = x04cb( ...
                 matrix, diag, z, fmt, mtitle, rlabel, rlabs, clabel, ...
                 clabs, ncols, indent);

g05zt example results


Size of embedding matrix = 32

Approximation not required

 Fractional Brownian motion realisations (x coordinate first):
              1         2         3         4         5
 0.0    0.00000   0.00000   0.00000   0.00000   0.00000
 0.2   -0.52650  -0.16159  -0.96224  -0.40096   0.65803
 0.4   -1.81085  -0.85811  -1.43661   0.03947   0.99671
 0.6   -1.65690  -0.74802  -0.61733  -0.34685   0.05141
 0.8   -1.72240  -0.14958   0.14996   0.18134   0.26567
 1.0   -2.20349   0.46219   0.70982   0.66405   0.40706
 1.2   -2.38542   0.52085   0.36330   0.31831   0.81515
 1.4   -3.13939   0.68433   0.79826  -0.35408   1.12296
 1.6   -3.54602   0.64413   0.85751  -0.39303   1.14220
 1.8   -4.09082   1.67048   0.06038   0.30181   1.30350
 2.0   -2.97487   1.72275  -0.67253  -0.07439   1.57169