NAG Library Function Document

nag_zgesdd (f08krc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     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 Nag_ColMajor.

2:     job – Nag_JobTypeInput

On entry: specifies options for computing all or part of the matrix $U$.

$\mathbf{job}=\mathrm{Nag\_DoAll}$

All $m$ columns of $U$ and all $n$ rows of $V^{\mathrm{H}}$ are returned in the arrays u and vt.

$\mathbf{job}=\mathrm{Nag\_DoSquare}$

The first $\min \left(m,n\right)$ columns of $U$ and the first $\min \left(m,n\right)$ rows of $V^{\mathrm{H}}$ are returned in the arrays u and vt.

$\mathbf{job}=\mathrm{Nag\_DoOverwrite}$

If $\mathbf{m}\ge \mathbf{n}$, the first $n$ columns of $U$ are overwritten on the array a and all rows of $V^{\mathrm{H}}$ are returned in the array vt. Otherwise, all columns of $U$ are returned in the array u and the first $m$ rows of $V^{\mathrm{H}}$ are overwritten in the array vt.

$\mathbf{job}=\mathrm{Nag\_DoNothing}$

No columns of $U$ or rows of $V^{\mathrm{H}}$ are computed.

Constraint: $\mathbf{job}=\mathrm{Nag\_DoAll}$, $\mathrm{Nag\_DoSquare}$, $\mathrm{Nag\_DoOverwrite}$ or $\mathrm{Nag\_DoNothing}$.

3:     m – IntegerInput

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

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

4:     n – IntegerInput

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

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

5:     a[$\mathit{dim}$] – ComplexInput/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: if $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$, a is overwritten with the first $n$ columns of $U$ (the left singular vectors, stored column-wise) if $\mathbf{m}\ge \mathbf{n}$; a is overwritten with the first $m$ rows of $V^{\mathrm{H}}$ (the right singular vectors, stored row-wise) otherwise.

If $\mathbf{job}\ne \mathrm{Nag\_DoOverwrite}$, the contents of a are destroyed.

6:     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)$.

7:     s[$\min \left(\mathbf{m},\mathbf{n}\right)$] – doubleOutput

On exit: the singular values of $A$, sorted so that $\mathbf{s}\left[i-1\right]\ge \mathbf{s}\left[i\right]$.

8:     u[$\mathit{dim}$] – ComplexOutput

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

• $\max \left(1,\mathbf{pdu}\times \mathbf{m}\right)$ when $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}<\mathbf{n}$;
• $\max \left(1,\mathbf{pdu}\times \min \left(\mathbf{m},\mathbf{n}\right)\right)$ when $\mathbf{job}=\mathrm{Nag\_DoSquare}$ and $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\max \left(1,\mathbf{m}\times \mathbf{pdu}\right)$ when $\mathbf{job}=\mathrm{Nag\_DoSquare}$ 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)\times \mathbf{pdu}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{u}\left[\left(i-1\right)\times \mathbf{pdu}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

On exit:

If $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}<\mathbf{n}$, u contains the $m$ by $m$ matrix $U$.

If $\mathbf{job}=\mathrm{Nag\_DoSquare}$, u contains the first $\min \left(m,n\right)$ columns of $U$ (the left singular vectors, stored column-wise).

If $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}\ge \mathbf{n}$, or $\mathbf{job}=\mathrm{Nag\_DoNothing}$, u is not referenced.

9:     pdu – IntegerInput

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{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}<\mathbf{n}$, $\mathbf{pdu}\ge \max \left(1,\mathbf{m}\right)$;
  • if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdu}\ge \max \left(1,\mathbf{m}\right)$;
  • otherwise $\mathbf{pdu}\ge 1$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$,
  • if $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}<\mathbf{n}$, $\mathbf{pdu}\ge \max \left(1,\mathbf{m}\right)$;
  • if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdu}\ge \max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\right)$;
  • otherwise $\mathbf{pdu}\ge 1$.

10:   vt[$\mathit{dim}$] – ComplexOutput

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

• $\max \left(1,\mathbf{pdvt}\times \mathbf{n}\right)$ when $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}\ge \mathbf{n}$;
• $\max \left(1,\mathbf{pdvt}\times \mathbf{n}\right)$ when $\mathbf{job}=\mathrm{Nag\_DoSquare}$ and $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\times \mathbf{pdvt}\right)$ when $\mathbf{job}=\mathrm{Nag\_DoSquare}$ 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)\times \mathbf{pdvt}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{vt}\left[\left(i-1\right)\times \mathbf{pdvt}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

On exit: if $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}\ge \mathbf{n}$, vt contains the $n$ by $n$ unitary matrix $V^{\mathrm{H}}$.

If $\mathbf{job}=\mathrm{Nag\_DoSquare}$, vt contains the first $\min \left(m,n\right)$ rows of $V^{\mathrm{H}}$ (the right singular vectors, stored row-wise).

If $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}<\mathbf{n}$, or $\mathbf{job}=\mathrm{Nag\_DoNothing}$, vt is not referenced.

11:   pdvt – IntegerInput

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{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}\ge \mathbf{n}$, $\mathbf{pdvt}\ge \max \left(1,\mathbf{n}\right)$;
  • if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdvt}\ge \max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\right)$;
  • otherwise $\mathbf{pdvt}\ge 1$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$,
  • if $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}\ge \mathbf{n}$, $\mathbf{pdvt}\ge \max \left(1,\mathbf{n}\right)$;
  • if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdvt}\ge \max \left(1,\mathbf{n}\right)$;
  • otherwise $\mathbf{pdvt}\ge 1$.

12:   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.

NE_BAD_PARAM

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

NE_CONVERGENCE

nag_zgesdd (f08krc) did not converge, the updating process failed.

NE_ENUM_INT_3

On entry, $\mathbf{job}=〈\mathit{\text{value}}〉$, $\mathbf{pdu}=〈\mathit{\text{value}}〉$, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}<\mathbf{n}$, $\mathbf{pdu}\ge \max \left(1,\mathbf{m}\right)$;
if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdu}\ge \max \left(1,\mathbf{m}\right)$;
otherwise $\mathbf{pdu}\ge 1$.

On entry, $\mathbf{job}=〈\mathit{\text{value}}〉$, $\mathbf{pdu}=〈\mathit{\text{value}}〉$, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}<\mathbf{n}$, $\mathbf{pdu}\ge \max \left(1,\mathbf{m}\right)$;
if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdu}\ge \max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\right)$;
otherwise $\mathbf{pdu}\ge 1$.

On entry, $\mathbf{job}=〈\mathit{\text{value}}〉$, $\mathbf{pdvt}=〈\mathit{\text{value}}〉$, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}\ge \mathbf{n}$, $\mathbf{pdvt}\ge \max \left(1,\mathbf{n}\right)$;
if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdvt}\ge \max \left(1,\min \left(\mathbf{m},\mathbf{n}\right)\right)$;
otherwise $\mathbf{pdvt}\ge 1$.

On entry, $\mathbf{job}=〈\mathit{\text{value}}〉$, $\mathbf{pdvt}=〈\mathit{\text{value}}〉$, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{job}=\mathrm{Nag\_DoAll}$ or $\mathbf{job}=\mathrm{Nag\_DoOverwrite}$ and $\mathbf{m}\ge \mathbf{n}$, $\mathbf{pdvt}\ge \max \left(1,\mathbf{n}\right)$;
if $\mathbf{job}=\mathrm{Nag\_DoSquare}$, $\mathbf{pdvt}\ge \max \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 \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_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

8  Further Comments

9  Example

9.1  Program Text

Program Text (f08krce.c)

9.2  Program Data

Program Data (f08krce.d)

9.3  Program Results

Program Results (f08krce.r)