!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_GESV computes the solution to either a real or complex system of 
! linear equations  AX = B,
! where A is a square matrix and X and B are either rectangular
! matrices or vectors.
!
! The LU decomposition with partial pivoting and row interchanges is
! used to factor A as  A = PLU,
! where P is a permutation matrix, L is unit lower triangular, and U is
! upper triangular. The factored form of A is then used to solve the
! system of equations AX = B.
!
! Arguments
! =========
!
! SUBROUTINE LA_GESV ( A, B, IPIV, INFO )
!    <type>(<wp>), INTENT(INOUT) :: A(:,:), <rhs>
!    INTEGER, INTENT(OUT), OPTIONAL :: IPIV(:)
!    INTEGER, INTENT(OUT), OPTIONAL :: INFO
!    where
!    <type> ::= REAL | COMPLEX
!    <wp>   ::= KIND(1.0) | KIND(1.0D0)
!    <rhs>  ::= B(:,:) | B(:)
!
! =====================
!
! A    (input/output) either REAL or COMPLEX square array,
!      shape (:,:), size(A,1) == size(A,2).
!      On entry, the matrix A.
!      On exit, the factors L and U from the factorization A = PLU;
!         the unit diagonal elements of L are not stored.
!
! B    (input/output) either REAL or COMPLEX rectangular array,
!      shape either (:,:) or (:), size(B,1) or size(B) == size(A,1).
!      On entry, the right hand side vector(s) of matrix B for the
!         system of equations AX = B.
!      On exit, if there is no error, the matrix of solution
!         vector(s) X.
!
! IPIV Optional (output) INTEGER array, shape (:),
!      size(IPIV) == size(A,1). If IPIV is present it indice define
!      the permutation matrix P; row i of the matrix was interchanged
!      with row IPIV(i).
!
! INFO Optional (output) INTEGER.
!      If INFO is present
!         = 0: successful exit
!         < 0: if INFO = -k, the k-th argument had an illegal value
!         > 0: if INFO = k, U(k,k) is exactly zero.  The factorization
!              has been completed, but the factor U is exactly
!              singular, so the solution could not be computed.
!      If INFO is not present and an error occurs, then the program is
!         terminated with an error message.
!-------------------------------------
