NAG Toolbox: nag_stat_moments_ratio_quad_forms (g01nb)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{a}\left(\mathit{lda},\mathbf{n}\right)$ – double array

lda, the first dimension of the array, must satisfy the constraint $\mathit{lda}\ge \mathbf{n}$.

The $n$ by $n$ symmetric matrix $A$. Only the lower triangle is referenced.

2:     $\mathrm{b}\left(\mathit{ldb},\mathbf{n}\right)$ – double array

ldb, the first dimension of the array, must satisfy the constraint $\mathit{ldb}\ge \mathbf{n}$.

The $n$ by $n$ positive semidefinite symmetric matrix $B$. Only the lower triangle is referenced.

Constraint: the matrix $B$ must be positive semidefinite.

3:     $\mathrm{sigma}\left(\mathit{ldsig},\mathbf{n}\right)$ – double array

ldsig, the first dimension of the array, must satisfy the constraint $\mathit{ldsig}\ge \mathbf{n}$.

The $n$ by $n$ variance-covariance matrix $\Sigma$. Only the lower triangle is referenced.

Constraint: the matrix $\Sigma$ must be positive definite.

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

The first moment to be computed, $l_1$.

Constraint: $0<\mathbf{l1}\le \mathbf{l2}$.

5:     $\mathrm{l2}$ – int64int32nag_int scalar

The last moment to be computed, $l_2$.

Constraint: $\mathbf{l1}\le \mathbf{l2}\le 12$.

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

The relative accuracy required for the moments, this value is also used in the checks for the existence of the moments.

If $\mathbf{eps}=0.0$, a value of $\sqrt{\epsilon }$ where $\epsilon$ is the machine precision used.

Constraint: $\mathbf{eps}=0.0$ or $\mathbf{eps}\ge \mathit{machine precision}$.

Optional Input Parameters

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

Default: the first dimension of the arrays a, b, sigma and the second dimension of the arrays a, b, sigma. (An error is raised if these dimensions are not equal.)

$n$, the dimension of the quadratic form.

Constraint: $\mathbf{n}>1$.

2:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double array

The first dimension, $\mathit{ldc}$, of the array c must satisfy

• if $\mathit{case}=\text{'Q'}$, $\mathit{ldc}\ge \mathbf{n}$;
• otherwise $\mathit{ldc}\ge 1$.

The second dimension of the array c must be at least $\mathbf{n}$ if $\mathit{case}=\text{'Q'}$, and at least $1$ otherwise.

If $\mathit{case}=\text{'Q'}$, c must contain the $n$ by $n$ symmetric matrix $C$; only the lower triangle is referenced.

If $\mathit{case}\ne \text{'Q'}$, c is not referenced.

3:     $\mathrm{ela}\left(:\right)$ – double array

The dimension of the array ela must be at least $\mathbf{n}$ if $\mathit{case}=\text{'L'}$, and at least $1$ otherwise

If $\mathit{case}=\text{'L'}$, ela must contain the vector $a$ of length $n$, otherwise ela is not referenced.

4:     $\mathrm{emu}\left(:\right)$ – double array

The dimension of the array emu must be at least $\mathbf{n}$ if $\mathit{mean}=\text{'M'}$, and at least $1$ otherwise

If $\mathit{mean}=\text{'M'}$, emu must contain the $n$ elements of the vector $\mu$.

If $\mathit{mean}=\text{'Z'}$, emu is not referenced.

Output Parameters

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

The highest moment computed, $l_{\mathrm{MAX}}$. This will be $l_2$ if $\mathbf{ifail}=\mathbf{0}$ on exit.

2:     $\mathrm{rmom}\left(\mathbf{l2}-\mathbf{l1}+1\right)$ – double array

The $l_1$ to $l_{\mathrm{MAX}}$ moments.

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

The estimated maximum absolute error in any computed moment.

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

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{ifail}=1$

On entry,	$\mathbf{n}\le 1$,
or	$\mathit{lda}<\mathbf{n}$,
or	$\mathit{ldb}<\mathbf{n}$,
or	$\mathit{ldsig}<\mathbf{n}$,
or	$\mathit{case}=\text{'Q'}$ and $\mathit{ldc}<\mathbf{n}$,
or	$\mathit{case}\ne \text{'Q'}$ and $\mathit{ldc}<1$,
or	$\mathbf{l1}<1$,
or	$\mathbf{l1}>\mathbf{l2}$,
or	$\mathbf{l2}>12$,
or	$\mathit{case}\ne \text{'R'}$, $\text{'L'}$ or $\text{'Q'}$,
or	$\mathit{mean}\ne \text{'M'}$ or $\text{'Z'}$,
or	$\mathbf{eps}\ne 0.0$ and $\mathbf{eps}<\mathit{machine precision}$.

   $\mathbf{ifail}=2$

On entry,	$\Sigma$ is not positive definite,
or	$\mathbf{b}$ is not positive semidefinite or is null.

   $\mathbf{ifail}=3$

None of the required moments can be computed.

   $\mathbf{ifail}=4$

The matrix $L^{\mathrm{T}}BL$ is not positive semidefinite or is null.

   $\mathbf{ifail}=5$

The computation to compute the eigenvalues required in the calculation of moments has failed to converge: this is an unlikely error exit.

W  $\mathbf{ifail}=6$

Only some of the required moments have been computed, the highest is given by lmax.

W  $\mathbf{ifail}=7$

The required accuracy has not been achieved in the integration. An estimate of the accuracy is returned in abserr.

   $\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: g01nb_example

function g01nb_example


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

% Problem parameters
n    = 10;
l1   = int64(1);
l2   = int64(3);
beta = 0.8;
y0   = 1.0;

% Setup a, b, emu, sigma for simple autoregression
a = zeros(n, n);
b = zeros(n, n);
a(2:n,  1:n-1) = 0.5*eye(n-1);
b(1:n-1,1:n-1) = eye(n-1);

emu = zeros(n,1);
for j=1:n
  emu(j) = y0*beta^j;
end
sigma = zeros(n,n);
sigma(1,1) = 1;
for j = 2:n
  sigma(j,j) = sigma(j-1,j-1)*beta^2 + 1;
end
for i = 1:n
  s = sigma(i,i);
  for j = i+1:n
    sigma(j,i) = s*beta^(j-i);
  end
end

% Compute moments
epsilon = 0;
[lmax, rmom, abserr, ifail] = ...
  g01nb( ...
         a, b, sigma, l1, l2, epsilon, 'emu', emu);

% Display results
fprintf(' n = %3d, beta = %6.3f, y0 = %6.3f\n\n', n, beta, y0);
fprintf('      Moments\n\n');
ival = double([l1:lmax]');
fprintf('%3d%12.4e\n',[ival rmom]');

g01nb example results

 n =  10, beta =  0.800, y0 =  1.000

      Moments

  1  6.8204e-01
  2  5.3569e-01
  3  4.4269e-01