# NAG FL Interfacef08kwf (zgesvj)

## 1Purpose

f08kwf computes the one-sided Jacobi singular value decomposition (SVD) of a complex $m$ by $n$, general or triangular, matrix $A$, $m\ge n$, with fast scaled rotations and de Rijk’s pivoting, optionally computing the left and/or right singular vectors. For $m, the routines f08kpf or f08krf may be used.

## 2Specification

Fortran Interface
 Subroutine f08kwf ( joba, jobu, jobv, m, n, a, lda, sva, mv, v, ldv, info)
 Integer, Intent (In) :: m, n, lda, mv, ldv, lwork, lrwork Integer, Intent (Out) :: info Real (Kind=nag_wp), Intent (Inout) :: rwork(lrwork) Real (Kind=nag_wp), Intent (Out) :: sva(n) Complex (Kind=nag_wp), Intent (Inout) :: a(lda,*), v(ldv,*) Complex (Kind=nag_wp), Intent (Out) :: cwork(lwork) Character (1), Intent (In) :: joba, jobu, jobv
#include <nag.h>
 void f08kwf_ (const char *joba, const char *jobu, const char *jobv, const Integer *m, const Integer *n, Complex a[], const Integer *lda, double sva[], const Integer *mv, Complex v[], const Integer *ldv, Complex cwork[], const Integer *lwork, double rwork[], const Integer *lrwork, Integer *info, const Charlen length_joba, const Charlen length_jobu, const Charlen length_jobv)
The routine may be called by the names f08kwf, nagf_lapackeig_zgesvj or its LAPACK name zgesvj.

## 3Description

The SVD is written as
 $A = UΣVH ,$
where $\Sigma$ is an $n$ by $n$ diagonal matrix, $U$ is an $m$ by $n$ unitary matrix, and $V$ is an $n$ by $n$ unitary matrix. The diagonal elements of $\Sigma$ are the singular values of $A$ in descending order of magnitude. The columns of $U$ and $V$ are the left and the right singular vectors of $A$, respectively.

## 4References

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 https://www.netlib.org/lapack/lug
Drmač Z and Veselić K (2008a) New fast and accurate Jacobi SVD Algorithm I SIAM J. Matrix Anal. Appl. 29 4
Drmač Z and Veselić K (2008b) New fast and accurate Jacobi SVD Algorithm II SIAM J. Matrix Anal. Appl. 29 4
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## 5Arguments

1: $\mathbf{joba}$Character(1) Input
On entry: specifies the structure of matrix $A$.
${\mathbf{joba}}=\text{'L'}$
The input matrix $A$ is lower triangular.
${\mathbf{joba}}=\text{'U'}$
The input matrix $A$ is upper triangular.
${\mathbf{joba}}=\text{'G'}$
The input matrix $A$ is a general $m$ by $n$ matrix, ${\mathbf{m}}\ge {\mathbf{n}}$.
Constraint: ${\mathbf{joba}}=\text{'L'}$, $\text{'U'}$ or $\text{'G'}$.
2: $\mathbf{jobu}$Character(1) Input
On entry: specifies whether to compute the left singular vectors and if so whether you want to control their numerical orthogonality threshold.
${\mathbf{jobu}}=\text{'U'}$
The left singular vectors corresponding to the nonzero singular values are computed and returned in the leading columns of a. See more details in the description of a. The numerical orthogonality threshold is set to approximately $\mathit{tol}=\sqrt{m}×\epsilon$, where $\epsilon$ is the machine precision.
${\mathbf{jobu}}=\text{'C'}$
Analogous to ${\mathbf{jobu}}=\text{'U'}$, except that you can control the level of numerical orthogonality of the computed left singular vectors. The orthogonality threshold is set to $\mathit{tol}=\mathit{ctol}×\epsilon$, where $\mathit{ctol}$ is given on input in ${\mathbf{rwork}}\left(1\right)$. The option ${\mathbf{jobu}}=\text{'C'}$ can be used if $m×\epsilon$ is a satisfactory orthogonality of the computed left singular vectors, so $\mathit{ctol}={\mathbf{m}}$ could save a few sweeps of Jacobi rotations. See the descriptions of a and ${\mathbf{rwork}}\left(1\right)$.
${\mathbf{jobu}}=\text{'N'}$
The matrix $U$ is not computed. However, see the description of a.
Constraint: ${\mathbf{jobu}}=\text{'U'}$, $\text{'C'}$ or $\text{'N'}$.
3: $\mathbf{jobv}$Character(1) Input
On entry: specifies whether and how to compute the right singular vectors.
${\mathbf{jobv}}=\text{'V'}$
The matrix $V$ is computed and returned in the array v.
${\mathbf{jobv}}=\text{'A'}$
The Jacobi rotations are applied to the leading ${m}_{v}$ by $n$ part of the array v. In other words, the right singular vector matrix $V$ is not computed explicitly, instead it is applied to an ${m}_{v}$ by $n$ matrix initially stored in the first mv rows of v.
${\mathbf{jobv}}=\text{'N'}$
The matrix $V$ is not computed and the array v is not referenced.
Constraint: ${\mathbf{jobv}}=\text{'V'}$, $\text{'A'}$ or $\text{'N'}$.
4: $\mathbf{m}$Integer Input
On entry: $m$, the number of rows of the matrix $A$.
Constraint: ${\mathbf{m}}\ge 0$.
5: $\mathbf{n}$Integer Input
On entry: $n$, the number of columns of the matrix $A$.
Constraint: ${\mathbf{m}}\ge {\mathbf{n}}\ge 0$.
6: $\mathbf{a}\left({\mathbf{lda}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry: the $m$ by $n$ matrix $A$.
On exit: the matrix $U$ containing the left singular vectors of $A$.
If ${\mathbf{jobu}}=\text{'U'}$ or $\text{'C'}$
if ${\mathbf{info}}=0$
$\mathrm{rank}\left(A\right)$ unitary columns of $U$ are returned in the leading $\mathrm{rank}\left(A\right)$ columns of the array a. Here $\mathrm{rank}\left(A\right)\le {\mathbf{n}}$ is the number of computed singular values of $A$ that are above the safe range parameter, as returned by x02amf. The singular vectors corresponding to underflowed or zero singular values are not computed. The value of $\mathrm{rank}\left(A\right)$ is returned by rounding ${\mathbf{rwork}}\left(2\right)$ to the nearest whole number. Also see the descriptions of sva and rwork. The computed columns of $U$ are mutually numerically unitary up to approximately $\mathit{tol}=\sqrt{m}×\epsilon$; or $\mathit{tol}=\mathit{ctol}×\epsilon$ (${\mathbf{jobu}}=\text{'C'}$), where $\epsilon$ is the machine precision and $\mathit{ctol}$ is supplied on entry in ${\mathbf{rwork}}\left(1\right)$, see the description of jobu.
if ${\mathbf{info}}>0$
f08kwf did not converge in $30$ iterations (sweeps). In this case, the computed columns of $U$ may not be unitary up to $\mathit{tol}$. The output $U$ (stored in a), $\Sigma$ (given by the computed singular values in sva) and $V$ is still a decomposition of the input matrix $A$ in the sense that the residual ${‖A-\alpha ×U×\Sigma ×{V}^{\mathrm{H}}‖}_{2}/{‖A‖}_{2}$ is small, where $\alpha$ is the value returned in ${\mathbf{rwork}}\left(1\right)$.
If ${\mathbf{jobu}}=\text{'N'}$
if ${\mathbf{info}}=0$
Note that the left singular vectors are ‘for free’ in the one-sided Jacobi SVD algorithm. However, if only the singular values are needed, the level of numerical orthogonality of $U$ is not an issue and iterations are stopped when the columns of the iterated matrix are numerically unitary up to approximately $m×\epsilon$. Thus, on exit, a contains the columns of $U$ scaled with the corresponding singular values.
if ${\mathbf{info}}>0$
f08kwf did not converge in $30$ iterations (sweeps).
7: $\mathbf{lda}$Integer Input
On entry: the first dimension of the array a as declared in the (sub)program from which f08kwf is called.
Constraint: ${\mathbf{lda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
8: $\mathbf{sva}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
On exit: the, possibly scaled, singular values of $A$.
If ${\mathbf{info}}=0$
The singular values of $A$ are ${\sigma }_{\mathit{i}}=\alpha ×{\mathbf{sva}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n$, where $\alpha$ is the scale factor stored in ${\mathbf{rwork}}\left(1\right)$. Normally $\alpha =1$, however, if some of the singular values of $A$ might underflow or overflow, then $\alpha \ne 1$ and the scale factor needs to be applied to obtain the singular values.
If ${\mathbf{info}}>0$
f08kwf did not converge in $30$ iterations and $\alpha ×{\mathbf{sva}}$ may not be accurate.
9: $\mathbf{mv}$Integer Input
On entry: if ${\mathbf{jobv}}=\text{'A'}$, the product of Jacobi rotations is applied to the first ${m}_{v}$ rows of v.
If ${\mathbf{jobv}}\ne \text{'A'}$, mv is ignored. See the description of jobv.
Constraint: ${\mathbf{mv}}\ge 0$.
10: $\mathbf{v}\left({\mathbf{ldv}},*\right)$Complex (Kind=nag_wp) array Input/Output
Note: the second dimension of the array v must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$ if ${\mathbf{jobv}}=\text{'V'}$ or $\text{'A'}$, and at least $1$ otherwise.
On entry: if ${\mathbf{jobv}}=\text{'A'}$, v must contain an ${m}_{v}$ by $n$ matrix to be premultiplied by the matrix $V$ of right singular vectors.
On exit: the right singular vectors of $A$.
If ${\mathbf{jobv}}=\text{'V'}$, v contains the $n$ by $n$ matrix of the right singular vectors.
If ${\mathbf{jobv}}=\text{'A'}$, v contains the product of the computed right singular vector matrix and the initial matrix in the array v.
If ${\mathbf{jobv}}=\text{'N'}$, v is not referenced.
11: $\mathbf{ldv}$Integer Input
On entry: the first dimension of the array v as declared in the (sub)program from which f08kwf is called.
Constraints:
• if ${\mathbf{jobv}}=\text{'V'}$, ${\mathbf{ldv}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{jobv}}=\text{'A'}$, ${\mathbf{ldv}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{mv}}\right)$;
• otherwise ${\mathbf{ldv}}\ge 1$.
12: $\mathbf{cwork}\left({\mathbf{lwork}}\right)$Complex (Kind=nag_wp) array Workspace
On exit: if ${\mathbf{info}}={\mathbf{0}}$, ${\mathbf{cwork}}\left(1\right)$ contains the required minimal size of lwork.
13: $\mathbf{lwork}$Integer Input
On entry: the dimension of the array cwork as declared in the (sub)program from which f08kwf is called.
Constraint: ${\mathbf{lwork}}\ge {\mathbf{m}}+{\mathbf{n}}$.
14: $\mathbf{rwork}\left({\mathbf{lrwork}}\right)$Real (Kind=nag_wp) array Workspace
On entry: if ${\mathbf{jobu}}=\text{'C'}$, ${\mathbf{rwork}}\left(1\right)=\mathit{ctol}$, where $\mathit{ctol}$ defines the threshold for convergence. The process stops if all columns of $A$ are mutually orthogonal up to $\mathit{ctol}×\epsilon$. It is required that $\mathit{ctol}\ge 1$, i.e., it is not possible to force the routine to obtain orthogonality below $\epsilon$. $\mathit{ctol}$ greater than $1/\epsilon$ is meaningless, where $\epsilon$ is the machine precision.
On exit: contains information about the completed job.
${\mathbf{rwork}}\left(1\right)$
The scaling factor, $\alpha$, such that ${\sigma }_{\mathit{i}}=\alpha ×{\mathbf{sva}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n$, are the computed singular values of $A$. (See the description of sva.)
${\mathbf{rwork}}\left(2\right)$
${\mathbf{rwork}}\left(2\right)$ gives, as nearest integer, the number of the computed nonzero singular values.
${\mathbf{rwork}}\left(3\right)$
${\mathbf{rwork}}\left(3\right)$ gives, as nearest integer, the number of the computed singular values that are larger than the underflow threshold.
${\mathbf{rwork}}\left(4\right)$
${\mathbf{rwork}}\left(4\right)$ gives, as nearest integer, the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.
${\mathbf{rwork}}\left(5\right)$
${\mathrm{max}}_{i\ne j}\left|\mathrm{cos}\left(A\left(:,i\right),A\left(:,j\right)\right)\right|$ in the last iteration (sweep). This is useful information in cases when f08kwf did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.
${\mathbf{rwork}}\left(6\right)$
The largest absolute value over all sines of the Jacobi rotation angles in the last sweep. It can be useful for subsequent analysis.
Constraint: if ${\mathbf{jobu}}=\text{'C'}$, ${\mathbf{rwork}}\left(1\right)\ge 1.0$.
15: $\mathbf{lrwork}$Integer Input
On entry: the dimension of the array rwork as declared in the (sub)program from which f08kwf is called.
Constraint: ${\mathbf{lrwork}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(6,{\mathbf{n}}\right)$.
16: $\mathbf{info}$Integer Output
On exit: ${\mathbf{info}}=0$ unless the routine detects an error (see Section 6).

## 6Error 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$
f08kwf did not converge in the allowed number of iterations ($30$), but its output might still be useful.

## 7Accuracy

The computed SVD is nearly the exact SVD 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 unitary to working precision. See Section 4.9 of Anderson et al. (1999) for further details.
See Section 6 of Drmač and Veselić (2008a) for a detailed discussion of the accuracy of the computed SVD.

## 8Parallelism and Performance

f08kwf 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.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

This SVD algorithm is numerically superior to the bidiagonalization based $QR$ algorithm implemented by f08kpf and the divide and conquer algorithm implemented by f08krf and is considerably faster than previous implementations of the (equally accurate) Jacobi SVD method. Moreover, this algorithm can compute the SVD faster than f08kpf and not much slower than f08krf. See Section 3.3 of Drmač and Veselić (2008b) for the details.
The real analogue of this routine is f08kjf.

## 10Example

This example finds the singular values and left and right singular vectors of the $6$ by $4$ matrix
 $A = 0.96-0.81i -0.03+0.96i -0.91+2.06i -0.05+0.41i -0.98+1.98i -1.20+0.19i -0.66+0.42i -0.81+0.56i 0.62-0.46i 1.01+0.02i 0.63-0.17i -1.11+0.60i -0.37+0.38i 0.19-0.54i -0.98-0.36i 0.22-0.20i 0.83+0.51i 0.20+0.01i -0.17-0.46i 1.47+1.59i 1.08-0.28i 0.20-0.12i -0.07+1.23i 0.26+0.26i ,$
together with approximate error bounds for the computed singular values and vectors.

### 10.1Program Text

Program Text (f08kwfe.f90)

### 10.2Program Data

Program Data (f08kwfe.d)

### 10.3Program Results

Program Results (f08kwfe.r)