Developer Reference for Intel® oneAPI Math Kernel Library - C

Developer Reference

  • 2021.1
  • 12/04/2020
  • Public Content
Contents

?bdsqr

Computes the singular value decomposition of a general matrix that has been reduced to bidiagonal form.

Syntax

lapack_int LAPACKE_sbdsqr
(
int
matrix_layout
,
char
uplo
,
lapack_int
n
,
lapack_int
ncvt
,
lapack_int
nru
,
lapack_int
ncc
,
float*
d
,
float*
e
,
float*
vt
,
lapack_int
ldvt
,
float*
u
,
lapack_int
ldu
,
float*
c
,
lapack_int
ldc
);
lapack_int LAPACKE_dbdsqr
(
int
matrix_layout
,
char
uplo
,
lapack_int
n
,
lapack_int
ncvt
,
lapack_int
nru
,
lapack_int
ncc
,
double*
d
,
double*
e
,
double*
vt
,
lapack_int
ldvt
,
double*
u
,
lapack_int
ldu
,
double*
c
,
lapack_int
ldc
);
lapack_int LAPACKE_cbdsqr
(
int
matrix_layout
,
char
uplo
,
lapack_int
n
,
lapack_int
ncvt
,
lapack_int
nru
,
lapack_int
ncc
,
float*
d
,
float*
e
,
lapack_complex_float*
vt
,
lapack_int
ldvt
,
lapack_complex_float*
u
,
lapack_int
ldu
,
lapack_complex_float*
c
,
lapack_int
ldc
);
lapack_int LAPACKE_zbdsqr
(
int
matrix_layout
,
char
uplo
,
lapack_int
n
,
lapack_int
ncvt
,
lapack_int
nru
,
lapack_int
ncc
,
double*
d
,
double*
e
,
lapack_complex_double*
vt
,
lapack_int
ldvt
,
lapack_complex_double*
u
,
lapack_int
ldu
,
lapack_complex_double*
c
,
lapack_int
ldc
);
Include Files
  • mkl.h
Description
The routine computes the singular values and, optionally, the right and/or left singular vectors from the Singular Value Decomposition (SVD) of a real
n
-by-
n
 (upper or lower) bidiagonal matrix
B
 using the implicit zero-shift
QR
 algorithm. The SVD of
B
 has the form
B
 =
Q
*
S
*
P
H
 where
S
 is the diagonal matrix of singular values,
Q
 is an orthogonal matrix of left singular vectors, and
P
 is an orthogonal matrix of right singular vectors. If left singular vectors are requested, this subroutine actually returns
U
 *
Q
 instead of
Q
, and, if right singular vectors are requested, this subroutine returns
P
H
 *
VT
 instead of
P
H
, for given real/complex input matrices
U
 and
VT
. When
U
 and
VT
 are the orthogonal/unitary matrices that reduce a general matrix
A
 to bidiagonal form:
A
 =
U
*
B
*
VT
, as computed by
?gebrd
, then
A
 = (
U
*
Q
)*
S
*(
P
H
*
VT
)
is the SVD of
A
. Optionally, the subroutine may also compute
Q
H
 *
C
 for a given real/complex input matrix
C
.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
uplo
Must be
'U'
 or
'L'
.
If
uplo
 =
'U'
,
B
 is an upper bidiagonal matrix.
If
uplo
 =
'L'
,
B
 is a lower bidiagonal matrix.
n
The order of the matrix
B
 (
n
≥
 0
).
ncvt
The number of columns of the matrix
VT
, that is, the number of right singular vectors (
ncvt
≥
 0
).
Set
ncvt
 = 0
 if no right singular vectors are required.
nru
The number of rows in
U
, that is, the number of left singular vectors (
nru
≥
 0
).
Set
nru
 = 0
 if no left singular vectors are required.
ncc
The number of columns in the matrix
C
 used for computing the product
Q
H
*
C
 (
ncc
≥
 0
). Set
ncc
 = 0
 if no matrix
C
 is supplied.
d
,
e
Arrays:
d
 contains the diagonal elements of
B
.
The size of
d
 must be at least
max(1,
n
)
.
e
 contains the
(
n
-1)
 off-diagonal elements of
B
.
The size of
e
 must be at least
max(1,
n
 - 1)
.
vt
,
u
,
c
Arrays:
vt
, size max(1,
ldvt
*
ncvt
) for column major layout and max(1,
ldvt
*
n
) for row major layout,
 contains an
n
-by-
ncvt
 matrix
VT
.
vt
 is not referenced if
ncvt
 = 0
.
u
, size max(1,
ldu
*
n
) for column major layout and max(1,
ldu
*
nru
) for row major layout,
contains an
nru
 by
n
 matrix
U
.
u
 is not referenced if
nru
 = 0
.
c
, size max(1,
ldc
*
ncc
) for column major layout and max(1,
ldc
*
n
) for row major layout,
 contains the
n
-by-
ncc
 matrix
C
 for computing the product
Q
H
*
C
.
ldvt
The leading dimension of
vt
. Constraints:
ldvt
≥
 max(1,
n
)
 if
ncvt
 > 0
for column major layout and
ldvt
≥
 max(1,
ncvt
) for row major layout
;
ldvt
≥
 1
 if
ncvt
 = 0
.
ldu
The leading dimension of
u
. Constraint:
ldu
≥
 max(1,
nru
)
for column major layout and
ldu
≥
 max(1,
n
) for row major layout
 .
ldc
The leading dimension of
c
. Constraints:
ldc
≥
 max(1,
n
) if
ncc
 > 0
for column major layout and
ldc
≥
 max(1,
ncc
)
 for row major layout
;
ldc
≥
 1 otherwise.
Output Parameters
d
On exit, if
info
 = 0
, overwritten by the singular values in decreasing order (see
info
).
e
On exit, if
info
 = 0
,
e
 is destroyed. See also
info
 below.
c
Overwritten by the product
Q
H
*
C
.
vt
On exit, this array is overwritten by
P
H
 *
VT
. Not referenced if
ncvt
 = 0.
u
On exit, this array is overwritten by
U
 *
Q
. Not referenced if
nru
 = 0.
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
 > 0
,
If
ncvt
 =
nru
 =
ncc
 = 0
,
  • info
     = 1
    , a split was marked by a positive value in
    e
  • info
     = 2
    , the current block of
    z
     not diagonalized after 100*
    n
     iterations (in the inner
    while
     loop)
  • info
     = 3
    , termination criterion of the outer
    while
     loop is not met (the program created more than
    n
     unreduced blocks).
In all other cases when
ncvt
,
nru
, or
ncc
 > 0
, the algorithm did not converge;
d
 and
e
 contain the elements of a bidiagonal matrix that is orthogonally similar to the input matrix
B
; if
info
 =
i
,
i
 elements of
e
 have not converged to zero.
Application Notes
Each singular value and singular vector is computed to high relative accuracy. However, the reduction to bidiagonal form (prior to calling the routine) may decrease the relative accuracy in the small singular values of the original matrix if its singular values vary widely in magnitude.
If
s
i
 is an exact singular value of
B
, and
s
i
 is the corresponding computed value, then
|
s
i
 -
σ
i
|
≤
p
*(
m
,
n
)*
ε
*
σ
i
where
p
(
m
,
n
) is a modestly increasing function of
m
 and
n
, and
ε
 is the machine precision.
If only singular values are computed, they are computed more accurately than when some singular vectors are also computed (that is, the function
p
(
m
,
n
) is smaller).
If
u
i
 is the corresponding exact left singular vector of
B
, and
w
i
 is the corresponding computed left singular vector, then the angle
θ
(
u
i
,
w
i
) between them is bounded as follows:
θ
(
u
i
,
w
i
)
≤
p
(
m
,
n
)*
ε
 / min
i
≠
j
(|
σ
i
 -
σ
j
|/|
σ
i
 +
σ
j
|)
.
Here
min
i
≠
j
(|
σ
i
 -
σ
j
|/|
σ
i
 +
σ
j
|)
 is the
relative gap
 between
σ
i
 and the other singular values. A similar error bound holds for the right singular vectors.
The total number of real floating-point operations is roughly proportional to
n
2
 if only the singular values are computed. About
6
n
2
*
nru
 additional operations (
12
n
2
*
nru
 for complex flavors) are required to compute the left singular vectors and about
6
n
2
*
ncvt
 operations (
12
n
2
*
ncvt
 for complex flavors) to compute the right singular vectors.

Product and Performance Information

1

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