?bdsqr

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-3E51F1C1-B9F4-4531-A2DC-C6F648705E8C

View Details

?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² if only the singular values are computed. About 6n²*nru additional operations (12n²*nru for complex flavors) are required to compute the left singular vectors and about 6n²*ncvt operations (12n²*ncvt for complex flavors) to compute the right singular vectors.

Parent topic: Singular Value Decomposition: LAPACK Computational Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

?bdsqr

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values

Application Notes