!-----------------------------------------------------------------
!
! Purpose
! =======
!
! LA_SPSV computes the solution to a system of linear equations
!    A * X = B,
! where A is a symmetric real or complex, or hermitian matrix stored
! in packed format and X and B are either retriangular matrices or
! vectors.
! The diagonal pivoting method is used to factor A as
!    A = U * D * U**T,  if UPLO = 'U', or
!    A = L * D * L**T,  if UPLO = 'L',
! where U (or L) is a product of permutation and unit upper (lower)
! triangular matrices, D is symmetric and block diagonal with 1-by-1
! and 2-by-2 diagonal blocks.  The factored form of A is then used to
! solve the system of equations A * X = B.
!
! Arguments
! =========
!
!  SUBROUTINE LA_SPSV /LA_HPSV( AP, B, UPLO, IPIV, INFO )
!      <type>(<wp>), INTENT(INOUT) :: AP(:), <rhs>
!      CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO
!      INTEGER, INTENT(OUT), OPTIONAL :: IPIV(:)
!      INTEGER, INTENT(OUT), OPTIONAL :: INFO
!    <type> ::= REAL | COMPLEX
!    <wp>   ::= KIND(1.0) | KIND(1.0D0)
!    <rhs>  ::= B(:,:) | B(:)
!
! =====================
!
! AP   (input/output) either REAL or COMPLEX array, shape (:), where
!      SIZE(A) n*(n+1)/2 (n is a rank of the matrix A).
!      On entry, the upper or lower triangle of the symmetric matrix
!      A, packed columnwise in a linear array. The j-th column of A
!      is stored in the array AP as follows:
!      if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
!      if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
!      See below for further details.
!
! 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.
!
! UPLO Optional, (input) CHARACTER*1
!      If UPLO is present then:
!         = 'U':  Upper triangle of A is stored;
!         = 'L':  Lower triangle of A is stored.
!
! IPIV Optional (output) INTEGER array, shape (:),
!      size(IPIV) == size(A,1). If IPIV is present it indices that
!      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.
!
! Further Details
! ===============
!
! The packed storage scheme is illustrated by the following example
! when n = 4, UPLO = 'U':
!
! Two-dimensional storage of the symmetric matrix A:
!
!    a11 a12 a13 a14
!        a22 a23 a24
!            a33 a34     (aij = aji)
!                a44
!
! Packed storage of the upper triangle of A:
!
! AP = [ a11, a12, a22, a13, a23, a33, a14, a24, a34, a44 ]
! SIZE(AP) = n*(n+1)/2 = 10
!
!-------------------------------------

.