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/sggglm.f | |
parent | 5fe0466a14e395641f4f8a300ecc9dcb8058081b (diff) | |
download | lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.gz lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.bz2 lapack-e1d39294aee16fa6db9ba079b14442358217db71.zip |
Integrating Doxygen in comments
Diffstat (limited to 'SRC/sggglm.f')
-rw-r--r-- | SRC/sggglm.f | 274 |
1 files changed, 177 insertions, 97 deletions
diff --git a/SRC/sggglm.f b/SRC/sggglm.f index 833dea90..3f483759 100644 --- a/SRC/sggglm.f +++ b/SRC/sggglm.f @@ -1,10 +1,185 @@ +*> \brief <b> SGGEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for GE matrices</b> +* +* =========== DOCUMENTATION =========== +* +* Online html documentation available at +* http://www.netlib.org/lapack/explore-html/ +* +* Definition +* ========== +* +* SUBROUTINE SGGGLM( N, M, P, A, LDA, B, LDB, D, X, Y, WORK, LWORK, +* INFO ) +* +* .. Scalar Arguments .. +* INTEGER INFO, LDA, LDB, LWORK, M, N, P +* .. +* .. Array Arguments .. +* REAL A( LDA, * ), B( LDB, * ), D( * ), WORK( * ), +* $ X( * ), Y( * ) +* .. +* +* Purpose +* ======= +* +*>\details \b Purpose: +*>\verbatim +*> +*> SGGGLM solves a general Gauss-Markov linear model (GLM) problem: +*> +*> minimize || y ||_2 subject to d = A*x + B*y +*> x +*> +*> where A is an N-by-M matrix, B is an N-by-P matrix, and d is a +*> given N-vector. It is assumed that M <= N <= M+P, and +*> +*> rank(A) = M and rank( A B ) = N. +*> +*> Under these assumptions, the constrained equation is always +*> consistent, and there is a unique solution x and a minimal 2-norm +*> solution y, which is obtained using a generalized QR factorization +*> of the matrices (A, B) given by +*> +*> A = Q*(R), B = Q*T*Z. +*> (0) +*> +*> In particular, if matrix B is square nonsingular, then the problem +*> GLM is equivalent to the following weighted linear least squares +*> problem +*> +*> minimize || inv(B)*(d-A*x) ||_2 +*> x +*> +*> where inv(B) denotes the inverse of B. +*> +*>\endverbatim +* +* Arguments +* ========= +* +*> \param[in] N +*> \verbatim +*> N is INTEGER +*> The number of rows of the matrices A and B. N >= 0. +*> \endverbatim +*> +*> \param[in] M +*> \verbatim +*> M is INTEGER +*> The number of columns of the matrix A. 0 <= M <= N. +*> \endverbatim +*> +*> \param[in] P +*> \verbatim +*> P is INTEGER +*> The number of columns of the matrix B. P >= N-M. +*> \endverbatim +*> +*> \param[in,out] A +*> \verbatim +*> A is REAL array, dimension (LDA,M) +*> On entry, the N-by-M matrix A. +*> On exit, the upper triangular part of the array A contains +*> the M-by-M upper triangular matrix R. +*> \endverbatim +*> +*> \param[in] LDA +*> \verbatim +*> LDA is INTEGER +*> The leading dimension of the array A. LDA >= max(1,N). +*> \endverbatim +*> +*> \param[in,out] B +*> \verbatim +*> B is REAL array, dimension (LDB,P) +*> On entry, the N-by-P matrix B. +*> On exit, if N <= P, the upper triangle of the subarray +*> B(1:N,P-N+1:P) contains the N-by-N upper triangular matrix T; +*> if N > P, the elements on and above the (N-P)th subdiagonal +*> contain the N-by-P upper trapezoidal matrix T. +*> \endverbatim +*> +*> \param[in] LDB +*> \verbatim +*> LDB is INTEGER +*> The leading dimension of the array B. LDB >= max(1,N). +*> \endverbatim +*> +*> \param[in,out] D +*> \verbatim +*> D is REAL array, dimension (N) +*> On entry, D is the left hand side of the GLM equation. +*> On exit, D is destroyed. +*> \endverbatim +*> +*> \param[out] X +*> \verbatim +*> X is REAL array, dimension (M) +*> \param[out] Y +*> \verbatim +*> Y is REAL array, dimension (P) +*> On exit, X and Y are the solutions of the GLM problem. +*> \endverbatim +*> \endverbatim +*> +*> \param[out] WORK +*> \verbatim +*> WORK is REAL array, dimension (MAX(1,LWORK)) +*> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. +*> \endverbatim +*> +*> \param[in] LWORK +*> \verbatim +*> LWORK is INTEGER +*> The dimension of the array WORK. LWORK >= max(1,N+M+P). +*> For optimum performance, LWORK >= M+min(N,P)+max(N,P)*NB, +*> where NB is an upper bound for the optimal blocksizes for +*> SGEQRF, SGERQF, SORMQR and SORMRQ. +*> \endverbatim +*> \verbatim +*> 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. +*> \endverbatim +*> +*> \param[out] INFO +*> \verbatim +*> INFO is INTEGER +*> = 0: successful exit. +*> < 0: if INFO = -i, the i-th argument had an illegal value. +*> = 1: the upper triangular factor R associated with A in the +*> generalized QR factorization of the pair (A, B) is +*> singular, so that rank(A) < M; the least squares +*> solution could not be computed. +*> = 2: the bottom (N-M) by (N-M) part of the upper trapezoidal +*> factor T associated with B in the generalized QR +*> factorization of the pair (A, B) is singular, so that +*> rank( A B ) < N; the least squares solution could not +*> be computed. +*> \endverbatim +*> +* +* Authors +* ======= +* +*> \author Univ. of Tennessee +*> \author Univ. of California Berkeley +*> \author Univ. of Colorado Denver +*> \author NAG Ltd. +* +*> \date November 2011 +* +*> \ingroup realOTHEReigen +* +* ===================================================================== SUBROUTINE SGGGLM( N, M, P, A, LDA, B, LDB, D, X, Y, WORK, LWORK, $ INFO ) * -* -- LAPACK driver routine (version 3.3.1) -- +* -- LAPACK eigen 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 .. INTEGER INFO, LDA, LDB, LWORK, M, N, P @@ -14,101 +189,6 @@ $ X( * ), Y( * ) * .. * -* Purpose -* ======= -* -* SGGGLM solves a general Gauss-Markov linear model (GLM) problem: -* -* minimize || y ||_2 subject to d = A*x + B*y -* x -* -* where A is an N-by-M matrix, B is an N-by-P matrix, and d is a -* given N-vector. It is assumed that M <= N <= M+P, and -* -* rank(A) = M and rank( A B ) = N. -* -* Under these assumptions, the constrained equation is always -* consistent, and there is a unique solution x and a minimal 2-norm -* solution y, which is obtained using a generalized QR factorization -* of the matrices (A, B) given by -* -* A = Q*(R), B = Q*T*Z. -* (0) -* -* In particular, if matrix B is square nonsingular, then the problem -* GLM is equivalent to the following weighted linear least squares -* problem -* -* minimize || inv(B)*(d-A*x) ||_2 -* x -* -* where inv(B) denotes the inverse of B. -* -* Arguments -* ========= -* -* N (input) INTEGER -* The number of rows of the matrices A and B. N >= 0. -* -* M (input) INTEGER -* The number of columns of the matrix A. 0 <= M <= N. -* -* P (input) INTEGER -* The number of columns of the matrix B. P >= N-M. -* -* A (input/output) REAL array, dimension (LDA,M) -* On entry, the N-by-M matrix A. -* On exit, the upper triangular part of the array A contains -* the M-by-M upper triangular matrix R. -* -* LDA (input) INTEGER -* The leading dimension of the array A. LDA >= max(1,N). -* -* B (input/output) REAL array, dimension (LDB,P) -* On entry, the N-by-P matrix B. -* On exit, if N <= P, the upper triangle of the subarray -* B(1:N,P-N+1:P) contains the N-by-N upper triangular matrix T; -* if N > P, the elements on and above the (N-P)th subdiagonal -* contain the N-by-P upper trapezoidal matrix T. -* -* LDB (input) INTEGER -* The leading dimension of the array B. LDB >= max(1,N). -* -* D (input/output) REAL array, dimension (N) -* On entry, D is the left hand side of the GLM equation. -* On exit, D is destroyed. -* -* X (output) REAL array, dimension (M) -* Y (output) REAL array, dimension (P) -* On exit, X and Y are the solutions of the GLM problem. -* -* WORK (workspace/output) REAL array, dimension (MAX(1,LWORK)) -* On exit, if INFO = 0, WORK(1) returns the optimal LWORK. -* -* LWORK (input) INTEGER -* The dimension of the array WORK. LWORK >= max(1,N+M+P). -* For optimum performance, LWORK >= M+min(N,P)+max(N,P)*NB, -* where NB is an upper bound for the optimal blocksizes for -* SGEQRF, SGERQF, SORMQR and SORMRQ. -* -* 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. -* -* INFO (output) INTEGER -* = 0: successful exit. -* < 0: if INFO = -i, the i-th argument had an illegal value. -* = 1: the upper triangular factor R associated with A in the -* generalized QR factorization of the pair (A, B) is -* singular, so that rank(A) < M; the least squares -* solution could not be computed. -* = 2: the bottom (N-M) by (N-M) part of the upper trapezoidal -* factor T associated with B in the generalized QR -* factorization of the pair (A, B) is singular, so that -* rank( A B ) < N; the least squares solution could not -* be computed. -* * =================================================================== * * .. Parameters .. |