NAG Library Function Document

nag_dgesvj (f08kjc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:    $\mathbf{order}$ – Nag_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:    $\mathbf{joba}$ – Nag_MatrixTypeInput

On entry: specifies the structure of matrix $A$.

$\mathbf{joba}=\mathrm{Nag\_LowerMatrix}$

The input matrix $A$ is lower triangular.

$\mathbf{joba}=\mathrm{Nag\_UpperMatrix}$

The input matrix $A$ is upper triangular.

$\mathbf{joba}=\mathrm{Nag\_GeneralMatrix}$

The input matrix $A$ is a general $m$ by $n$ matrix, $\mathbf{m}\ge \mathbf{n}$.

Constraint: $\mathbf{joba}=\mathrm{Nag\_LowerMatrix}$, $\mathrm{Nag\_UpperMatrix}$ or $\mathrm{Nag\_GeneralMatrix}$.

3:    $\mathbf{jobu}$ – Nag_LeftVecsTypeInput

On entry: specifies whether to compute the left singular vectors and if so whether you want to control their numerical orthogonality threshold.

$\mathbf{jobu}=\mathrm{Nag\_LeftSpan}$

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}=\mathit{ctol}\times \epsilon$, where $\epsilon$ is the machine precision and $\mathit{ctol}=\sqrt{m}$.

$\mathbf{jobu}=\mathrm{Nag\_LeftVecsCtol}$

Analogous to $\mathbf{jobu}=\mathrm{Nag\_LeftSpan}$, 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}\times \epsilon$, where $\mathit{ctol}$ is given on input in $\mathbf{work}\left[0\right]$. The option $\mathbf{jobu}=\mathrm{Nag\_LeftVecsCtol}$ can be used if $m\times \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{work}\left[0\right]$.

$\mathbf{jobu}=\mathrm{Nag\_NotLeftVecs}$

The matrix $U$ is not computed. However, see the description of a.

Constraint: $\mathbf{jobu}=\mathrm{Nag\_LeftSpan}$, $\mathrm{Nag\_LeftVecsCtol}$ or $\mathrm{Nag\_NotLeftVecs}$.

4:    $\mathbf{jobv}$ – Nag_RightVecsTypeInput

On entry: specifies whether and how to compute the right singular vectors.

$\mathbf{jobv}=\mathrm{Nag\_RightVecs}$

The matrix $V$ is computed and returned in the array v.

$\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$

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}=\mathrm{Nag\_NotRightVecs}$

The matrix $V$ is not computed and the array v is not referenced.

Constraint: $\mathbf{jobv}=\mathrm{Nag\_RightVecs}$, $\mathrm{Nag\_RightVecsMV}$ or $\mathrm{Nag\_NotRightVecs}$.

5:    $\mathbf{m}$ – IntegerInput

On entry: $m$, the number of rows of the matrix $A$.

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

6:    $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of columns of the matrix $A$.

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

7:    $\mathbf{a}\left[\mathit{dim}\right]$ – doubleInput/Output

Note: the dimension, dim, of the array a must be at least

• $\max \left(1,\mathbf{pda}\times \mathbf{n}\right)$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\max \left(1,\mathbf{m}\times \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)\times \mathbf{pda}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{a}\left[\left(i-1\right)\times \mathbf{pda}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

On entry: the $m$ by $n$ matrix $A$.

On exit: the matrix $U$ containing the left singular vectors of $A$.

If $\mathbf{jobu}=\mathrm{Nag\_LeftSpan}$ or $\mathrm{Nag\_LeftVecsCtol}$

if $\mathbf{fail}\mathbf{.}\mathbf{errnum}=0$

$\mathrm{rank}\left(A\right)$ orthonormal 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 nag_real_safe_small_number (X02AMC). 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{work}\left[1\right]$ to the nearest whole number. Also see the descriptions of sva and work. The computed columns of $U$ are mutually numerically orthogonal up to approximately $\mathit{tol}=\sqrt{m}\times \epsilon$; or $\mathit{tol}=\mathit{ctol}\times \epsilon$ ($\mathbf{jobu}=\mathrm{Nag\_LeftVecsCtol}$), where $\epsilon$ is the machine precision and $\mathit{ctol}$ is supplied on entry in $\mathbf{work}\left[0\right]$, see the description of jobu.

If $\mathbf{fail}\mathbf{.}\mathbf{errnum}>0$

nag_dgesvj (f08kjc) did not converge in $30$ iterations (sweeps). In this case, the computed columns of $U$ may not be orthogonal 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 \times U\times \Sigma \times V^{\mathrm{T}}‖}_2/{‖A‖}_2$ is small, where $\alpha$ is the value returned in $\mathbf{work}\left[0\right]$.

If $\mathbf{jobu}=\mathrm{Nag\_NotLeftVecs}$

if $\mathbf{fail}\mathbf{.}\mathbf{errnum}=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 orthogonal up to approximately $m\times \epsilon$. Thus, on exit, a contains the columns of $U$ scaled with the corresponding singular values.

If $\mathbf{fail}\mathbf{.}\mathbf{errnum}>0$

nag_dgesvj (f08kjc) did not converge in $30$ iterations (sweeps).

8:    $\mathbf{pda}$ – IntegerInput

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 \max \left(1,\mathbf{m}\right)$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$, $\mathbf{pda}\ge \max \left(1,\mathbf{n}\right)$.

9:    $\mathbf{sva}\left[\mathbf{n}\right]$ – doubleOutput

On exit: the, possibly scaled, singular values of $A$.

If $\mathbf{fail}\mathbf{.}\mathbf{errnum}=0$

The singular values of $A$ are ${\sigma }_{\mathit{i}}=\alpha \mathbf{sva}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,n$, where $\alpha$ is the scale factor stored in $\mathbf{work}\left[0\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{fail}\mathbf{.}\mathbf{errnum}>0$

nag_dgesvj (f08kjc) did not converge in $30$ iterations and $\alpha \times \mathbf{sva}$ may not be accurate.

10:  $\mathbf{mv}$ – IntegerInput

On entry: if $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$, the product of Jacobi rotations is applied to the first $m_v$ rows of v.

If $\mathbf{jobv}\ne \mathrm{Nag\_RightVecsMV}$, mv is ignored. See the description of jobv.

11:  $\mathbf{v}\left[\mathit{dim}\right]$ – doubleInput/Output

Note: the dimension, dim, of the array v must be at least

• $\max \left(1,\mathbf{pdv}\times \mathbf{n}\right)$ when $\mathbf{jobv}=\mathrm{Nag\_RightVecs}$;
• $\max \left(1,\mathbf{pdv}\times \mathbf{n}\right)$ when $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$ and $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\max \left(1,\mathbf{mv}\times \mathbf{pdv}\right)$ when $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$ and $\mathbf{order}=\mathrm{Nag\_RowMajor}$;
• $\max \left(1,\mathbf{mv}\right)$ otherwise.

The $\left(i,j\right)$th element of the matrix $V$ is stored in

• $\mathbf{v}\left[\left(j-1\right)\times \mathbf{pdv}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{v}\left[\left(i-1\right)\times \mathbf{pdv}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

On entry: if $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$, 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}=\mathrm{Nag\_RightVecs}$, v contains the $n$ by $n$ matrix of the right singular vectors.

If $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$, v contains the product of the computed right singular vector matrix and the initial matrix in the array v.

If $\mathbf{jobv}=\mathrm{Nag\_NotRightVecs}$, v is not referenced.

12:  $\mathbf{pdv}$ – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array v.

Constraints:

• if $\mathbf{order}=\mathrm{Nag\_ColMajor}$,
  • if $\mathbf{jobv}=\mathrm{Nag\_RightVecs}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{n}\right)$;
  • if $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{mv}\right)$;
  • otherwise $\mathbf{pdv}\ge 1$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$,
  • if $\mathbf{jobv}=\mathrm{Nag\_RightVecs}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{n}\right)$;
  • if $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{n}\right)$;
  • otherwise $\mathbf{pdv}\ge 1$.

13:  $\mathbf{work}\left[\mathbf{lwork}\right]$ – doubleCommunication Array

On entry: if $\mathbf{jobu}=\mathrm{Nag\_LeftVecsCtol}$, $\mathbf{work}\left[0\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}\times \epsilon$. It is required that $\mathit{ctol}\ge 1$, i.e., it is not possible to force the function 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{work}\left[0\right]$

the scaling factor, $\alpha$, such that ${\sigma }_{\mathit{i}}=\alpha \mathbf{sva}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,n$ are the computed singular values of $A$. (See description of sva.)

$\mathbf{work}\left[1\right]$

$\mathrm{nint}\left(\mathbf{work}\left[1\right]\right)$gives the number of the computed nonzero singular values.

$\mathbf{work}\left[2\right]$

$\mathrm{nint}\left(\mathbf{work}\left[2\right]\right)$ gives the number of the computed singular values that are larger than the underflow threshold.

$\mathbf{work}\left[3\right]$

$\mathrm{nint}\left(\mathbf{work}\left[3\right]\right)$ gives the number of iterations (sweeps of Jacobi rotations) needed for numerical convergence.

$\mathbf{work}\left[4\right]$

${\max }_{i\ne j}\left|\cos \left(A\left(:,i\right),A\left(:,j\right)\right)\right|$ in the last iteration (sweep). This is useful information in cases when nag_dgesvj (f08kjc) did not converge, as it can be used to estimate whether the output is still useful and for subsequent analysis.

$\mathbf{work}\left[5\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}=\mathrm{Nag\_LeftVecsCtol}$, $\mathbf{work}\left[0\right]\ge 1.0$.

14:  $\mathbf{lwork}$ – IntegerInput

On entry: the dimension of the array work.

Constraint: $\mathbf{lwork}\ge \max \left(6,\mathbf{m}+\mathbf{n}\right)$.

15:  $\mathbf{fail}$ – NagError *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.
See Section 3.2.1.2 in the Essential Introduction for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_CONVERGENCE

nag_dgesvj (f08kjc) did not converge in the allowed number of iterations ($30$), but its output might still be useful.

NE_ENUM_INT_2

On entry, $\mathbf{jobv}=〈\mathit{\text{value}}〉$, $\mathbf{pdv}=〈\mathit{\text{value}}〉$, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{jobv}=\mathrm{Nag\_RightVecs}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{n}\right)$;
if $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{n}\right)$;
otherwise $\mathbf{pdv}\ge 1$.

NE_ENUM_INT_3

On entry, $\mathbf{jobv}=〈\mathit{\text{value}}〉$, $\mathbf{n}=〈\mathit{\text{value}}〉$, $\mathbf{mv}=〈\mathit{\text{value}}〉$ and $\mathbf{pdv}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{jobv}=\mathrm{Nag\_RightVecs}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{n}\right)$;
if $\mathbf{jobv}=\mathrm{Nag\_RightVecsMV}$, $\mathbf{pdv}\ge \max \left(1,\mathbf{mv}\right)$;
otherwise $\mathbf{pdv}\ge 1$.

NE_ENUM_REAL_1

On entry, $\mathbf{jobu}=〈\mathit{\text{value}}〉$ and $\mathbf{work}\left[0\right]=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{jobu}=\mathrm{Nag\_LeftVecsCtol}$, $\mathbf{work}\left[0\right]\ge 1.0$.

NE_INT

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge 0$.

On entry, $\mathbf{pda}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pda}>0$.

On entry, $\mathbf{pdv}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdv}>0$.

NE_INT_2

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge \mathbf{n}\ge 0$.

On entry, $\mathbf{pda}=〈\mathit{\text{value}}〉$ and $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pda}\ge \max \left(1,\mathbf{m}\right)$.

On entry, $\mathbf{pda}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pda}\ge \max \left(1,\mathbf{n}\right)$.

NE_INT_3

On entry, $\mathbf{lwork}=〈\mathit{\text{value}}〉$, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lwork}\ge \max \left(6,\mathbf{m}+\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.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f08kjce.c)

10.2  Program Data

Program Data (f08kjce.d)

10.3  Program Results

Program Results (f08kjce.r)