?orcsd/?uncsd

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

Syntax

FORTRAN 77:

call sorcsd( jobu1, jobu2, jobv1t, jobv2t, trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, v2t, ldv2t, work, lwork, iwork, info )

call dorcsd( jobu1, jobu2, jobv1t, jobv2t, trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, v2t, ldv2t, work, lwork, iwork, info )

call cuncsd( jobu1, jobu2, jobv1t, jobv2t, trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, v2t, ldv2t, work, lwork, rwork, lrwork, iwork, info )

call zuncsd( jobu1, jobu2, jobv1t, jobv2t, trans, signs, m, p, q, x11, ldx11, x12, ldx12, x21, ldx21, x22, ldx22, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, v2t, ldv2t, work, lwork, rwork, lrwork, iwork, info )

FORTRAN 95:

call orcsd( x11,x12,x21,x22,theta,u1,u2,v1t,v2t[,jobu1][,jobu2][,jobv1t][,jobv2t][,trans][,signs][,info] )

call uncsd( x11,x12,x21,x22,theta,u1,u2,v1t,v2t[,jobu1][,jobu2][,jobv1t][,jobv2t][,trans][,signs][,info] )

C:

lapack_int LAPACKE_sorcsd( int matrix_order, 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_order, 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_order, 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_order, 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

Description

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

Equation

or unitary matrix:

Equation

x 11 is p-by-q. The orthogonal/unitary matrices u1, u2, v1, and v 2 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

The data types are given for the Fortran interface. A <datatype> placeholder, if present, is used for the C interface data types in the C interface section above. See C Interface Conventions for the C interface principal conventions and type definitions.

jobu1

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

jobu2

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

jobv1t

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

jobv2t

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

trans

CHARACTER

= '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

CHARACTER

= 'O':
The lower-left block is made nonpositive (the "other" convention).
otherwise
The upper-right block is made nonpositive (the "default" convention).
m

INTEGER. The number of rows and columns of the matrix X.

p

INTEGER. The number of rows in x 11 and x12. 0 ≤ p ≤ m.

q

INTEGER. The number of columns in x 11 and x21. 0 ≤ q ≤ m.

x

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, DIMENSION (ldx,m).

On entry, the orthogonal/unitary matrix whose CSD is desired.

ldx

INTEGER. The leading dimension of the array X. ldx ≥ max(1,m).

ldu1

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

ldu2

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

ldv1t

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

ldv2t

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

work

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Workspace array, DIMENSION (max(1,lwork)).

lwork

INTEGER. The size of the work array. Constraints:

If lwork = -1, then a workspace query is assumed; the routine only calculates the optimal size of the work array, returns this value as the first entry of the work array, and no error message related to lwork is issued by xerbla.

rwork

REAL for cuncsd

DOUBLE PRECISION for zuncsd

Workspace array, DIMENSION (max(1,lrwork)).

lrwork

INTEGER. The size of the rwork array. Constraints:

If lrwork = -1, then a workspace query is assumed; the routine only calculates the optimal size of the rwork array, returns this value as the first entry of the rwork array, and no error message related to lrwork is issued by xerbla.

iwork

INTEGER. Workspace array, dimension m.

Output Parameters

theta

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

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

C = diag( cos(theta(1)), ..., cos(theta(r)) ), and

S = diag( sin(theta(1)), ..., sin(theta(r)) ).

u1

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, DIMENSION (p).

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

u2

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, DIMENSION (ldu2,m-p).

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

v1t

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, DIMENSION (ldv1t,q).

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

v2t

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, DIMENSION (ldv2t,m-q).

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

work

On exit,

If info = 0,
work(1) returns the optimal lwork.
If info > 0,
work(2:r) contains the values phi(1), ..., phi(r-1) that, together with theta(1), ..., theta(r) define the matrix in intermediate bidiagonal-block form remaining after nonconvergence. info specifies the number of nonzero phi's.
rwork

On exit,

If info = 0,
rwork(1) returns the optimal lrwork.
If info > 0,
rwork(2:r) contains the values phi(1), ..., phi(r-1) that, together with theta(1), ..., theta(r) define the matrix in intermediate bidiagonal-block form remaining after nonconvergence. info specifies the number of nonzero phi's.
info

INTEGER.

= 0: successful exit

< 0: if info = -i, the i-th argument has an illegal value

> 0: ?bbcsd did not converge. See the description of work above for details.

Fortran 95 Interface Notes

Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or reconstructible arguments, see Fortran 95 Interface Conventions.

Specific details for the routine ?orcsd/?uncsd interface are as follows:

x11

Holds the block of matrix X of size (p, q).

x12

Holds the block of matrix X of size (p, m-q).

x21

Holds the block of matrix X of size (m-p, q).

x22

Holds the block of matrix X of size (m-p, m-q).

theta

Holds the vector of length r = min(p,m-p,q,m-q).

u1

Holds the matrix of size (p,p).

u2

Holds the matrix of size (m-p,m-p).

v1t

Holds the matrix of size (q,q).

v2t

Holds the matrix of size (m-q,m-q).

jobsu1

Indicates whether u1 is computed. Must be 'Y' or 'O'.

jobsu2

Indicates whether u2 is computed. Must be 'Y' or 'O'.

jobv1t

Indicates whether v1t is computed. Must be 'Y' or 'O'.

jobv2t

Indicates whether v2t is computed. Must be 'Y' or 'O'.

trans

Must be 'N' or 'T'.

signs

Must be 'O' or 'D'.

Parent topic: Cosine-Sine Decomposition

See Also

?bbcsd
xerbla

Submit feedback on this help topic