SRC/dlatrz.f

   1 *> \brief \b DLATRZ factors an upper trapezoidal matrix by means of orthogonal transformations.
   2 *
   3 *  =========== DOCUMENTATION ===========
   4 *
   5 * Online html documentation available at
   6 *            http://www.netlib.org/lapack/explore-html/
   7 *
   8 *> \htmlonly
   9 *> Download DLATRZ + dependencies
  10 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/dlatrz.f">
  11 *> [TGZ]</a>
  12 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/dlatrz.f">
  13 *> [ZIP]</a>
  14 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/dlatrz.f">
  15 *> [TXT]</a>
  16 *> \endhtmlonly
  17 *
  18 *  Definition:
  19 *  ===========
  20 *
  21 *       SUBROUTINE DLATRZ( M, N, L, A, LDA, TAU, WORK )
  22 *
  23 *       .. Scalar Arguments ..
  24 *       INTEGER            L, LDA, M, N
  25 *       ..
  26 *       .. Array Arguments ..
  27 *       DOUBLE PRECISION   A( LDA, * ), TAU( * ), WORK( * )
  28 *       ..
  29 *
  30 *
  31 *> \par Purpose:
  32 *  =============
  33 *>
  34 *> \verbatim
  35 *>
  36 *> DLATRZ factors the M-by-(M+L) real upper trapezoidal matrix
  37 *> [ A1 A2 ] = [ A(1:M,1:M) A(1:M,N-L+1:N) ] as ( R  0 ) * Z, by means
  38 *> of orthogonal transformations.  Z is an (M+L)-by-(M+L) orthogonal
  39 *> matrix and, R and A1 are M-by-M upper triangular matrices.
  40 *> \endverbatim
  41 *
  42 *  Arguments:
  43 *  ==========
  44 *
  45 *> \param[in] M
  46 *> \verbatim
  47 *>          M is INTEGER
  48 *>          The number of rows of the matrix A.  M >= 0.
  49 *> \endverbatim
  50 *>
  51 *> \param[in] N
  52 *> \verbatim
  53 *>          N is INTEGER
  54 *>          The number of columns of the matrix A.  N >= 0.
  55 *> \endverbatim
  56 *>
  57 *> \param[in] L
  58 *> \verbatim
  59 *>          L is INTEGER
  60 *>          The number of columns of the matrix A containing the
  61 *>          meaningful part of the Householder vectors. N-M >= L >= 0.
  62 *> \endverbatim
  63 *>
  64 *> \param[in,out] A
  65 *> \verbatim
  66 *>          A is DOUBLE PRECISION array, dimension (LDA,N)
  67 *>          On entry, the leading M-by-N upper trapezoidal part of the
  68 *>          array A must contain the matrix to be factorized.
  69 *>          On exit, the leading M-by-M upper triangular part of A
  70 *>          contains the upper triangular matrix R, and elements N-L+1 to
  71 *>          N of the first M rows of A, with the array TAU, represent the
  72 *>          orthogonal matrix Z as a product of M elementary reflectors.
  73 *> \endverbatim
  74 *>
  75 *> \param[in] LDA
  76 *> \verbatim
  77 *>          LDA is INTEGER
  78 *>          The leading dimension of the array A.  LDA >= max(1,M).
  79 *> \endverbatim
  80 *>
  81 *> \param[out] TAU
  82 *> \verbatim
  83 *>          TAU is DOUBLE PRECISION array, dimension (M)
  84 *>          The scalar factors of the elementary reflectors.
  85 *> \endverbatim
  86 *>
  87 *> \param[out] WORK
  88 *> \verbatim
  89 *>          WORK is DOUBLE PRECISION array, dimension (M)
  90 *> \endverbatim
  91 *
  92 *  Authors:
  93 *  ========
  94 *
  95 *> \author Univ. of Tennessee
  96 *> \author Univ. of California Berkeley
  97 *> \author Univ. of Colorado Denver
  98 *> \author NAG Ltd.
  99 *
 100 *> \date September 2012
 101 *
 102 *> \ingroup doubleOTHERcomputational
 103 *
 104 *> \par Contributors:
 105 *  ==================
 106 *>
 107 *>    A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA
 108 *
 109 *> \par Further Details:
 110 *  =====================
 111 *>
 112 *> \verbatim
 113 *>
 114 *>  The factorization is obtained by Householder's method.  The kth
 115 *>  transformation matrix, Z( k ), which is used to introduce zeros into
 116 *>  the ( m - k + 1 )th row of A, is given in the form
 117 *>
 118 *>     Z( k ) = ( I     0   ),
 119 *>              ( 0  T( k ) )
 120 *>
 121 *>  where
 122 *>
 123 *>     T( k ) = I - tau*u( k )*u( k )**T,   u( k ) = (   1    ),
 124 *>                                                 (   0    )
 125 *>                                                 ( z( k ) )
 126 *>
 127 *>  tau is a scalar and z( k ) is an l element vector. tau and z( k )
 128 *>  are chosen to annihilate the elements of the kth row of A2.
 129 *>
 130 *>  The scalar tau is returned in the kth element of TAU and the vector
 131 *>  u( k ) in the kth row of A2, such that the elements of z( k ) are
 132 *>  in  a( k, l + 1 ), ..., a( k, n ). The elements of R are returned in
 133 *>  the upper triangular part of A1.
 134 *>
 135 *>  Z is given by
 136 *>
 137 *>     Z =  Z( 1 ) * Z( 2 ) * ... * Z( m ).
 138 *> \endverbatim
 139 *>
 140 *  =====================================================================
 141       SUBROUTINE DLATRZ( M, N, L, A, LDA, TAU, WORK )
 142 *
 143 *  -- LAPACK computational routine (version 3.4.2) --
 144 *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
 145 *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
 146 *     September 2012
 147 *
 148 *     .. Scalar Arguments ..
 149       INTEGER            L, LDA, M, N
 150 *     ..
 151 *     .. Array Arguments ..
 152       DOUBLE PRECISION   A( LDA, * ), TAU( * ), WORK( * )
 153 *     ..
 154 *
 155 *  =====================================================================
 156 *
 157 *     .. Parameters ..
 158       DOUBLE PRECISION   ZERO
 159       PARAMETER          ( ZERO = 0.0D+0 )
 160 *     ..
 161 *     .. Local Scalars ..
 162       INTEGER            I
 163 *     ..
 164 *     .. External Subroutines ..
 165       EXTERNAL           DLARFG, DLARZ
 166 *     ..
 167 *     .. Executable Statements ..
 168 *
 169 *     Test the input arguments
 170 *
 171 *     Quick return if possible
 172 *
 173       IF( M.EQ.0 ) THEN
 174          RETURN
 175       ELSE IF( M.EQ.N ) THEN
 176          DO 10 I = 1, N
 177             TAU( I ) = ZERO
 178    10    CONTINUE
 179          RETURN
 180       END IF
 181 *
 182       DO 20 I = M, 1, -1
 183 *
 184 *        Generate elementary reflector H(i) to annihilate
 185 *        [ A(i,i) A(i,n-l+1:n) ]
 186 *
 187          CALL DLARFG( L+1, A( I, I ), A( I, N-L+1 ), LDA, TAU( I ) )
 188 *
 189 *        Apply H(i) to A(1:i-1,i:n) from the right
 190 *
 191          CALL DLARZ( 'Right', I-1, N-I+1, L, A( I, N-L+1 ), LDA,
 192      $               TAU( I ), A( 1, I ), LDA, WORK )
 193 *
 194    20 CONTINUE
 195 *
 196       RETURN
 197 *
 198 *     End of DLATRZ
 199 *
 200       END