?orcsd/?uncsd

Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

Download PDF

ID 766686

Date 3/31/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-D82ECBB0-F5BF-43DA-BBC8-C96C28EF9D3B

View Details

?orcsd/?uncsd

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

Syntax

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 )

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] )

Include Files

mkl.fi, lapack.f90

Description

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

or unitary matrix:

x₁₁ is p-by-q. The orthogonal/unitary matrices u₁, u₂, v₁, and v₂ 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 C² + S² = I, in which r = min(p,m-p,q,m-q).

Input Parameters

jobu1

CHARACTER. If equals Y, then u₁ is computed. Otherwise, u₁ is not computed.

jobu2

CHARACTER. If equals Y, then u₂ is computed. Otherwise, u₂ is not computed.

jobv1t

CHARACTER. If equals Y, then v₁^t is computed. Otherwise, v₁^t is not computed.

jobv2t

CHARACTER. If equals Y, then v₂^t is computed. Otherwise, v₂^t is not computed.

trans

CHARACTER

= 'T':: x, u₁, u₂, v₁^t, v₂^t are stored in row-major order.
otherwise: x, u₁, u₂, v₁^t, v₂^t 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₁₁ and x₁₂. 0 ≤p≤m.

q

INTEGER. The number of columns in x₁₁ and x₂₁. 0 ≤q≤m.

x11, x12, x21, x22

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

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

INTEGER. 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

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

ldu2

INTEGER. The leading dimension of the array u₂. 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, size (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, size (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, size (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, size (p).

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

u2

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, size (ldu2,m-p).

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

v1t

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, size (ldv1t,*) .

If jobv1t = 'Y', v1t contains the q-by-q orthogonal matrix v₁^T or unitary matrix v₁^H.

v2t

REAL for sorcsd

DOUBLE PRECISION for dorcsd

COMPLEX for cuncsd

DOUBLE COMPLEX for zuncsd

Array, size (ldv2t,m-q).

If jobv2t = 'Y', v2t contains the (m-q)-by-(m-q) orthogonal matrix v₂^T or unitary matrix v₂^H.

work

On exit,

If info = 0,: work(1) returns the optimal lwork.
If info > 0,: For ?orcsd, 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,: For ?uncsd, 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: ?orcsd/?uncsd 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 u₁ is computed. Must be 'Y' or 'O'.
jobsu2: Indicates whether u₂ is computed. Must be 'Y' or 'O'.
jobv1t: Indicates whether v₁^t is computed. Must be 'Y' or 'O'.
jobv2t: Indicates whether v₂^t is computed. Must be 'Y' or 'O'.
trans: Must be 'N' or 'T'.
signs: Must be 'O' or 'D'.

Parent topic: Cosine-Sine Decomposition: LAPACK Driver 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 Fortran

?orcsd/?uncsd

See Also