NAG FL Interface
f08rnf (zuncsd)
1
Purpose
f08rnf computes the CS decomposition of a complex by unitary matrix , partitioned into a by array of submatrices.
2
Specification
Fortran Interface
Subroutine f08rnf ( |
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) |
Integer, Intent (In) |
:: |
m, p, q, ldx11, ldx12, ldx21, ldx22, ldu1, ldu2, ldv1t, ldv2t, lwork, lrwork |
Integer, Intent (Out) |
:: |
iwork(m-min(p,m-p,q,m-q)), info |
Real (Kind=nag_wp), Intent (Out) |
:: |
theta(min(p,m-p,q,m-q)), rwork(max(1,lrwork)) |
Complex (Kind=nag_wp), Intent (Inout) |
:: |
x11(ldx11,*), x12(ldx12,*), x21(ldx21,*), x22(ldx22,*), u1(ldu1,*), u2(ldu2,*), v1t(ldv1t,*), v2t(ldv2t,*) |
Complex (Kind=nag_wp), Intent (Out) |
:: |
work(max(1,lwork)) |
Character (1), Intent (In) |
:: |
jobu1, jobu2, jobv1t, jobv2t, trans, signs |
|
C Header Interface
#include <nag.h>
void |
f08rnf_ (const char *jobu1, const char *jobu2, const char *jobv1t, const char *jobv2t, const char *trans, const char *signs, const Integer *m, const Integer *p, const Integer *q, Complex x11[], const Integer *ldx11, Complex x12[], const Integer *ldx12, Complex x21[], const Integer *ldx21, Complex x22[], const Integer *ldx22, double theta[], Complex u1[], const Integer *ldu1, Complex u2[], const Integer *ldu2, Complex v1t[], const Integer *ldv1t, Complex v2t[], const Integer *ldv2t, Complex work[], const Integer *lwork, double rwork[], const Integer *lrwork, Integer iwork[], Integer *info, const Charlen length_jobu1, const Charlen length_jobu2, const Charlen length_jobv1t, const Charlen length_jobv2t, const Charlen length_trans, const Charlen length_signs) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
f08rnf_ (const char *jobu1, const char *jobu2, const char *jobv1t, const char *jobv2t, const char *trans, const char *signs, const Integer &m, const Integer &p, const Integer &q, Complex x11[], const Integer &ldx11, Complex x12[], const Integer &ldx12, Complex x21[], const Integer &ldx21, Complex x22[], const Integer &ldx22, double theta[], Complex u1[], const Integer &ldu1, Complex u2[], const Integer &ldu2, Complex v1t[], const Integer &ldv1t, Complex v2t[], const Integer &ldv2t, Complex work[], const Integer &lwork, double rwork[], const Integer &lrwork, Integer iwork[], Integer &info, const Charlen length_jobu1, const Charlen length_jobu2, const Charlen length_jobv1t, const Charlen length_jobv2t, const Charlen length_trans, const Charlen length_signs) |
}
|
The routine may be called by the names f08rnf, nagf_lapackeig_zuncsd or its LAPACK name zuncsd.
3
Description
The
by
unitary matrix
is partitioned as
where
is a
by
submatrix and the dimensions of the other submatrices
,
and
are such that
remains
by
.
The CS decomposition of
is
where
,
and
are
by
matrices, such that
is a unitary matrix containing the
by
unitary matrix
and the
by
unitary matrix
;
is a unitary matrix containing the
by
unitary matrix
and the
by
unitary matrix
; and
contains the
by
non-negative diagonal submatrices
and
satisfying
, where
and the top left partition is
by
.
The identity matrix is of order and vanishes if .
The identity matrix is of order and vanishes if .
The identity matrix is of order and vanishes if .
The identity matrix is of order and vanishes if .
In each of the four cases at least two of the identity matrices vanish.
The indicated zeros represent augmentations by additional rows or columns (but not both) to the square diagonal matrices formed by and or .
does not need to be stored in full; it is sufficient to return only the values for where and .
The algorithm used to perform the complete
decomposition is described fully in
Sutton (2009) including discussions of the stability and accuracy of the algorithm.
4
References
Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999)
LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia
https://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (2012) Matrix Computations (4th Edition) Johns Hopkins University Press, Baltimore
Sutton B D (2009) Computing the complete
decomposition
Numerical Algorithms (Volume 50) 1017–1398 Springer US 33–65
https://dx.doi.org/10.1007/s11075-008-9215-6
5
Arguments
-
1:
– Character(1)
Input
-
On entry:
- if , is computed;
- otherwise, is not computed.
-
2:
– Character(1)
Input
-
On entry:
- if , is computed;
- otherwise, is not computed.
-
3:
– Character(1)
Input
-
On entry:
- if , is computed;
- otherwise, is not computed.
-
4:
– Character(1)
Input
-
On entry:
- if , is computed;
- otherwise, is not computed.
-
5:
– Character(1)
Input
-
On entry:
- if , , , , and are stored in row-major order;
- otherwise, , , , and are stored in column-major order.
-
6:
– Character(1)
Input
-
On entry:
- if , the lower-left block is made nonpositive (the other convention);
- otherwise, the upper-right block is made nonpositive (the default convention).
-
7:
– Integer
Input
-
On entry: , the number of rows and columns in the unitary matrix .
Constraint:
.
-
8:
– Integer
Input
-
On entry: , the number of rows in and .
Constraint:
.
-
9:
– Integer
Input
-
On entry: , the number of columns in and .
Constraint:
.
-
10:
– Complex (Kind=nag_wp) array
Input/Output
-
Note: the second dimension of the array
x11
must be at least
if
, and at least
otherwise.
On entry: the upper left partition of the unitary matrix whose CSD is desired.
On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.
-
11:
– Integer
Input
-
On entry: the first dimension of the array
x11 as declared in the (sub)program from which
f08rnf is called.
Constraints:
- if , ;
- otherwise .
-
12:
– Complex (Kind=nag_wp) array
Input/Output
-
Note: the second dimension of the array
x12
must be at least
if
, and at least
otherwise.
On entry: the upper right partition of the unitary matrix whose CSD is desired.
On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.
-
13:
– Integer
Input
-
On entry: the first dimension of the array
x12 as declared in the (sub)program from which
f08rnf is called.
Constraints:
- if , ;
- otherwise .
-
14:
– Complex (Kind=nag_wp) array
Input/Output
-
Note: the second dimension of the array
x21
must be at least
if
, and at least
otherwise.
On entry: the lower left partition of the unitary matrix whose CSD is desired.
On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.
-
15:
– Integer
Input
-
On entry: the first dimension of the array
x21 as declared in the (sub)program from which
f08rnf is called.
Constraints:
- if , ;
- otherwise .
-
16:
– Complex (Kind=nag_wp) array
Input/Output
-
Note: the second dimension of the array
x22
must be at least
if
, and at least
otherwise.
On entry: the lower right partition of the unitary matrix CSD is desired.
On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.
-
17:
– Integer
Input
-
On entry: the first dimension of the array
x22 as declared in the (sub)program from which
f08rnf is called.
Constraints:
- if , ;
- otherwise .
-
18:
– Real (Kind=nag_wp) array
Output
-
On exit: the values
for
where
. The diagonal submatrices
and
of
are constructed from these values as
- and
- .
-
19:
– Complex (Kind=nag_wp) array
Output
-
Note: the second dimension of the array
u1
must be at least
if
, and at least
otherwise.
On exit: if
,
u1 contains the
by
unitary matrix
.
-
20:
– Integer
Input
-
On entry: the first dimension of the array
u1 as declared in the (sub)program from which
f08rnf is called.
Constraint:
if , .
-
21:
– Complex (Kind=nag_wp) array
Output
-
Note: the second dimension of the array
u2
must be at least
if
, and at least
otherwise.
On exit: if
,
u2 contains the
by
unitary matrix
.
-
22:
– Integer
Input
-
On entry: the first dimension of the array
u2 as declared in the (sub)program from which
f08rnf is called.
Constraint:
if , .
-
23:
– Complex (Kind=nag_wp) array
Output
-
Note: the second dimension of the array
v1t
must be at least
if
, and at least
otherwise.
On exit: if
,
v1t contains the
by
unitary matrix
.
-
24:
– Integer
Input
-
On entry: the first dimension of the array
v1t as declared in the (sub)program from which
f08rnf is called.
Constraint:
if , .
-
25:
– Complex (Kind=nag_wp) array
Output
-
Note: the second dimension of the array
v2t
must be at least
if
, and at least
otherwise.
On exit: if
,
v2t contains the
by
unitary matrix
.
-
26:
– Integer
Input
-
On entry: the first dimension of the array
v2t as declared in the (sub)program from which
f08rnf is called.
Constraint:
if , .
-
27:
– Complex (Kind=nag_wp) array
Workspace
-
On exit: if
,
returns the optimal
lwork.
If
on exit,
contains the values
that, together with
, define the matrix in intermediate bidiagonal-block form remaining after nonconvergence.
info specifies the number of nonzero PHI's.
-
28:
– Integer
Input
-
On entry: the dimension of the array
work as declared in the (sub)program from which
f08rnf is called.
If
, 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.
The minimum workspace required is ; the optimal amount of workspace depends on internal block sizes and the relative problem dimensions.
Constraint:
or .
-
29:
– Real (Kind=nag_wp) array
Workspace
-
-
30:
– Integer
Input
-
On entry: the dimension of the array
rwork as declared in the (sub)program from which
f08rnf is called.
If
, 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
lrwork is issued. Otherwise the required workspace is
which equates to
for
,
for
and
when
.
Constraint:
.
-
31:
– Integer array
Workspace
-
-
32:
– Integer
Output
On exit:
unless the routine detects an error (see
Section 6).
6
Error Indicators and Warnings
If , argument had an illegal value. An explanatory message is output, and execution of the program is terminated.
-
The Jacobi-type procedure failed to converge during an internal reduction to bidiagonal-block form. The process requires convergence to
values, the value of
info gives the number of converged values.
7
Accuracy
The computed
decomposition is nearly the exact
decomposition for the nearby matrix
, where
and
is the
machine precision.
8
Parallelism and Performance
f08rnf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f08rnf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
The total number of floating-point operations required to perform the full decomposition is approximately .
The real analogue of this routine is
f08raf.
10
Example
This example finds the full CS decomposition of a unitary
by
matrix
(see
Section 10.2) partitioned so that the top left block is
by
.
The decomposition is performed both on submatrices of the unitary matrix and on separated partition matrices. Code is also provided to perform a recombining check if required.
10.1
Program Text
10.2
Program Data
10.3
Program Results