f08 Chapter Contents
f08 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_dgesvd (f08kbc)

## 1  Purpose

nag_dgesvd (f08kbc) computes the singular value decomposition (SVD) of a real $m$ by $n$ matrix $A$, optionally computing the left and/or right singular vectors.

## 2  Specification

 #include #include
 void nag_dgesvd (Nag_OrderType order, Nag_ComputeUType jobu, Nag_ComputeVTType jobvt, Integer m, Integer n, double a[], Integer pda, double s[], double u[], Integer pdu, double vt[], Integer pdvt, double work[], NagError *fail)

## 3  Description

The SVD is written as
 $A = UΣVT ,$
where $\Sigma$ is an $m$ by $n$ matrix which is zero except for its $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ diagonal elements, $U$ is an $m$ by $m$ orthogonal matrix, and $V$ is an $n$ by $n$ orthogonal matrix. The diagonal elements of $\Sigma$ are the singular values of $A$; they are real and non-negative, and are returned in descending order. The first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ columns of $U$ and $V$ are the left and right singular vectors of $A$.
Note that the function returns ${V}^{\mathrm{T}}$, not $V$.

## 4  References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or $\mathrm{Nag_ColMajor}$.
2:     jobuNag_ComputeUTypeInput
On entry: specifies options for computing all or part of the matrix $U$.
${\mathbf{jobu}}=\mathrm{Nag_AllU}$
All $m$ columns of $U$ are returned in array u.
${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$
The first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ columns of $U$ (the left singular vectors) are returned in the array u.
${\mathbf{jobu}}=\mathrm{Nag_Overwrite}$
The first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ columns of $U$ (the left singular vectors) are overwritten on the array a.
${\mathbf{jobu}}=\mathrm{Nag_NotU}$
No columns of $U$ (no left singular vectors) are computed.
Constraint: ${\mathbf{jobu}}=\mathrm{Nag_AllU}$, $\mathrm{Nag_SingularVecsU}$, $\mathrm{Nag_Overwrite}$ or $\mathrm{Nag_NotU}$.
3:     jobvtNag_ComputeVTTypeInput
On entry: specifies options for computing all or part of the matrix ${V}^{\mathrm{T}}$.
${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$
All $n$ rows of ${V}^{\mathrm{T}}$ are returned in the array vt.
${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$
The first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ rows of ${V}^{\mathrm{T}}$ (the right singular vectors) are returned in the array vt.
${\mathbf{jobvt}}=\mathrm{Nag_OverwriteVT}$
The first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ rows of ${V}^{\mathrm{T}}$ (the right singular vectors) are overwritten on the array a.
${\mathbf{jobvt}}=\mathrm{Nag_NotVT}$
No rows of ${V}^{\mathrm{T}}$ (no right singular vectors) are computed.
Constraints:
• ${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$, $\mathrm{Nag_SingularVecsVT}$, $\mathrm{Nag_OverwriteVT}$ or $\mathrm{Nag_NotVT}$;
• If ${\mathbf{jobu}}=\mathrm{Nag_Overwrite}$, jobvt cannot be $\mathrm{Nag_OverwriteVT}$.
4:     mIntegerInput
On entry: $m$, the number of rows of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
5:     nIntegerInput
On entry: $n$, the number of columns of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
6:     a[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array a must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pda}}×{\mathbf{n}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pda}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
The $\left(i,j\right)$th element of the matrix $A$ is stored in
• ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $m$ by $n$ matrix $A$.
On exit: if ${\mathbf{jobu}}=\mathrm{Nag_Overwrite}$, a is overwritten with the first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ columns of $U$ (the left singular vectors, stored column-wise).
If ${\mathbf{jobvt}}=\mathrm{Nag_OverwriteVT}$, a is overwritten with the first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ rows of ${V}^{\mathrm{T}}$ (the right singular vectors, stored row-wise).
If ${\mathbf{jobu}}\ne \mathrm{Nag_Overwrite}$ and ${\mathbf{jobvt}}\ne \mathrm{Nag_OverwriteVT}$, the contents of a are destroyed.
7:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
8:     s[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array s must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$.
On exit: the singular values of $A$, sorted so that ${\mathbf{s}}\left[i-1\right]\ge {\mathbf{s}}\left[i\right]$.
9:     u[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array u must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdu}}×{\mathbf{m}}\right)$ when ${\mathbf{jobu}}=\mathrm{Nag_AllU}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdu}}×\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$ when ${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$ and ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pdu}}\right)$ when ${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$ and ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $1$ otherwise.
The $\left(i,j\right)$th element of the matrix $U$ is stored in
• ${\mathbf{u}}\left[\left(j-1\right)×{\mathbf{pdu}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{u}}\left[\left(i-1\right)×{\mathbf{pdu}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobu}}=\mathrm{Nag_AllU}$, u contains the $m$ by $m$ orthogonal matrix $U$.
If ${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$, u contains the first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ columns of $U$ (the left singular vectors, stored column-wise).
If ${\mathbf{jobu}}=\mathrm{Nag_NotU}$ or $\mathrm{Nag_Overwrite}$, u is not referenced.
10:   pduIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array u.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{jobu}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• otherwise ${\mathbf{pdu}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$,
• if ${\mathbf{jobu}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$;
• otherwise ${\mathbf{pdu}}\ge 1$.
11:   vt[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array vt must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvt}}×{\mathbf{n}}\right)$ when ${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdvt}}×{\mathbf{n}}\right)$ when ${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$ and ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)×{\mathbf{pdvt}}\right)$ when ${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$ and ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $1$ otherwise.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{vt}}\left[\left(j-1\right)×{\mathbf{pdvt}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{vt}}\left[\left(i-1\right)×{\mathbf{pdvt}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$, vt contains the $n$ by $n$ orthogonal matrix ${V}^{\mathrm{T}}$.
If ${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$, vt contains the first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ rows of ${V}^{\mathrm{T}}$ (the right singular vectors, stored row-wise).
If ${\mathbf{jobvt}}=\mathrm{Nag_NotVT}$ or $\mathrm{Nag_OverwriteVT}$, vt is not referenced.
12:   pdvtIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array vt.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$,
• if ${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$;
• otherwise ${\mathbf{pdvt}}\ge 1$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$,
• if ${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise ${\mathbf{pdvt}}\ge 1$.
13:   work[$\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)$]doubleOutput
On exit: if ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_CONVERGENCE, ${\mathbf{WORK}}\left(2:\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$ (using the notation described in Section 3.2.1.4 in the Essential Introduction) 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}}$.
14:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_CONVERGENCE
If nag_dgesvd (f08kbc) did not converge, ${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero.
NE_ENUM_INT_2
On entry, ${\mathbf{jobu}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{pdu}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{jobu}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
if ${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
otherwise ${\mathbf{pdu}}\ge 1$.
NE_ENUM_INT_3
On entry, ${\mathbf{jobu}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{pdu}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{jobu}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
if ${\mathbf{jobu}}=\mathrm{Nag_SingularVecsU}$, ${\mathbf{pdu}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$;
otherwise ${\mathbf{pdu}}\ge 1$.
On entry, ${\mathbf{jobvt}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{pdvt}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
if ${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right)$;
otherwise ${\mathbf{pdvt}}\ge 1$.
On entry, ${\mathbf{jobvt}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{pdvt}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{jobvt}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
if ${\mathbf{jobvt}}=\mathrm{Nag_SingularVecsVT}$, ${\mathbf{pdvt}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
otherwise ${\mathbf{pdvt}}\ge 1$.
NE_INT
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\ge 0$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{pda}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pda}}>0$.
On entry, ${\mathbf{pdu}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdu}}>0$.
On entry, ${\mathbf{pdvt}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdvt}}>0$.
NE_INT_2
On entry, ${\mathbf{pda}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
On entry, ${\mathbf{pda}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

## 7  Accuracy

The computed singular value decomposition is nearly the exact singular value decomposition for a nearby matrix $\left(A+E\right)$, where
 $E2 = Oε A2 ,$
and $\epsilon$ is the machine precision. In addition, the computed singular vectors are nearly orthogonal to working precision. See Section 4.9 of Anderson et al. (1999) for further details.

## 8  Parallelism and Performance

nag_dgesvd (f08kbc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_dgesvd (f08kbc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

The total number of floating-point operations is approximately proportional to $m{n}^{2}$ when $m>n$ and ${m}^{2}n$ otherwise.
The singular values are returned in descending order.
The complex analogue of this function is nag_zgesvd (f08kpc).

## 10  Example

This example finds the singular values and left and right singular vectors of the $6$ by $4$ matrix
 $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 ,$
together with approximate error bounds for the computed singular values and vectors.
The example program for nag_dgesdd (f08kdc) illustrates finding a singular value decomposition for the case $m\le n$.

### 10.1  Program Text

Program Text (f08kbce.c)

### 10.2  Program Data

Program Data (f08kbce.d)

### 10.3  Program Results

Program Results (f08kbce.r)