!----------------------------------------------------------------!
! Purpose
! =======
!
! LA_GGGLM 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 A and B.
!
! 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
! =========
!
! SUBROUTINE LA_GGGLM( A, B, D, X, Y, INFO )
!
<type>(<wp>), INTENT( INOUT ) :: A( :, : ), B(:,:), D(:)
!
<type>(<wp>), INTENT( OUT ) :: X(:), Y(:)
!
INTEGER, INTENT(OUT), OPTIONAL :: INFO
!
<type> ::= REAL | COMPLEX
!
<wp>
::= KIND(1.0) | KIND(1.0D0)
!
! =====================
!
! A
(input/output) either REAL or COMPLEX array, shape (:,:),
!
SIZE(A,1) == n, SIZE(A,2) == m.
!
On entry, the n-by-m matrix A.
!
On exit, A is destroyed.
!
INFO = -1 if SIZE(A,2) < 0 or SIZE(A,1) < SIZE(A,2)
!
! B
(input/output) REAL or COMPLEX array, shape (:,:),
!
SIZE(B,1) == n, SIZE(B,2) == p.
!
On entry, the n-by-p matrix B.
!
On exit, B is destroyed.
!
INFO = -2 if SIZE(B,2) < 0 or SIZE(B,1) /= SIZE(A,1) or
!
SIZE(B,2) < SIZE(A,1) - SIZE(A,2)
!
! D
(input/output) REAL or COMPLEX array, shape (:), SIZE(D) == n.
!
On entry, D is the left hand side of the GLM equation.
!
On exit, D is destroyed.
!
INFO = -3 if SIZE(D) /= SIZE(A,1)
!
! X
(output) REAL or COMPLEX array, shape (:), SIZE(X) == m.
! Y
(output) REAL or COMPLEX array, shape (:), SIZE(Y) == p.
!
On exit, X and Y are the solutions of the GLM problem.
!
INFO = -4 if SIZE(X) /= SIZE(A,2)
!
INFO = -5 if SIZE(Y) /= SIZE(B,2)
!
! INFO Optional (output) INTEGER
!
= 0: successful exit.
!
< 0: if INFO = -i, the i-th argument had an illegal value.
!
If INFO is not present and an error occurs, then the program is
!
terminated with an error message.
!-------------------------------------