Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

Contents

?gesvd

Computes the singular value decomposition of a general rectangular matrix.

Syntax

lapack_int LAPACKE_sgesvd
(
int
matrix_layout
,
char
jobu
,
char
jobvt
,
lapack_int
m
,
lapack_int
n
,
float*
a
,
lapack_int
lda
,
float*
s
,
float*
u
,
lapack_int
ldu
,
float*
vt
,
lapack_int
ldvt
,
float*
superb
);
lapack_int LAPACKE_dgesvd
(
int
matrix_layout
,
char
jobu
,
char
jobvt
,
lapack_int
m
,
lapack_int
n
,
double*
a
,
lapack_int
lda
,
double*
s
,
double*
u
,
lapack_int
ldu
,
double*
vt
,
lapack_int
ldvt
,
double*
superb
);
lapack_int LAPACKE_cgesvd
(
int
matrix_layout
,
char
jobu
,
char
jobvt
,
lapack_int
m
,
lapack_int
n
,
lapack_complex_float*
a
,
lapack_int
lda
,
float*
s
,
lapack_complex_float*
u
,
lapack_int
ldu
,
lapack_complex_float*
vt
,
lapack_int
ldvt
,
float*
superb
);
lapack_int LAPACKE_zgesvd
(
int
matrix_layout
,
char
jobu
,
char
jobvt
,
lapack_int
m
,
lapack_int
n
,
lapack_complex_double*
a
,
lapack_int
lda
,
double*
s
,
lapack_complex_double*
u
,
lapack_int
ldu
,
lapack_complex_double*
vt
,
lapack_int
ldvt
,
double*
superb
);
Include Files
  • mkl.h
Description
The routine computes the singular value decomposition (SVD) of a real/complex
m
-by-
n
 matrix
A
, optionally computing the left and/or right singular vectors. The SVD is written as
A
 =
U
*
Σ
*
V
T
 for real routines
A
 =
U
*
Σ
*
V
H
 for complex routines
where
Σ
 is an
m
-by-
n
 matrix which is zero except for its min(
m
,
n
) diagonal elements,
U
 is an
m
-by-
m
 orthogonal/unitary matrix, and
V
 is an
n
-by-
n
 orthogonal/unitary matrix. The diagonal elements of
Σ
 are the singular values of
A
; they are real and non-negative, and are returned in descending order. The first min(
m
,
n
) columns of
U
 and
V
 are the left and right singular vectors of
A
.
The routine returns
V
T
 (for real flavors) or
V
H
 (for complex flavors), not
V
.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
jobu
Must be
'A'
,
'S'
,
'O'
, or
'N'
. Specifies options for computing all or part of the matrix
U
.
If
jobu
 =
'A'
, all
m
 columns of
U
 are returned in the array
u
;
if
jobu
 =
'S'
, the first min(
m
,
n
) columns of
U
 (the left singular vectors) are returned in the array
u
;
if
jobu
 =
'O'
, the first min(
m
,
n
) columns of
U
 (the left singular vectors) are overwritten on the array
a
;
if
jobu
 =
'N'
, no columns of
U
 (no left singular vectors) are computed.
jobvt
Must be
'A'
,
'S'
,
'O'
, or
'N'
. Specifies options for computing all or part of the matrix
V
T
/
V
H
.
If
jobvt
 =
'A'
, all
n
 rows of
V
T
/
V
H
 are returned in the array
vt
;
if
jobvt
 =
'S'
, the first min(
m
,
n
) rows of
V
T
/
V
H
 (the right singular vectors) are returned in the array
vt
;
if
jobvt
 =
'O'
, the first min(
m
,
n
) rows of
V
T
/
V
H
) (the right singular vectors) are overwritten on the array
a
;
if
jobvt
 =
'N'
, no rows of
V
T
/
V
H
 (no right singular vectors) are computed.
jobvt
 and
jobu
 cannot both be
'O'
.
m
The number of rows of the matrix
A
 (
m
≥
 0
).
n
The number of columns in
A
 (
n
≥
 0
).
a
Arrays:
a
(size at least max(1,
lda
*
n
) for column major layout and max(1,
lda
*
m
) for row major layout)
 is an array containing the
m
-by-
n
 matrix
A
.
lda
The leading dimension of the array
a
.
Must be at least max(1,
m
)
for column major layout and at least max(1,
n
) for row major layout
 .
ldu
,
ldvt
The leading dimensions of the output arrays
u
 and
vt
, respectively.
Constraints:
ldu
≥
 1;
ldvt
≥
 1
.
If
jobu
 =
'A'
,
ldu
≥
m
;
If
jobu
 =
'S'
,
ldu
≥
m
 for column major layout and
ldu
≥
 min(
m
,
n
) for row major layout;
If
jobvt
 =
'A'
,
ldvt
≥
n
;
If
jobvt
 =
'S'
,
ldvt
≥
 min
(
m
,
n
)
for column major layout and
ldvt
≥
n
 for row major layout
 .
Output Parameters
a
On exit,
If
jobu
 =
'O'
,
a
 is overwritten with the first min(
m
,
n
) columns of
U
 (the left singular vectors stored columnwise);
If
jobvt
 =
'O'
,
a
 is overwritten with the first min(
m
,
n
) rows of
V
T
/
V
H
 (the right singular vectors stored rowwise);
If
jobu
≠
'O'
 and
jobvt
≠
'O'
, the contents of
a
 are destroyed.
s
Array, size at least max(1, min(
m
,
n
)). Contains the singular values of
A
 sorted so that
s
[
i
]
≥
 
s
[
i
 + 1]
.
u
,
vt
Arrays:
Array
u
 minimum size:
Column major layout
Row major layout
jobu
 =
'A'
max(1,
ldu
*
m
)
max(1,
ldu
*
m
)
jobu
 =
'S'
max(1,
ldu
*min(
m
,
n
))
max(1,
ldu
*
m
)
If
jobu
 =
'A'
,
u
 contains the
m
-by-
m
 orthogonal/unitary matrix
U
.
If
jobu
 =
'S'
,
u
 contains the first min(
m
,
n
) columns of
U
 (the left singular vectors stored column-wise).
If
jobu
 =
'N'
 or
'O'
,
u
 is not referenced.
Array
v
 minimum size:
Column major layout
Row major layout
jobvt
 =
'A'
max(1,
ldvt
*
n
)
max(1,
ldvt
*
n
)
jobvt
 =
'S'
max(1,
ldvt
*min(
m
,
n
))
max(1,
ldvt
*
n
)
If
jobvt
 =
'A'
,
vt
 contains the
n
-by-
n
 orthogonal/unitary matrix
V
T
/
V
H
.
If
jobvt
 =
'S'
,
vt
 contains the first min(
m
,
n
) rows of
V
T
/
V
H
 (the right singular vectors stored row-wise).
If
jobvt
 =
'N'
or
'O'
,
vt
 is not referenced.
superb
If
?bdsqr
 does not converge (indicated by the return value
info
 > 0
), on exit
superb
(0:min(
m
,
n
)-2)
 contains the unconverged superdiagonal elements of an upper bidiagonal matrix
B
 whose diagonal is in
s
 (not necessarily sorted).
B
 satisfies
A
 =
u
*
B
*
V
T
 (real flavors) or
A
 =
u
*
B
*
V
H
 (complex flavors), so it has the same singular values as
A
, and singular vectors related by
u
 and
vt
.
Return Values
This function returns a value
info
.
If
info
 = 0
, the execution is successful.
If
info
 =
-i
, the
i
-th parameter had an illegal value.
If
info
 =
i
, then if
?bdsqr
 did not converge,
i
 specifies how many superdiagonals of the intermediate bidiagonal form
B
 did not converge to zero (see the description of the
superb
 parameter for details).

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.