PCLARZT(3)    ScaLAPACK routine of NEC Numeric Library Collection   PCLARZT(3)



NAME
       PCLARZT  -  form the triangular factor T of a complex block reflector H
       of order > n, which is defined as a product of k elementary  reflectors
       as returned by PCTZRZF

SYNOPSIS
       SUBROUTINE PCLARZT( DIRECT,  STOREV,  N,  K,  V, IV, JV, DESCV, TAU, T,
                           WORK )

           CHARACTER       DIRECT, STOREV

           INTEGER         IV, JV, K, N

           INTEGER         DESCV( * )

           COMPLEX         TAU( * ), T( * ), V( * ), WORK( * )

PURPOSE
       PCLARZT forms the triangular factor T of a complex block reflector H of
       order  > n, which is defined as a product of k elementary reflectors as
       returned by PCTZRZF.  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'

       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' * T * V

       Currently, only STOREV = 'R' and DIRECT = 'B' are supported.


       Notes
       =====

       Each  global data object is described by an associated description vec-
       tor.  This vector stores the information required to establish the map-
       ping between an object element and its corresponding process and memory
       location.

       Let A be a generic term for any 2D block  cyclicly  distributed  array.
       Such a global array has an associated description vector DESCA.  In the
       following comments, the character _ should be read as  "of  the  global
       array".

       NOTATION        STORED IN      EXPLANATION
       --------------- -------------- --------------------------------------
       DTYPE_A(global) DESCA( DTYPE_ )The descriptor type.  In this case,
                                      DTYPE_A = 1.
       CTXT_A (global) DESCA( CTXT_ ) The BLACS context handle, indicating
                                      the BLACS process grid A is distribu-
                                      ted over. The context itself is glo-
                                      bal, but the handle (the integer
                                      value) may vary.
       M_A    (global) DESCA( M_ )    The number of rows in the global
                                      array A.
       N_A    (global) DESCA( N_ )    The number of columns in the global
                                      array A.
       MB_A   (global) DESCA( MB_ )   The blocking factor used to distribute
                                      the rows of the array.
       NB_A   (global) DESCA( NB_ )   The blocking factor used to distribute
                                      the columns of the array.
       RSRC_A (global) DESCA( RSRC_ ) The process row over which the first
                                      row  of  the  array  A  is  distributed.
       CSRC_A (global) DESCA( CSRC_ ) The process column over which the
                                      first column of the array A is
                                      distributed.
       LLD_A  (local)  DESCA( LLD_ )  The leading dimension of the local
                                      array.  LLD_A >= MAX(1,LOCr(M_A)).

       Let K be the number of rows or columns of  a  distributed  matrix,  and
       assume that its process grid has dimension p x q.
       LOCr(  K  )  denotes  the  number of elements of K that a process would
       receive if K were distributed over the p processes of its process  col-
       umn.
       Similarly, LOCc( K ) denotes the number of elements of K that a process
       would receive if K were distributed over the q processes of its process
       row.
       The  values  of  LOCr()  and LOCc() may be determined via a call to the
       ScaLAPACK tool function, NUMROC:
               LOCr( M ) = NUMROC( M, MB_A, MYROW, RSRC_A, NPROW ),
               LOCc( N ) = NUMROC( N, NB_A, MYCOL, CSRC_A, NPCOL ).  An  upper
       bound for these quantities may be computed by:
               LOCr( M ) <= ceil( ceil(M/MB_A)/NPROW )*MB_A
               LOCc( N ) <= ceil( ceil(N/NB_A)/NPCOL )*NB_A


ARGUMENTS
       DIRECT  (global input) CHARACTER
               Specifies the order in which the elementary reflectors are mul-
               tiplied to form the block reflector:
               = 'F': H = H(1) H(2) . . . H(k) (Forward, not supported yet)
               = 'B': H = H(k) . . . H(2) H(1) (Backward)

       STOREV  (global input) CHARACTER
               Specifies how the vectors which define the  elementary  reflec-
               tors are stored (see also Further Details):
               = 'R': rowwise

       N       (global input) INTEGER
               The  number  of meaningful entries of the block reflector H.  N
               >= 0.

       K       (global input) INTEGER
               The order of the triangular factor T (= the number  of  elemen-
               tary reflectors). 1 <= K <= MB_V (= NB_V).

       V       (input/output) COMPLEX pointer into the local memory
               to  an  array  of  local dimension (LOCr(IV+K-1),LOCc(JV+N-1)).
               The distributed matrix V contains the Householder vectors.  See
               further details.

       IV      (global input) INTEGER
               The row index in the global array V indicating the first row of
               sub( V ).

       JV      (global input) INTEGER
               The column index in the global array  V  indicating  the  first
               column of sub( V ).

       DESCV   (global and local input) INTEGER array of dimension DLEN_.
               The array descriptor for the distributed matrix V.

       TAU     (local input) COMPLEX, array, dimension LOCr(IV+K-1)
               if  INCV = M_V, and LOCc(JV+K-1) otherwise. This array contains
               the Householder scalars related  to  the  Householder  vectors.
               TAU is tied to the distributed matrix V.

       T       (local output) COMPLEX array, dimension (MB_V,MB_V)
               It contains the k-by-k triangular factor of the block reflector
               associated with V. T is lower triangular.

       WORK    (local workspace) COMPLEX array,
               dimension (K*(K-1)/2)

FURTHER DETAILS
       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;  the  corresponding  array
       elements  are  modified  but restored on exit. The rest of the array is
       not used.

       DIRECT = 'F' and STOREV = 'C':         DIRECT = 'F' and STOREV = 'R':

                                                   ______V_____
              ( v1 v2 v3 )                        |            |
              ( v1 v2 v3 )                      ( v1 v1 v1 v1 v1 . . . . 1 )
          V = ( v1 v2 v3 )                      ( v2 v2 v2 v2 v2 . . . 1   )
              ( v1 v2 v3 )                      ( v3 v3 v3 v3 v3 . . 1     )
              ( v1 v2 v3 )
                 .  .  .
                 .  .  .
                 1  .  .
                    1  .
                       1

       DIRECT = 'B' and STOREV = 'C':         DIRECT = 'B' and STOREV = 'R':

                                                             ______V_____
                 1                                          |            |
                 .  1                           ( 1 . . . . v1 v1 v1 v1 v1 )
                 .  .  1                        ( . 1 . . . v2 v2 v2 v2 v2 )
                 .  .  .                        ( . . 1 . . v3 v3 v3 v3 v3 )
                 .  .  .
              ( v1 v2 v3 )
              ( v1 v2 v3 )
          V = ( v1 v2 v3 )
              ( v1 v2 v3 )
              ( v1 v2 v3 )




ScaLAPACK routine               31 October 2017                     PCLARZT(3)