diff options
author | julie <julielangou@users.noreply.github.com> | 2011-10-06 06:53:11 +0000 |
---|---|---|
committer | julie <julielangou@users.noreply.github.com> | 2011-10-06 06:53:11 +0000 |
commit | e1d39294aee16fa6db9ba079b14442358217db71 (patch) | |
tree | 30e5aa04c1f6596991fda5334f63dfb9b8027849 /SRC/ztgsy2.f | |
parent | 5fe0466a14e395641f4f8a300ecc9dcb8058081b (diff) | |
download | lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.gz lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.bz2 lapack-e1d39294aee16fa6db9ba079b14442358217db71.zip |
Integrating Doxygen in comments
Diffstat (limited to 'SRC/ztgsy2.f')
-rw-r--r-- | SRC/ztgsy2.f | 404 |
1 files changed, 256 insertions, 148 deletions
diff --git a/SRC/ztgsy2.f b/SRC/ztgsy2.f index 388a1f99..fb383e36 100644 --- a/SRC/ztgsy2.f +++ b/SRC/ztgsy2.f @@ -1,3 +1,258 @@ +*> \brief \b ZTGSY2 +* +* =========== DOCUMENTATION =========== +* +* Online html documentation available at +* http://www.netlib.org/lapack/explore-html/ +* +* Definition +* ========== +* +* SUBROUTINE ZTGSY2( TRANS, IJOB, M, N, A, LDA, B, LDB, C, LDC, D, +* LDD, E, LDE, F, LDF, SCALE, RDSUM, RDSCAL, +* INFO ) +* +* .. Scalar Arguments .. +* CHARACTER TRANS +* INTEGER IJOB, INFO, LDA, LDB, LDC, LDD, LDE, LDF, M, N +* DOUBLE PRECISION RDSCAL, RDSUM, SCALE +* .. +* .. Array Arguments .. +* COMPLEX*16 A( LDA, * ), B( LDB, * ), C( LDC, * ), +* $ D( LDD, * ), E( LDE, * ), F( LDF, * ) +* .. +* +* Purpose +* ======= +* +*>\details \b Purpose: +*>\verbatim +*> +*> ZTGSY2 solves the generalized Sylvester equation +*> +*> A * R - L * B = scale * C (1) +*> D * R - L * E = scale * F +*> +*> using Level 1 and 2 BLAS, where R and L are unknown M-by-N matrices, +*> (A, D), (B, E) and (C, F) are given matrix pairs of size M-by-M, +*> N-by-N and M-by-N, respectively. A, B, D and E are upper triangular +*> (i.e., (A,D) and (B,E) in generalized Schur form). +*> +*> The solution (R, L) overwrites (C, F). 0 <= SCALE <= 1 is an output +*> scaling factor chosen to avoid overflow. +*> +*> In matrix notation solving equation (1) corresponds to solve +*> Zx = scale * b, where Z is defined as +*> +*> Z = [ kron(In, A) -kron(B**H, Im) ] (2) +*> [ kron(In, D) -kron(E**H, Im) ], +*> +*> Ik is the identity matrix of size k and X**H is the conjuguate transpose of X. +*> kron(X, Y) is the Kronecker product between the matrices X and Y. +*> +*> If TRANS = 'C', y in the conjugate transposed system Z**H*y = scale*b +*> is solved for, which is equivalent to solve for R and L in +*> +*> A**H * R + D**H * L = scale * C (3) +*> R * B**H + L * E**H = scale * -F +*> +*> This case is used to compute an estimate of Dif[(A, D), (B, E)] = +*> = sigma_min(Z) using reverse communicaton with ZLACON. +*> +*> ZTGSY2 also (IJOB >= 1) contributes to the computation in ZTGSYL +*> of an upper bound on the separation between to matrix pairs. Then +*> the input (A, D), (B, E) are sub-pencils of two matrix pairs in +*> ZTGSYL. +*> +*>\endverbatim +* +* Arguments +* ========= +* +*> \param[in] TRANS +*> \verbatim +*> TRANS is CHARACTER*1 +*> = 'N', solve the generalized Sylvester equation (1). +*> = 'T': solve the 'transposed' system (3). +*> \endverbatim +*> +*> \param[in] IJOB +*> \verbatim +*> IJOB is INTEGER +*> Specifies what kind of functionality to be performed. +*> =0: solve (1) only. +*> =1: A contribution from this subsystem to a Frobenius +*> norm-based estimate of the separation between two matrix +*> pairs is computed. (look ahead strategy is used). +*> =2: A contribution from this subsystem to a Frobenius +*> norm-based estimate of the separation between two matrix +*> pairs is computed. (DGECON on sub-systems is used.) +*> Not referenced if TRANS = 'T'. +*> \endverbatim +*> +*> \param[in] M +*> \verbatim +*> M is INTEGER +*> On entry, M specifies the order of A and D, and the row +*> dimension of C, F, R and L. +*> \endverbatim +*> +*> \param[in] N +*> \verbatim +*> N is INTEGER +*> On entry, N specifies the order of B and E, and the column +*> dimension of C, F, R and L. +*> \endverbatim +*> +*> \param[in] A +*> \verbatim +*> A is COMPLEX*16 array, dimension (LDA, M) +*> On entry, A contains an upper triangular matrix. +*> \endverbatim +*> +*> \param[in] LDA +*> \verbatim +*> LDA is INTEGER +*> The leading dimension of the matrix A. LDA >= max(1, M). +*> \endverbatim +*> +*> \param[in] B +*> \verbatim +*> B is COMPLEX*16 array, dimension (LDB, N) +*> On entry, B contains an upper triangular matrix. +*> \endverbatim +*> +*> \param[in] LDB +*> \verbatim +*> LDB is INTEGER +*> The leading dimension of the matrix B. LDB >= max(1, N). +*> \endverbatim +*> +*> \param[in,out] C +*> \verbatim +*> C is COMPLEX*16 array, dimension (LDC, N) +*> On entry, C contains the right-hand-side of the first matrix +*> equation in (1). +*> On exit, if IJOB = 0, C has been overwritten by the solution +*> R. +*> \endverbatim +*> +*> \param[in] LDC +*> \verbatim +*> LDC is INTEGER +*> The leading dimension of the matrix C. LDC >= max(1, M). +*> \endverbatim +*> +*> \param[in] D +*> \verbatim +*> D is COMPLEX*16 array, dimension (LDD, M) +*> On entry, D contains an upper triangular matrix. +*> \endverbatim +*> +*> \param[in] LDD +*> \verbatim +*> LDD is INTEGER +*> The leading dimension of the matrix D. LDD >= max(1, M). +*> \endverbatim +*> +*> \param[in] E +*> \verbatim +*> E is COMPLEX*16 array, dimension (LDE, N) +*> On entry, E contains an upper triangular matrix. +*> \endverbatim +*> +*> \param[in] LDE +*> \verbatim +*> LDE is INTEGER +*> The leading dimension of the matrix E. LDE >= max(1, N). +*> \endverbatim +*> +*> \param[in,out] F +*> \verbatim +*> F is COMPLEX*16 array, dimension (LDF, N) +*> On entry, F contains the right-hand-side of the second matrix +*> equation in (1). +*> On exit, if IJOB = 0, F has been overwritten by the solution +*> L. +*> \endverbatim +*> +*> \param[in] LDF +*> \verbatim +*> LDF is INTEGER +*> The leading dimension of the matrix F. LDF >= max(1, M). +*> \endverbatim +*> +*> \param[out] SCALE +*> \verbatim +*> SCALE is DOUBLE PRECISION +*> On exit, 0 <= SCALE <= 1. If 0 < SCALE < 1, the solutions +*> R and L (C and F on entry) will hold the solutions to a +*> slightly perturbed system but the input matrices A, B, D and +*> E have not been changed. If SCALE = 0, R and L will hold the +*> solutions to the homogeneous system with C = F = 0. +*> Normally, SCALE = 1. +*> \endverbatim +*> +*> \param[in,out] RDSUM +*> \verbatim +*> RDSUM is DOUBLE PRECISION +*> On entry, the sum of squares of computed contributions to +*> the Dif-estimate under computation by ZTGSYL, where the +*> scaling factor RDSCAL (see below) has been factored out. +*> On exit, the corresponding sum of squares updated with the +*> contributions from the current sub-system. +*> If TRANS = 'T' RDSUM is not touched. +*> NOTE: RDSUM only makes sense when ZTGSY2 is called by +*> ZTGSYL. +*> \endverbatim +*> +*> \param[in,out] RDSCAL +*> \verbatim +*> RDSCAL is DOUBLE PRECISION +*> On entry, scaling factor used to prevent overflow in RDSUM. +*> On exit, RDSCAL is updated w.r.t. the current contributions +*> in RDSUM. +*> If TRANS = 'T', RDSCAL is not touched. +*> NOTE: RDSCAL only makes sense when ZTGSY2 is called by +*> ZTGSYL. +*> \endverbatim +*> +*> \param[out] INFO +*> \verbatim +*> INFO is INTEGER +*> On exit, if INFO is set to +*> =0: Successful exit +*> <0: If INFO = -i, input argument number i is illegal. +*> >0: The matrix pairs (A, D) and (B, E) have common or very +*> close eigenvalues. +*> \endverbatim +*> +* +* Authors +* ======= +* +*> \author Univ. of Tennessee +*> \author Univ. of California Berkeley +*> \author Univ. of Colorado Denver +*> \author NAG Ltd. +* +*> \date November 2011 +* +*> \ingroup complex16SYauxiliary +* +* +* Further Details +* =============== +*>\details \b Further \b Details +*> \verbatim +*> +*> Based on contributions by +*> Bo Kagstrom and Peter Poromaa, Department of Computing Science, +*> Umea University, S-901 87 Umea, Sweden. +*> +*> \endverbatim +*> +* ===================================================================== SUBROUTINE ZTGSY2( TRANS, IJOB, M, N, A, LDA, B, LDB, C, LDC, D, $ LDD, E, LDE, F, LDF, SCALE, RDSUM, RDSCAL, $ INFO ) @@ -5,7 +260,7 @@ * -- LAPACK auxiliary routine (version 3.3.1) -- * -- LAPACK is a software package provided by Univ. of Tennessee, -- * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..-- -* -- April 2011 -- +* November 2011 * * .. Scalar Arguments .. CHARACTER TRANS @@ -17,153 +272,6 @@ $ D( LDD, * ), E( LDE, * ), F( LDF, * ) * .. * -* Purpose -* ======= -* -* ZTGSY2 solves the generalized Sylvester equation -* -* A * R - L * B = scale * C (1) -* D * R - L * E = scale * F -* -* using Level 1 and 2 BLAS, where R and L are unknown M-by-N matrices, -* (A, D), (B, E) and (C, F) are given matrix pairs of size M-by-M, -* N-by-N and M-by-N, respectively. A, B, D and E are upper triangular -* (i.e., (A,D) and (B,E) in generalized Schur form). -* -* The solution (R, L) overwrites (C, F). 0 <= SCALE <= 1 is an output -* scaling factor chosen to avoid overflow. -* -* In matrix notation solving equation (1) corresponds to solve -* Zx = scale * b, where Z is defined as -* -* Z = [ kron(In, A) -kron(B**H, Im) ] (2) -* [ kron(In, D) -kron(E**H, Im) ], -* -* Ik is the identity matrix of size k and X**H is the conjuguate transpose of X. -* kron(X, Y) is the Kronecker product between the matrices X and Y. -* -* If TRANS = 'C', y in the conjugate transposed system Z**H*y = scale*b -* is solved for, which is equivalent to solve for R and L in -* -* A**H * R + D**H * L = scale * C (3) -* R * B**H + L * E**H = scale * -F -* -* This case is used to compute an estimate of Dif[(A, D), (B, E)] = -* = sigma_min(Z) using reverse communicaton with ZLACON. -* -* ZTGSY2 also (IJOB >= 1) contributes to the computation in ZTGSYL -* of an upper bound on the separation between to matrix pairs. Then -* the input (A, D), (B, E) are sub-pencils of two matrix pairs in -* ZTGSYL. -* -* Arguments -* ========= -* -* TRANS (input) CHARACTER*1 -* = 'N', solve the generalized Sylvester equation (1). -* = 'T': solve the 'transposed' system (3). -* -* IJOB (input) INTEGER -* Specifies what kind of functionality to be performed. -* =0: solve (1) only. -* =1: A contribution from this subsystem to a Frobenius -* norm-based estimate of the separation between two matrix -* pairs is computed. (look ahead strategy is used). -* =2: A contribution from this subsystem to a Frobenius -* norm-based estimate of the separation between two matrix -* pairs is computed. (DGECON on sub-systems is used.) -* Not referenced if TRANS = 'T'. -* -* M (input) INTEGER -* On entry, M specifies the order of A and D, and the row -* dimension of C, F, R and L. -* -* N (input) INTEGER -* On entry, N specifies the order of B and E, and the column -* dimension of C, F, R and L. -* -* A (input) COMPLEX*16 array, dimension (LDA, M) -* On entry, A contains an upper triangular matrix. -* -* LDA (input) INTEGER -* The leading dimension of the matrix A. LDA >= max(1, M). -* -* B (input) COMPLEX*16 array, dimension (LDB, N) -* On entry, B contains an upper triangular matrix. -* -* LDB (input) INTEGER -* The leading dimension of the matrix B. LDB >= max(1, N). -* -* C (input/output) COMPLEX*16 array, dimension (LDC, N) -* On entry, C contains the right-hand-side of the first matrix -* equation in (1). -* On exit, if IJOB = 0, C has been overwritten by the solution -* R. -* -* LDC (input) INTEGER -* The leading dimension of the matrix C. LDC >= max(1, M). -* -* D (input) COMPLEX*16 array, dimension (LDD, M) -* On entry, D contains an upper triangular matrix. -* -* LDD (input) INTEGER -* The leading dimension of the matrix D. LDD >= max(1, M). -* -* E (input) COMPLEX*16 array, dimension (LDE, N) -* On entry, E contains an upper triangular matrix. -* -* LDE (input) INTEGER -* The leading dimension of the matrix E. LDE >= max(1, N). -* -* F (input/output) COMPLEX*16 array, dimension (LDF, N) -* On entry, F contains the right-hand-side of the second matrix -* equation in (1). -* On exit, if IJOB = 0, F has been overwritten by the solution -* L. -* -* LDF (input) INTEGER -* The leading dimension of the matrix F. LDF >= max(1, M). -* -* SCALE (output) DOUBLE PRECISION -* On exit, 0 <= SCALE <= 1. If 0 < SCALE < 1, the solutions -* R and L (C and F on entry) will hold the solutions to a -* slightly perturbed system but the input matrices A, B, D and -* E have not been changed. If SCALE = 0, R and L will hold the -* solutions to the homogeneous system with C = F = 0. -* Normally, SCALE = 1. -* -* RDSUM (input/output) DOUBLE PRECISION -* On entry, the sum of squares of computed contributions to -* the Dif-estimate under computation by ZTGSYL, where the -* scaling factor RDSCAL (see below) has been factored out. -* On exit, the corresponding sum of squares updated with the -* contributions from the current sub-system. -* If TRANS = 'T' RDSUM is not touched. -* NOTE: RDSUM only makes sense when ZTGSY2 is called by -* ZTGSYL. -* -* RDSCAL (input/output) DOUBLE PRECISION -* On entry, scaling factor used to prevent overflow in RDSUM. -* On exit, RDSCAL is updated w.r.t. the current contributions -* in RDSUM. -* If TRANS = 'T', RDSCAL is not touched. -* NOTE: RDSCAL only makes sense when ZTGSY2 is called by -* ZTGSYL. -* -* INFO (output) INTEGER -* On exit, if INFO is set to -* =0: Successful exit -* <0: If INFO = -i, input argument number i is illegal. -* >0: The matrix pairs (A, D) and (B, E) have common or very -* close eigenvalues. -* -* Further Details -* =============== -* -* Based on contributions by -* Bo Kagstrom and Peter Poromaa, Department of Computing Science, -* Umea University, S-901 87 Umea, Sweden. -* * ===================================================================== * * .. Parameters .. |