Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 12/16/2022
Public

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

Document Table of Contents

?orcsd/?uncsd

Computes the CS decomposition of a block-partitioned orthogonal/unitary matrix.

Syntax

lapack_int LAPACKE_sorcsd( int matrix_layout, char jobu1, char jobu2, char jobv1t, char jobv2t, char trans, char signs, lapack_int m, lapack_int p, lapack_int q, float* x11, lapack_int ldx11, float* x12, lapack_int ldx12, float* x21, lapack_int ldx21, float* x22, lapack_int ldx22, float* theta, float* u1, lapack_int ldu1, float* u2, lapack_int ldu2, float* v1t, lapack_int ldv1t, float* v2t, lapack_int ldv2t );

lapack_int LAPACKE_dorcsd( int matrix_layout, char jobu1, char jobu2, char jobv1t, char jobv2t, char trans, char signs, lapack_int m, lapack_int p, lapack_int q, double* x11, lapack_int ldx11, double* x12, lapack_int ldx12, double* x21, lapack_int ldx21, double* x22, lapack_int ldx22, double* theta, double* u1, lapack_int ldu1, double* u2, lapack_int ldu2, double* v1t, lapack_int ldv1t, double* v2t, lapack_int ldv2t );

lapack_int LAPACKE_cuncsd( int matrix_layout, char jobu1, char jobu2, char jobv1t, char jobv2t, char trans, char signs, lapack_int m, lapack_int p, lapack_int q, lapack_complex_float* x11, lapack_int ldx11, lapack_complex_float* x12, lapack_int ldx12, lapack_complex_float* x21, lapack_int ldx21, lapack_complex_float* x22, lapack_int ldx22, float* theta, lapack_complex_float* u1, lapack_int ldu1, lapack_complex_float* u2, lapack_int ldu2, lapack_complex_float* v1t, lapack_int ldv1t, lapack_complex_float* v2t, lapack_int ldv2t );

lapack_int LAPACKE_zuncsd( int matrix_layout, char jobu1, char jobu2, char jobv1t, char jobv2t, char trans, char signs, lapack_int m, lapack_int p, lapack_int q, lapack_complex_double* x11, lapack_int ldx11, lapack_complex_double* x12, lapack_int ldx12, lapack_complex_double* x21, lapack_int ldx21, lapack_complex_double* x22, lapack_int ldx22, double* theta, lapack_complex_double* u1, lapack_int ldu1, lapack_complex_double* u2, lapack_int ldu2, lapack_complex_double* v1t, lapack_int ldv1t, lapack_complex_double* v2t, lapack_int ldv2t );

Include Files
  • mkl.h
Description

The routines ?orcsd/?uncsd compute the CS decomposition of an m-by-m partitioned orthogonal matrix X:

Equation

or unitary matrix:

Equation

x11 is p-by-q. The orthogonal/unitary matrices u1, u2, v1, and v2 are p-by-p, (m-p)-by-(m-p), q-by-q, (m-q)-by-(m-q), respectively. C and S are r-by-r nonnegative diagonal matrices satisfying C2 + S2 = I, in which r = min(p,m-p,q,m-q).

Input Parameters
matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

jobu1

If equals Y, then u1 is computed. Otherwise, u1 is not computed.

jobu2

If equals Y, then u2 is computed. Otherwise, u2 is not computed.

jobv1t

If equals Y, then v1t is computed. Otherwise, v1t is not computed.

jobv2t

If equals Y, then v2t is computed. Otherwise, v2t is not computed.

trans
= 'T':
x, u1, u2, v1t, v2t are stored in row-major order.
otherwise
x, u1, u2, v1t, v2t are stored in column-major order.
signs
= 'O':
The lower-left block is made nonpositive (the "other" convention).
otherwise
The upper-right block is made nonpositive (the "default" convention).
m

The number of rows and columns of the matrix X.

p

The number of rows in x11 and x12. 0 pm.

q

The number of columns in x11 and x21. 0 qm.

x11, x12, x21, x22

Arrays of size x11 (ldx11,q), x12 (ldx12,m - q), x21 (ldx21,q), and x22 (ldx22,m - q).

Contain the parts of the orthogonal/unitary matrix whose CSD is desired.

ldx11, ldx12, ldx21, ldx22

The leading dimensions of the parts of array X. ldx11 max(1, p), ldx12 max(1, p), ldx21 max(1, m - p), ldx22 max(1, m - p).

ldu1

The leading dimension of the array u1. If jobu1 = 'Y', ldu1 max(1,p).

ldu2

The leading dimension of the array u2. If jobu2 = 'Y', ldu2 max(1,m-p).

ldv1t

The leading dimension of the array v1t. If jobv1t = 'Y', ldv1t max(1,q).

ldv2t

The leading dimension of the array v2t. If jobv2t = 'Y', ldv2t max(1,m-q).

Output Parameters
theta

Array, size r, in which r = min(p,m-p,q,m-q).

C = diag( cos(theta[0]), ..., cos(theta[r - 1]) ), and

S = diag( sin(theta[0]), ..., sin(theta[r - 1]) ).

u1

Array, size at least max(1, ldu1*p).

If jobu1 = 'Y', u1 contains the p-by-p orthogonal/unitary matrix u1.

u2

Array, size at least max(1, ldu2*(m - p)).

If jobu2 = 'Y', u2 contains the (m-p)-by-(m-p) orthogonal/unitary matrix u2.

v1t

Array, size at least max(1, ldv1t*q) .

If jobv1t = 'Y', v1t contains the q-by-q orthogonal matrix v1T or unitary matrix v1H.

v2t

Array, size at least max(1, ldv2t*(m - q)).

If jobv2t = 'Y', v2t contains the (m-q)-by-(m-q) orthogonal matrix v2T or unitary matrix v2H.

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.

> 0: ?orcsd/?uncsd did not converge.

See Also