NAG Toolbox: nag_lapack_dgesvd (f08kb)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{jobu}$ – string (length ≥ 1)

Specifies options for computing all or part of the matrix $U$.

$\mathbf{jobu}=\text{'A'}$

All $m$ columns of $U$ are returned in array u.

$\mathbf{jobu}=\text{'S'}$

The first $\min \left(m,n\right)$ columns of $U$ (the left singular vectors) are returned in the array u.

$\mathbf{jobu}=\text{'O'}$

The first $\min \left(m,n\right)$ columns of $U$ (the left singular vectors) are overwritten on the array a.

$\mathbf{jobu}=\text{'N'}$

No columns of $U$ (no left singular vectors) are computed.

Constraint: $\mathbf{jobu}=\text{'A'}$, $\text{'S'}$, $\text{'O'}$ or $\text{'N'}$.

2:     $\mathrm{jobvt}$ – string (length ≥ 1)

Specifies options for computing all or part of the matrix $V^{\mathrm{T}}$.

$\mathbf{jobvt}=\text{'A'}$

All $n$ rows of $V^{\mathrm{T}}$ are returned in the array vt.

$\mathbf{jobvt}=\text{'S'}$

The first $\min \left(m,n\right)$ rows of $V^{\mathrm{T}}$ (the right singular vectors) are returned in the array vt.

$\mathbf{jobvt}=\text{'O'}$

The first $\min \left(m,n\right)$ rows of $V^{\mathrm{T}}$ (the right singular vectors) are overwritten on the array a.

$\mathbf{jobvt}=\text{'N'}$

No rows of $V^{\mathrm{T}}$ (no right singular vectors) are computed.

Constraints:

• $\mathbf{jobvt}=\text{'A'}$, $\text{'S'}$, $\text{'O'}$ or $\text{'N'}$;
• jobvt and jobu cannot both be $\text{'O'}$.

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

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

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

The $m$ by $n$ matrix $A$.

Optional Input Parameters

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

Default: the first dimension of the array a.

$m$, the number of rows of the matrix $A$.

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

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

Default: the second dimension of the array a.

$n$, the number of columns of the matrix $A$.

Constraint: $\mathbf{n}\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{m}\right)$.

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

If $\mathbf{jobu}=\text{'O'}$, a is overwritten with the first $\min \left(m,n\right)$ columns of $U$ (the left singular vectors, stored column-wise).

If $\mathbf{jobvt}=\text{'O'}$, a is overwritten with the first $\min \left(m,n\right)$ rows of $V^{\mathrm{T}}$ (the right singular vectors, stored row-wise).

If $\mathbf{jobu}\ne \text{'O'}$ and $\mathbf{jobvt}\ne \text{'O'}$, the contents of a are destroyed.

2:     $\mathrm{s}\left(:\right)$ – double array

The dimension of the array s will be $\max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\right)$

The singular values of $A$, sorted so that $\mathbf{s}\left(i\right)\ge \mathbf{s}\left(i+1\right)$.

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

The first dimension, $\mathit{ldu}$, of the array u will be

• if $\mathbf{jobu}=\text{'A'}$ or $\text{'S'}$, $\mathit{ldu}=\max \left(1,\mathbf{m}\right)$;
• otherwise $\mathit{ldu}=1$.

The second dimension of the array u will be $\max \left(1,\mathbf{m}\right)$ if $\mathbf{jobu}=\text{'A'}$, $\max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\right)$ if $\mathbf{jobu}=\text{'S'}$ and $1$ otherwise.

If $\mathbf{jobu}=\text{'A'}$, u contains the $m$ by $m$ orthogonal matrix $U$.

If $\mathbf{jobu}=\text{'S'}$, u contains the first $\min \left(m,n\right)$ columns of $U$ (the left singular vectors, stored column-wise).

If $\mathbf{jobu}=\text{'N'}$ or $\text{'O'}$, u is not referenced.

4:     $\mathrm{vt}\left(\mathit{ldvt},:\right)$ – double array

The first dimension, $\mathit{ldvt}$, of the array vt will be

• if $\mathbf{jobvt}=\text{'A'}$, $\mathit{ldvt}=\max \left(1,\mathbf{n}\right)$;
• if $\mathbf{jobvt}=\text{'S'}$, $\mathit{ldvt}=\max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\right)$;
• otherwise $\mathit{ldvt}=1$.

The second dimension of the array vt will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{jobvt}=\text{'A'}$ or $\text{'S'}$ and $1$ otherwise.

If $\mathbf{jobvt}=\text{'A'}$, vt contains the $n$ by $n$ orthogonal matrix $V^{\mathrm{T}}$.

If $\mathbf{jobvt}=\text{'S'}$, vt contains the first $\min \left(m,n\right)$ rows of $V^{\mathrm{T}}$ (the right singular vectors, stored row-wise).

If $\mathbf{jobvt}=\text{'N'}$ or $\text{'O'}$, vt is not referenced.

5:     $\mathrm{work}\left(\max \left(1,\mathit{lwork}\right)\right)$ – double array

If $\mathbf{info}=\mathbf{0}$, $\mathbf{work}\left(1\right)$ returns the optimal lwork.

If $\mathbf{info}>\mathbf{0}$, $\mathbf{work}\left(2:\min \left(\mathbf{m},\mathbf{n}\right)\right)$ contains the unconverged superdiagonal elements of an upper bidiagonal matrix $B$ whose diagonal is in s (not necessarily sorted). $B$ satisfies $A=UB{V}^{\mathrm{T}}$, so it has the same singular values as $A$, and singular vectors related by $U$ and $V^{\mathrm{T}}$.

6:     $\mathrm{info}$ – int64int32nag_int scalar

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

Error Indicators and Warnings

   $\mathbf{info}<0$

If $\mathbf{info}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

   $\mathbf{info}>0$

If nag_lapack_dgesvd (f08kb) did not converge, info specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08kb_example

function f08kb_example


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

% SVD of A to obtain Least-sqares solution of Ax=b, where
a = [ 2.27, -1.54,  1.15, -1.94;
      0.28, -1.67,  0.94, -0.78;
     -0.48, -3.09,  0.99, -0.21;
      1.07,  1.22,  0.79,  0.63;
     -2.35,  2.93, -1.45,  2.30;
      0.62, -7.39,  1.03, -2.57];
[m,n] = size(a);
b     = ones(m,1);

% SVD of A
jobu =  'Singular vectors part of U';
jobvt = 'Singular vectors part of VT';
[~, s, u, vt, work, info] = f08kb( ...
                                   jobu, jobvt, a);

disp('Singular values of A');
disp(s');

% Use SVD to compute least-squares solution: VS^(-1)U'b
y = u'*b;
y = y./s;
x = vt'*y;

disp('Least squares solution:');
disp(x');
disp('Norm of Residual:');
disp(norm(b - a*x));

f08kb example results

Singular values of A
    9.9966    3.6831    1.3569    0.5000

Least squares solution:
   -0.0563   -0.1700    0.8202    0.5545

Norm of Residual:
    1.7472