NAG Toolbox: nag_eigen_real_triang_svd (f02wu)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

The first dimension of the array a must be at least $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array a must be at least $\max \left(1,\mathbf{n}\right)$.

The leading $n$ by $n$ upper triangular part of the array a must contain the upper triangular matrix $R$.

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

The first dimension, $\mathit{ldb}$, of the array b must satisfy

• if $\mathbf{ncolb}>0$, $\mathit{ldb}\ge \max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldb}\ge 1$.

The second dimension of the array b must be at least $\max \left(1,\mathbf{ncolb}\right)$.

With $\mathbf{ncolb}>0$, the leading $n$ by $\mathit{ncolb}$ part of the array b must contain the matrix to be transformed.

3:     $\mathrm{wantq}$ – logical scalar

Must be true if the matrix $Q$ is required.

If $\mathbf{wantq}=\mathit{false}$, the array q is not referenced.

4:     $\mathrm{wantp}$ – logical scalar

Must be true if the matrix $P^{\mathrm{T}}$ is required, in which case $P^{\mathrm{T}}$ is overwritten on the array a, otherwise wantp must be false.

Optional Input Parameters

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

Default: the first dimension of the array a and the second dimension of the array a.

$n$, the order of the matrix $R$.

If $\mathbf{n}=0$, an immediate return is effected.

Constraint: $\mathbf{n}\ge 0$.

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

Default: the second dimension of the array b.

$\mathit{ncolb}$, the number of columns of the matrix $B$.

If $\mathbf{ncolb}=0$, the array b is not referenced.

Constraint: $\mathbf{ncolb}\ge 0$.

Output Parameters

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

The first dimension of the array a will be $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array a will be $\max \left(1,\mathbf{n}\right)$.

If $\mathbf{wantp}=\mathit{true}$, the $n$ by $n$ part of a will contain the $n$ by $n$ orthogonal matrix $P^{\mathrm{T}}$, otherwise the $n$ by $n$ upper triangular part of a is used as internal workspace, but the strictly lower triangular part of a is not referenced.

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

The first dimension, $\mathit{ldb}$, of the array b will be

• if $\mathbf{ncolb}>0$, $\mathit{ldb}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldb}=1$.

The second dimension of the array b will be $\max \left(1,\mathbf{ncolb}\right)$.

The leading $n$ by $\mathit{ncolb}$ part of the array b stores the matrix $Q^{\mathrm{T}}B$.

3:     $\mathrm{q}\left(\mathit{ldq},:\right)$ – double array

The first dimension, $\mathit{ldq}$, of the array q will be

• if $\mathbf{wantq}=\mathit{true}$, $\mathit{ldq}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldq}=1$.

The second dimension of the array q will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{wantq}=\mathit{true}$ and $1$ otherwise.

With $\mathbf{wantq}=\mathit{true}$, the leading $n$ by $n$ part of the array q will contain the orthogonal matrix $Q$. Otherwise the array q is not referenced.

4:     $\mathrm{sv}\left(\mathbf{n}\right)$ – double array

The array sv will contain the $n$ diagonal elements of the matrix $S$.

5:     $\mathrm{work}\left(:\right)$ – double array

The dimension of the array work will be $\max \left(1,2\times \left(\mathbf{n}-1\right)\right)$ if $\mathbf{ncolb}=0$ and $\mathbf{wantq}=\mathit{false}$ and $\mathbf{wantp}=\mathit{false}$, $\max \left(1,3\times \left(\mathbf{n}-1\right)\right)$ if ($\mathbf{ncolb}=0$ and $\mathbf{wantq}=\mathit{false}$ and $\mathbf{wantp}=\mathit{true}$) or ($\mathbf{wantp}=\mathit{false}$ and ($\mathbf{ncolb}>0$ or $\mathbf{wantq}=\mathit{true}$)) and $\max \left(1,5\times \left(\mathbf{n}-1\right)\right)$ otherwise

$\mathbf{work}\left(\mathbf{n}\right)$ contains the total number of iterations taken by the $QR$ algorithm.

The rest of the array is used as internal workspace.

6:     $\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}<0$,
or	$\mathit{lda}<\mathbf{n}$,
or	$\mathbf{ncolb}<0$,
or	$\mathit{ldb}<\mathbf{n}$ and $\mathbf{ncolb}>0$,
or	$\mathit{ldq}<\mathbf{n}$ and $\mathbf{wantq}=\mathit{true}$.

W  $\mathbf{ifail}>0$

The $QR$ algorithm has failed to converge in $50\times \mathbf{n}$ iterations. In this case $\mathbf{sv}\left(1\right),\mathbf{sv}\left(2\right),\dots ,\mathbf{sv}\left(\mathbf{ifail}\right)$ may not have been found correctly and the remaining singular values may not be the smallest. The matrix $R$ will nevertheless have been factorized as $R=QE{P}^{\mathrm{T}}$, where $E$ is a bidiagonal matrix with $\mathbf{sv}\left(1\right),\mathbf{sv}\left(2\right),\dots ,\mathbf{sv}\left(n\right)$ as the diagonal elements and $\mathbf{work}\left(1\right),\mathbf{work}\left(2\right),\dots ,\mathbf{work}\left(n-1\right)$ as the superdiagonal elements.

This failure is not likely to occur.

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

tol = eps;
irank = 1;
while (irank <= numel(sv) && sv(irank) >= tol*sv(1) )
  irank = irank + 1;
end

Example

Open in the MATLAB editor: f02wu_example

function f02wu_example


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

% SVD of upper triangular A
a = [-4, -2, -3;
      0, -3, -2;
      0,  0, -4];

b = [-1; -1; -1];
wantq = true;
wantp = true;
[a, b, q, sv, work, ifail] = f02wu( ...
                                    a, b, wantq, wantp);

fprintf('Singular value decomposition of A\n\n');

disp('Singular values');
disp(sv');
disp('Left-hand singular vectors, by column');
disp(q);
disp('Right-hand singular vectors, by column');
disp(a');
disp('Vector Q''*B');
disp(b');

f02wu example results

Singular value decomposition of A

Singular values
    6.5616    3.0000    2.4384

Left-hand singular vectors, by column
   -0.7699    0.5883   -0.2471
   -0.4324   -0.1961    0.8801
   -0.4694   -0.7845   -0.4054

Right-hand singular vectors, by column
    0.4694   -0.7845    0.4054
    0.4324   -0.1961   -0.8801
    0.7699    0.5883    0.2471

Vector Q'*B
    1.6716    0.3922   -0.2276