f02 Chapter Contents
f02 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_complex_svd (f02xec)

## 1  Purpose

nag_complex_svd (f02xec) returns all, or part, of the singular value decomposition of a general complex matrix.

## 2  Specification

 #include #include
 void nag_complex_svd (Integer m, Integer n, Complex a[], Integer tda, Integer ncolb, Complex b[], Integer tdb, Nag_Boolean wantq, Complex q[], Integer tdq, double sv[], Nag_Boolean wantp, Complex ph[], Integer tdph, Integer *iter, double e[], Integer *failinfo, NagError *fail)

## 3  Description

The $m$ by $n$ matrix $A$ is factorized as
 $A = QDP H$
where
 $D = S 0 m > n D = S , m = n D = S 0 m < n$
$Q$ is an $m$ by $m$ unitary matrix, $P$ is an $n$ by $n$ unitary matrix and $S$ is a $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ by $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ diagonal matrix with real non-negative diagonal elements, ${sv}_{1},{sv}_{2},\dots ,{sv}_{\mathrm{min}\left(m,n\right)}$, ordered such that
 $sv 1 ≥ sv 2 ≥ … ≥ sv min m,n ≥ 0 .$
The first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ columns of $Q$ are the left-hand singular vectors of $A$, the diagonal elements of $S$ are the singular values of $A$ and the first $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ columns of $P$ are the right-hand singular vectors of $A$.
Either or both of the left-hand and right-hand singular vectors of $A$ may be requested and the matrix $C$ given by
 $C = Q H B$
where $B$ is an $m$ by $\mathit{ncolb}$ given matrix, may also be requested.
The function obtains the singular value decomposition by first reducing $A$ to upper triangular form by means of Householder transformations, from the left when $m\ge n$ and from the right when $m The upper triangular form is then reduced to bidiagonal form by Givens plane rotations and finally the $QR$ algorithm is used to obtain the singular value decomposition of the bidiagonal form.
Good background descriptions to the singular value decomposition are given in Dongarra et al. (1979), Hammarling (1985) and Wilkinson (1978). Note that this function is not based on the LINPACK routine CSVDC.
Note that if $K$ is any unitary diagonal matrix such that
 $KK H = I$
then
 $A = Q K D P K H$
is also a singular value decomposition of $A$.

## 4  References

Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide SIAM, Philadelphia
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Wilkinson J H (1978) Singular Value Decomposition – Basic Aspects Numerical Software – Needs and Availability (ed D A H Jacobs) Academic Press

## 5  Arguments

1:    $\mathbf{m}$IntegerInput
On entry: the number of rows, $m$, of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
When ${\mathbf{m}}=0$ then an immediate return is effected.
2:    $\mathbf{n}$IntegerInput
On entry: the number of columns, $n$, of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
When ${\mathbf{n}}=0$ then an immediate return is effected.
3:    $\mathbf{a}\left[{\mathbf{m}}×{\mathbf{tda}}\right]$ComplexInput/Output
Note: the $\left(i,j\right)$th element of the matrix $A$ is stored in ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{tda}}+j-1\right]$.
On entry: the leading $m$ by $n$ part of the array a must contain the matrix $A$ whose singular value decomposition is required.
On exit: if ${\mathbf{m}}\ge {\mathbf{n}}$ and ${\mathbf{wantq}}=\mathrm{Nag_TRUE}$, then the leading $m$ by $n$ part of a will contain the first $n$ columns of the unitary matrix $Q$.
If ${\mathbf{m}}<{\mathbf{n}}$ and ${\mathbf{wantp}}=\mathrm{Nag_TRUE}$, then the leading $m$ by $n$ part of a will contain the first $m$ rows of the unitary matrix ${P}^{H}$.
If ${\mathbf{m}}\ge {\mathbf{n}}$ and ${\mathbf{wantq}}=\mathrm{Nag_FALSE}$ and ${\mathbf{wantp}}=\mathrm{Nag_TRUE}$, then the leading $n$ by $n$ part of a will contain the first $n$ rows of the unitary matrix ${P}^{H}$.
Otherwise the contents of the leading $m$ by $n$ part of a are indeterminate.
4:    $\mathbf{tda}$IntegerInput
On entry: the stride separating matrix column elements in the array a.
Constraint: ${\mathbf{tda}}\ge {\mathbf{n}}$.
5:    $\mathbf{ncolb}$IntegerInput
On entry: $\mathit{ncolb}$, the number of columns of the matrix $B$. When ${\mathbf{ncolb}}=0$ the array b is not referenced and may be NULL.
Constraint: ${\mathbf{ncolb}}\ge 0$.
6:    $\mathbf{b}\left[{\mathbf{m}}×{\mathbf{tdb}}\right]$ComplexInput/Output
Note: the $\left(i,j\right)$th element of the matrix $B$ is stored in ${\mathbf{b}}\left[\left(i-1\right)×{\mathbf{tdb}}+j-1\right]$.
On entry: if ${\mathbf{ncolb}}>0$, the leading $m$ by $\mathit{ncolb}$ part of the array b must contain the matrix to be transformed.
If ${\mathbf{ncolb}}=0$ the array b is not referenced and may be NULL.
On exit: b is overwritten by the $m$ by $\mathit{ncolb}$ matrix ${Q}^{H}B$.
7:    $\mathbf{tdb}$IntegerInput
On entry: the stride separating matrix column elements in the array b.
Constraint: if ${\mathbf{ncolb}}>0$ then ${\mathbf{tdb}}\ge {\mathbf{ncolb}}$.
8:    $\mathbf{wantq}$Nag_BooleanInput
On entry: wantq must be Nag_TRUE if the left-hand singular vectors are required. If ${\mathbf{wantq}}=\mathrm{Nag_FALSE}$ then the array q is not referenced and may be NULL.
9:    $\mathbf{q}\left[{\mathbf{m}}×{\mathbf{tdq}}\right]$ComplexOutput
Note: the $\left(i,j\right)$th element of the matrix $Q$ is stored in ${\mathbf{q}}\left[\left(i-1\right)×{\mathbf{tdq}}+j-1\right]$.
On exit: if ${\mathbf{m}}<{\mathbf{n}}$ and ${\mathbf{wantq}}=\mathrm{Nag_TRUE}$, the leading $m$ by $m$ part of the array q will contain the unitary matrix $Q$. Otherwise the array q is not referenced and may be NULL.
10:  $\mathbf{tdq}$IntegerInput
On entry: the stride separating matrix column elements in the array q.
Constraint: if ${\mathbf{m}}<{\mathbf{n}}$ and ${\mathbf{wantq}}=\mathrm{Nag_TRUE}$, ${\mathbf{tdq}}\ge {\mathbf{m}}$
11:  $\mathbf{sv}\left[\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right]$doubleOutput
On exit: the $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)$ diagonal elements of the matrix $S$.
12:  $\mathbf{wantp}$Nag_BooleanInput
On entry: wantp must be Nag_TRUE if the right-hand singular vectors are required. If wantp = Nag_FALSE then the array ph is not referenced and may be NULL.
13:  $\mathbf{ph}\left[{\mathbf{n}}×{\mathbf{tdph}}\right]$ComplexOutput
Note: the $\left(i,j\right)$th element of the matrix is stored in ${\mathbf{ph}}\left[\left(i-1\right)×{\mathbf{tdph}}+j-1\right]$.
On exit: if ${\mathbf{m}}\ge {\mathbf{n}}$ and wantq and wantp are Nag_TRUE, the leading $n$ by $n$ part of the array ph will contain the unitary matrix ${P}^{H}$. Otherwise the array ph is not referenced and may be NULL.
14:  $\mathbf{tdph}$IntegerInput
On entry: the stride separating matrix column elements in the array ph.
Constraint: if ${\mathbf{m}}\ge {\mathbf{n}}$ and ${\mathbf{wantq}}=\mathrm{Nag_TRUE}$ and ${\mathbf{wantp}}=\mathrm{Nag_TRUE}$, ${\mathbf{tdph}}\ge {\mathbf{n}}$
15:  $\mathbf{iter}$Integer *Output
On exit: the total number of iterations taken by the $QR$ algorithm.
16:  $\mathbf{e}\left[\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}\right)\right]$doubleOutput
On exit: if the error NE_QR_NOT_CONV occurs the array e contains the super-diagonal elements of matrix $E$ in the factorization of $A$ according to $A={QEP}^{H}$. See Section 6 for further details.
17:  $\mathbf{failinfo}$Integer *Output
On exit: if the error NE_QR_NOT_CONV occurs failinfo contains the number of singular values which may not have been found correctly. See Section 6 for details.
18:  $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, ${\mathbf{tda}}=〈\mathit{\text{value}}〉$ while ${\mathbf{n}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tda}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{tdb}}=〈\mathit{\text{value}}〉$ while ${\mathbf{ncolb}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tdb}}\ge {\mathbf{ncolb}}$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_INT_ARG_LT
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{ncolb}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ncolb}}\ge 0$.
NE_QR_NOT_CONV
The QR algorithm has failed to converge in $〈\mathit{\text{value}}〉$ iterations. Singular values $1,2,\dots ,{\mathbf{failinfo}}$ may not have been found correctly and the remaining singular values may not be the smallest. The matrix $A$ will nevertheless have been factorized as $A={QEP}^{\mathrm{T}}$, where the leading $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ by $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m,n\right)$ part of $E$ is a bidiagonal matrix with ${\mathbf{sv}}\left[0\right],{\mathbf{sv}}\left[1\right],\dots ,{\mathbf{sv}}\left[\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},{\mathbf{n}}-1\right)\right]$ as the diagonal elements and ${\mathbf{e}}\left[0\right],{\mathbf{e}}\left[1\right],\dots ,{\mathbf{e}}\left[\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}}\text{'}{\mathbf{n}}-2\right)\right]$ as the super-diagonal elements. This failure is not likely to occur.
NE_TDP_LT_N
On entry, ${\mathbf{tdph}}=〈\mathit{\text{value}}〉$ while ${\mathbf{n}}=〈\mathit{\text{value}}〉$. When wantq and wantp are Nag_TRUE and ${\mathbf{m}}\ge {\mathbf{n}}$ then relationship ${\mathbf{tdph}}\ge {\mathbf{n}}$ must be satisfied.
NE_TDQ_LT_M
On entry, ${\mathbf{tdq}}=〈\mathit{\text{value}}〉$ while ${\mathbf{m}}=〈\mathit{\text{value}}〉$. When wantq is Nag_TRUE and ${\mathbf{m}}<{\mathbf{n}}$ then relationship ${\mathbf{tdq}}\ge {\mathbf{m}}$ must be satisfied.

## 7  Accuracy

The computed factors $Q$, $D$ and $P$ satisfy the relation
 $QDP H = A + E$
where $‖E‖\le c\epsilon ‖A‖$, $\epsilon$ being the machine precision, $c$ is a modest function of $m$ and $n$ and $\text{.}$ denotes the spectral (two) norm. Note that $‖A‖={sv}_{1}$.

Not applicable.

None.

## 10  Example

For this function two examples are presented. There is a single example program for nag_complex_svd (f02xec), with a main program and the code to solve the two example problems is given in the functions ex1 and ex2.
Example 1 (ex1)
To find the singular value decomposition of the 5 by 3 matrix
 $A = 0.5 i -0.5 + 1.5 i -1.0 + 1.0 i 0.4 + 0.3 i - 0.9 + 1.3 i - 0.2 + 1.4 i 0.4 +0.3 i -0.4 + 0.4 i - 1.8 +0.3 i 0.3 - 0.4 i - 0.1 + 0.7 i - 0.0 +0.3 i -0.3 i - 0.3 + 0.3 i 2.4 i$
together with the vector ${Q}^{H}b$ for the vector
 $b = -0.55 + 1.05 i 0.49 + 0.93 i 0.56 - 0.16 i 0.39 + 0.23 i 1.13 + 0.83 i .$
Example 2 (ex2)
To find the singular value decomposition of the 3 by 5 matrix
 $A = 0.5 i 0.4 - 0.3 i - 0.4 -0.4 i 0.3 + 0.4 i 0.3 i -0.5 - 1.5 i 0.9 - 1.3 i -0.4 - 0.4 i 0.1 - 0.7 i 0.3 - 0.3 i -1.0 - 1.0 i 0.2 - 1.4 i - 1.8 -0.4 i - 0.0 -0.4 i -2.4 i .$

### 10.1  Program Text

Program Text (f02xece.c)

### 10.2  Program Data

Program Data (f02xece.d)

### 10.3  Program Results

Program Results (f02xece.r)