clarft.f

Go to the documentation of this file.

*> \brief \b CLARFT forms the triangular factor T of a block reflector H = I - vtvH
*
*  =========== DOCUMENTATION ===========
*
* Online html documentation available at 
*            http://www.netlib.org/lapack/explore-html/ 
*
*> \htmlonly
*> Download CLARFT + dependencies 
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/clarft.f"> 
*> [TGZ]</a> 
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/clarft.f"> 
*> [ZIP]</a> 
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/clarft.f"> 
*> [TXT]</a>
*> \endhtmlonly 
*
*  Definition:
*  ===========
*
*       SUBROUTINE CLARFT( DIRECT, STOREV, N, K, V, LDV, TAU, T, LDT )
* 
*       .. Scalar Arguments ..
*       CHARACTER          DIRECT, STOREV
*       INTEGER            K, LDT, LDV, N
*       ..
*       .. Array Arguments ..
*       COMPLEX            T( LDT, * ), TAU( * ), V( LDV, * )
*       ..
*  
*
*> \par Purpose:
*  =============
*>
*> \verbatim
*>
*> CLARFT forms the triangular factor T of a complex block reflector H
*> of order n, which is defined as a product of k elementary reflectors.
*>
*> If DIRECT = 'F', H = H(1) H(2) . . . H(k) and T is upper triangular;
*>
*> If DIRECT = 'B', H = H(k) . . . H(2) H(1) and T is lower triangular.
*>
*> If STOREV = 'C', the vector which defines the elementary reflector
*> H(i) is stored in the i-th column of the array V, and
*>
*>    H  =  I - V * T * V**H
*>
*> If STOREV = 'R', the vector which defines the elementary reflector
*> H(i) is stored in the i-th row of the array V, and
*>
*>    H  =  I - V**H * T * V
*> \endverbatim
*
*  Arguments:
*  ==========
*
*> \param[in] DIRECT
*> \verbatim
*>          DIRECT is CHARACTER*1
*>          Specifies the order in which the elementary reflectors are
*>          multiplied to form the block reflector:
*>          = 'F': H = H(1) H(2) . . . H(k) (Forward)
*>          = 'B': H = H(k) . . . H(2) H(1) (Backward)
*> \endverbatim
*>
*> \param[in] STOREV
*> \verbatim
*>          STOREV is CHARACTER*1
*>          Specifies how the vectors which define the elementary
*>          reflectors are stored (see also Further Details):
*>          = 'C': columnwise
*>          = 'R': rowwise
*> \endverbatim
*>
*> \param[in] N
*> \verbatim
*>          N is INTEGER
*>          The order of the block reflector H. N >= 0.
*> \endverbatim
*>
*> \param[in] K
*> \verbatim
*>          K is INTEGER
*>          The order of the triangular factor T (= the number of
*>          elementary reflectors). K >= 1.
*> \endverbatim
*>
*> \param[in] V
*> \verbatim
*>          V is COMPLEX array, dimension
*>                               (LDV,K) if STOREV = 'C'
*>                               (LDV,N) if STOREV = 'R'
*>          The matrix V. See further details.
*> \endverbatim
*>
*> \param[in] LDV
*> \verbatim
*>          LDV is INTEGER
*>          The leading dimension of the array V.
*>          If STOREV = 'C', LDV >= max(1,N); if STOREV = 'R', LDV >= K.
*> \endverbatim
*>
*> \param[in] TAU
*> \verbatim
*>          TAU is COMPLEX array, dimension (K)
*>          TAU(i) must contain the scalar factor of the elementary
*>          reflector H(i).
*> \endverbatim
*>
*> \param[out] T
*> \verbatim
*>          T is COMPLEX array, dimension (LDT,K)
*>          The k by k triangular factor T of the block reflector.
*>          If DIRECT = 'F', T is upper triangular; if DIRECT = 'B', T is
*>          lower triangular. The rest of the array is not used.
*> \endverbatim
*>
*> \param[in] LDT
*> \verbatim
*>          LDT is INTEGER
*>          The leading dimension of the array T. LDT >= K.
*> \endverbatim
*
*  Authors:
*  ========
*
*> \author Univ. of Tennessee 
*> \author Univ. of California Berkeley 
*> \author Univ. of Colorado Denver 
*> \author NAG Ltd. 
*
*> \date September 2012
*
*> \ingroup complexOTHERauxiliary
*
*> \par Further Details:
*  =====================
*>
*> \verbatim
*>
*>  The shape of the matrix V and the storage of the vectors which define
*>  the H(i) is best illustrated by the following example with n = 5 and
*>  k = 3. The elements equal to 1 are not stored.
*>
*>  DIRECT = 'F' and STOREV = 'C':         DIRECT = 'F' and STOREV = 'R':
*>
*>               V = (  1       )                 V = (  1 v1 v1 v1 v1 )
*>                   ( v1  1    )                     (     1 v2 v2 v2 )
*>                   ( v1 v2  1 )                     (        1 v3 v3 )
*>                   ( v1 v2 v3 )
*>                   ( v1 v2 v3 )
*>
*>  DIRECT = 'B' and STOREV = 'C':         DIRECT = 'B' and STOREV = 'R':
*>
*>               V = ( v1 v2 v3 )                 V = ( v1 v1  1       )
*>                   ( v1 v2 v3 )                     ( v2 v2 v2  1    )
*>                   (  1 v2 v3 )                     ( v3 v3 v3 v3  1 )
*>                   (     1 v3 )
*>                   (        1 )
*> \endverbatim
*>
*  =====================================================================
      SUBROUTINE clarft( DIRECT, STOREV, N, K, V, LDV, TAU, T, LDT )
*
*  -- LAPACK auxiliary routine (version 3.4.2) --
*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
*     September 2012
*
*     .. Scalar Arguments ..
      CHARACTER          DIRECT, STOREV
      INTEGER            K, LDT, LDV, N
*     ..
*     .. Array Arguments ..
      COMPLEX            T( ldt, * ), TAU( * ), V( ldv, * )
*     ..
*
*  =====================================================================
*
*     .. Parameters ..
      COMPLEX            ONE, ZERO
      parameter                ( one = ( 1.0e+0, 0.0e+0 ),
     $                   zero = ( 0.0e+0, 0.0e+0 ) )
*     ..
*     .. Local Scalars ..
      INTEGER            I, J, PREVLASTV, LASTV
*     ..
*     .. External Subroutines ..
      EXTERNAL           cgemv, clacgv, ctrmv
*     ..
*     .. External Functions ..
      LOGICAL            LSAME
      EXTERNAL           lsame
*     ..
*     .. Executable Statements ..
*
*     Quick return if possible
*
      IF( n.EQ.0 )
     $   RETURN
*
      IF( lsame( direct, 'F' ) ) THEN
         prevlastv = n
         DO i = 1, k
            prevlastv = max( prevlastv, i )
            IF( tau( i ).EQ.zero ) THEN
*
*              H(i)  =  I
*
               DO j = 1, i
                  t( j, i ) = zero
               END DO
            ELSE
*
*              general case
*
               IF( lsame( storev, 'C' ) ) THEN
*                 Skip any trailing zeros.
                  DO lastv = n, i+1, -1
                     IF( v( lastv, i ).NE.zero ) EXIT
                  END DO
                  DO j = 1, i-1
                     t( j, i ) = -tau( i ) * conjg( v( i , j ) )
                  END DO                     
                  j = min( lastv, prevlastv )
*
*                 T(1:i-1,i) := - tau(i) * V(i:j,1:i-1)**H * V(i:j,i)
*
                  CALL cgemv( 'Conjugate transpose', j-i, i-1,
     $                        -tau( i ), v( i+1, 1 ), ldv, 
     $                        v( i+1, i ), 1,
     $                        one, t( 1, i ), 1 )
               ELSE
*                 Skip any trailing zeros.
                  DO lastv = n, i+1, -1
                     IF( v( i, lastv ).NE.zero ) EXIT
                  END DO
                  DO j = 1, i-1
                     t( j, i ) = -tau( i ) * v( j , i )
                  END DO                     
                  j = min( lastv, prevlastv )
*
*                 T(1:i-1,i) := - tau(i) * V(1:i-1,i:j) * V(i,i:j)**H
*
                  CALL cgemm( 'N', 'C', i-1, 1, j-i, -tau( i ),
     $                        v( 1, i+1 ), ldv, v( i, i+1 ), ldv,
     $                        one, t( 1, i ), ldt )                  
               END IF
*
*              T(1:i-1,i) := T(1:i-1,1:i-1) * T(1:i-1,i)
*
               CALL ctrmv( 'Upper', 'No transpose', 'Non-unit', i-1, t,
     $                     ldt, t( 1, i ), 1 )
               t( i, i ) = tau( i )
               IF( i.GT.1 ) THEN
                  prevlastv = max( prevlastv, lastv )
               ELSE
                  prevlastv = lastv
               END IF
            END IF
         END DO
      ELSE
         prevlastv = 1
         DO i = k, 1, -1
            IF( tau( i ).EQ.zero ) THEN
*
*              H(i)  =  I
*
               DO j = i, k
                  t( j, i ) = zero
               END DO
            ELSE
*
*              general case
*
               IF( i.LT.k ) THEN
                  IF( lsame( storev, 'C' ) ) THEN
*                    Skip any leading zeros.
                     DO lastv = 1, i-1
                        IF( v( lastv, i ).NE.zero ) EXIT
                     END DO
                     DO j = i+1, k
                        t( j, i ) = -tau( i ) * conjg( v( n-k+i , j ) )
                     END DO                        
                     j = max( lastv, prevlastv )
*
*                    T(i+1:k,i) = -tau(i) * V(j:n-k+i,i+1:k)**H * V(j:n-k+i,i)
*
                     CALL cgemv( 'Conjugate transpose', n-k+i-j, k-i,
     $                           -tau( i ), v( j, i+1 ), ldv, v( j, i ),
     $                           1, one, t( i+1, i ), 1 )
                  ELSE
*                    Skip any leading zeros.
                     DO lastv = 1, i-1
                        IF( v( i, lastv ).NE.zero ) EXIT
                     END DO
                     DO j = i+1, k
                        t( j, i ) = -tau( i ) * v( j, n-k+i )
                     END DO                      
                     j = max( lastv, prevlastv )
*
*                    T(i+1:k,i) = -tau(i) * V(i+1:k,j:n-k+i) * V(i,j:n-k+i)**H
*
                     CALL cgemm( 'N', 'C', k-i, 1, n-k+i-j, -tau( i ),
     $                           v( i+1, j ), ldv, v( i, j ), ldv,
     $                           one, t( i+1, i ), ldt )                     
                  END IF
*
*                 T(i+1:k,i) := T(i+1:k,i+1:k) * T(i+1:k,i)
*
                  CALL ctrmv( 'Lower', 'No transpose', 'Non-unit', k-i,
     $                        t( i+1, i+1 ), ldt, t( i+1, i ), 1 )
                  IF( i.GT.1 ) THEN
                     prevlastv = min( prevlastv, lastv )
                  ELSE
                     prevlastv = lastv
                  END IF
               END IF
               t( i, i ) = tau( i )
            END IF
         END DO
      END IF
      RETURN
*
*     End of CLARFT
*
      END