====================================================================
dlabrd examples
====================================================================

====================================================================
Man Page Details
====================================================================

NAME
       DLABRD  - the first NB rows and columns of a real general m by n matrix
       A to upper or lower bidiagonal form by an orthogonal transformation  Q'
       * A * P, and returns the matrices X and Y which are needed to apply the
       transformation to the unreduced part of A

SYNOPSIS
       SUBROUTINE DLABRD( M, N, NB, A, LDA, D, E, TAUQ, TAUP, X, LDX, Y, LDY )

           INTEGER        LDA, LDX, LDY, M, N, NB

           DOUBLE         PRECISION  A(  LDA,  * ), D( * ), E( * ), TAUP( * ),
                          TAUQ( * ), X( LDX, * ), Y( LDY, * )

PURPOSE
       DLABRD reduces the first NB rows and columns of a real general m  by  n
       matrix A to upper or lower bidiagonal form by an orthogonal transforma-
       tion Q' * A * P, and returns the matrices X and Y which are  needed  to
       apply the transformation to the unreduced part of A.

       If  m  >=  n, A is reduced to upper bidiagonal form; if m < n, to lower
       bidiagonal form.

       This is an auxiliary routine called by DGEBRD


ARGUMENTS
       M       (input) INTEGER
               The number of rows in the matrix A.

       N       (input) INTEGER
               The number of columns in the matrix A.

       NB      (input) INTEGER
               The number of leading rows and columns of A to be reduced.

       A       (input/output) DOUBLE PRECISION array, dimension (LDA,N)
               On entry, the m by n general matrix to be  reduced.   On  exit,
               the  first  NB  rows and columns of the matrix are overwritten;
               the rest of the array is unchanged.  If m >= n, elements on and
               below  the  diagonal  in  the  first NB columns, with the array
               TAUQ, represent the orthogonal matrix Q as a product of elemen-
               tary  reflectors;  and elements above the diagonal in the first
               NB rows, with the array TAUP, represent the orthogonal matrix P
               as  a  product  of  elementary  reflectors.  If m < n, elements
               below the diagonal in the first  NB  columns,  with  the  array
               TAUQ, represent the orthogonal matrix Q as a product of elemen-
               tary reflectors, and elements on and above the diagonal in  the
               first  NB  rows,  with the array TAUP, represent the orthogonal
               matrix P as a product of elementary  reflectors.   See  Further
               Details.   LDA     (input) INTEGER The leading dimension of the
               array A.  LDA >= max(1,M).

       D       (output) DOUBLE PRECISION array, dimension (NB)
               The diagonal elements of the first NB rows and columns  of  the
               reduced matrix.  D(i) = A(i,i).

       E       (output) DOUBLE PRECISION array, dimension (NB)
               The  off-diagonal  elements of the first NB rows and columns of
               the reduced matrix.

       TAUQ    (output) DOUBLE PRECISION array dimension (NB)
               The scalar factors of the elementary reflectors which represent
               the orthogonal matrix Q. See Further Details.  TAUP    (output)
               DOUBLE PRECISION array, dimension (NB) The  scalar  factors  of
               the elementary reflectors which represent the orthogonal matrix
               P. See Further  Details.   X        (output)  DOUBLE  PRECISION
               array,  dimension  (LDX,NB)  The  m-by-nb  matrix X required to
               update the unreduced part of A.

       LDX     (input) INTEGER
               The leading dimension of the array X. LDX >= M.

       Y       (output) DOUBLE PRECISION array, dimension (LDY,NB)
               The n-by-nb matrix Y required to update the unreduced  part  of
               A.

       LDY     (input) INTEGER
               The leading dimension of the array Y. LDY >= N.

FURTHER DETAILS
       The  matrices Q and P are represented as products of elementary reflec-
       tors:

          Q = H(1) H(2) . . . H(nb)  and  P = G(1) G(2) . . . G(nb)

       Each H(i) and G(i) has the form:

          H(i) = I - tauq * v * v'  and G(i) = I - taup * u * u'

       where tauq and taup are real scalars, and v and u are real vectors.

       If m >= n, v(1:i-1) = 0, v(i) = 1, and v(i:m)  is  stored  on  exit  in
       A(i:m,i);  u(1:i)  =  0,  u(i+1) = 1, and u(i+1:n) is stored on exit in
       A(i,i+1:n); tauq is stored in TAUQ(i) and taup in TAUP(i).

       If m < n, v(1:i) = 0, v(i+1) = 1, and v(i+1:m) is  stored  on  exit  in
       A(i+2:m,i);  u(1:i-1)  =  0,  u(i) = 1, and u(i:n) is stored on exit in
       A(i,i+1:n); tauq is stored in TAUQ(i) and taup in TAUP(i).

       The elements of the vectors v and u together form the m-by-nb matrix  V
       and  the nb-by-n matrix U' which are needed, with X and Y, to apply the
       transformation to the unreduced part  of  the  matrix,  using  a  block
       update of the form:  A := A - V*Y' - X*U'.

       The  contents  of  A  on exit are illustrated by the following examples
       with nb = 2:

       m = 6 and n = 5 (m > n):          m = 5 and n = 6 (m < n):

         (  1   1   u1  u1  u1 )           (  1   u1  u1  u1  u1  u1 )
         (  v1  1   1   u2  u2 )           (  1   1   u2  u2  u2  u2 )
         (  v1  v2  a   a   a  )           (  v1  1   a   a   a   a  )
         (  v1  v2  a   a   a  )           (  v1  v2  a   a   a   a  )
         (  v1  v2  a   a   a  )           (  v1  v2  a   a   a   a  )
         (  v1  v2  a   a   a  )

       where a denotes an element of the original matrix which  is  unchanged,
       vi denotes an element of the vector defining H(i), and ui an element of
       the vector defining G(i).

