Household Reflector APIs#

LARF#

group larf

Functions

template<typename T>
void larf(char *side, integer *m, integer *n, T *v, integer *incv, T *tau, T *c, integer *ldc, T *work)#

LARF applies an elementary reflector to a general rectangular matrix.

Purpose:

 LARF applies a real elementary reflector H to a real m by n matrix
 C, from either the left or the right. H is represented in the form

       H = I - tau * v * v**T

 where tau is a real scalar and v is a real vector.

 If tau = 0, then H is taken to be the unit matrix.

Parameters:
  • SIDE – [in]

    SIDE is CHARACTER*1

    = ‘L’: form H * C

    = ‘R’: form C * H

  • M – [in]

    M is INTEGER

    The number of rows of the matrix C.

  • N – [in]

    N is INTEGER

    The number of columns of the matrix C.

  • V – [in]

    V is REAL array, dimension

    (1 + (M-1)*abs(INCV)) if SIDE = ‘L’

    or (1 + (N-1)*abs(INCV)) if SIDE = ‘R’

    The vector v in the representation of H. V is not used if TAU = 0.

  • INCV – [in]

    INCV is INTEGER

    The increment between elements of v. INCV <> 0.

  • TAU – [in]

    TAU is REAL

    The value tau in the representation of H.

  • C – [inout]

    C is REAL array, dimension (LDC,N)

    On entry, the m by n matrix C.

    On exit, C is overwritten by the matrix H * C if SIDE = ‘L’, or C * H if SIDE = ‘R’.

  • LDC – [in]

    LDC is INTEGER

    The leading dimension of the array C. LDC >= fla_max(1,M).

  • WORK – [out]

    WORK is REAL array, dimension

    (N) if SIDE = ‘L’

    or (M) if SIDE = ‘R’

LARFX#

group larfx

Functions

template<typename T>
void larfx(char *side, integer *m, integer *n, T *v, T *tau, T *c, integer *ldc, T *work)#

LARFX applies an elementary reflector to a general rectangular matrix,

with loop unrolling when the reflector has order ≤ 10.

Purpose:

  LARFX applies a real elementary reflector H to a real m by n
  matrix C, from either the left or the right. H is represented in the
  form
        H = I - tau * v * v**T

  where tau is a real scalar and v is a real vector.

  If tau = 0, then H is taken to be the unit matrix

  This version uses inline code if H has order < 11.

Parameters:
  • SIDE – [in]

    SIDE is CHARACTER*1

    = ‘L’: form H * C

    = ‘R’: form C * H

  • M – [in]

    M is INTEGER

    The number of rows of the matrix C.

  • N – [in]

    N is INTEGER

    The number of columns of the matrix C.

  • V – [in]

    V is REAL array, dimension (M) if SIDE = ‘L’ or (N) if SIDE = ‘R’

    The vector v in the representation of H.

  • TAU – [in]

    TAU is REAL

    The value tau in the representation of H.

  • C – [inout]

    C is REAL array, dimension (LDC,N)

    On entry, the m by n matrix C.

    On exit, C is overwritten by the matrix H * C if SIDE = ‘L’, or C * H if SIDE = ‘R’.

  • LDC – [in]

    LDC is INTEGER

    The leading dimension of the array C. LDC >= (1,M).

  • WORK – [out]

    WORK is REAL array, dimension (N) if SIDE = ‘L’ or (M) if SIDE = ‘R’

    WORK is not referenced if H has order < 11.

LARFY#

group larfy

Functions

template<typename T>
void larfy(char *uplo, integer *n, T *v, integer *incv, T *tau, T *c, integer *ldc, T *work)#

LARFY applies an elementary reflector, or Householder matrix, H,

to an n x n symmetric matrix C, from both the left and the right.

Purpose:

 LARFY applies an elementary reflector, or Householder matrix, H,
 to an n x n symmetric matrix C, from both the left and the right.

 H is represented in the form

    H = I - tau * v * v'

 where  tau  is a scalar and  v  is a vector.

 If  tau  is  zero, then  H  is taken to be the unit matrix.

Parameters:
  • UPLO – [in]

    UPLO is CHARACTER*1

    Specifies whether the upper or lower triangular part of the symmetric matrix C is stored.

    = ‘U’: Upper triangle

    = ‘L’: Lower triangle

  • N – [in]

    N is INTEGER

    The number of rows and columns of the matrix C. N >= 0.

  • V – [in]

    V is REAL array, dimension (1 + (N-1)*abs(INCV))

    The vector v as described above.

  • INCV – [in]

    INCV is INTEGER

    The increment between successive elements of v. INCV must not be zero.

  • TAU – [in]

    TAU is REAL

    The value tau as described above.

  • C – [inout]

    C is REAL array, dimension (LDC, N)

    On entry, the matrix C. On exit, C is overwritten by H * C * H’.

  • LDC – [in]

    LDC is INTEGER

    The leading dimension of the array C. LDC >= fla_max(1, N).

  • WORK – [out] WORK is REAL array, dimension (N)

LARFB#

group larfb

Functions

template<typename T>
void larfb(char *side, char *trans, char *direct, char *storev, integer *m, integer *n, integer *k, T *v, integer *ldv, T *t, integer *ldt, T *c, integer *ldc, T *work, integer *ldwork)#

LARFB applies a block reflector or its transpose to a general rectangular matrix.

Purpose:

  LARFB applies a real block reflector H or its transpose H**T to a
  real m by n matrix C, from either the left or the right.

Parameters:
  • SIDE – [in]

    SIDE is CHARACTER*1

    = ‘L’: apply H or H**T from the Left

    = ‘R’: apply H or H**T from the Right

  • TRANS – [in]

    TRANS is CHARACTER*1

    = ‘N’: apply H (No transpose)

    = ‘T’: apply H**T (Transpose)

  • DIRECT – [in]

    DIRECT is CHARACTER*1

    Indicates how H is formed from a product of elementary reflectors

    = ‘F’: H = H(1) H(2) … H(k) (Forward)

    = ‘B’: H = H(k) … H(2) H(1) (Backward)

  • STOREV – [in]

    STOREV is CHARACTER*1

    Indicates how the vectors which define the elementary reflectors are stored:

    = ‘C’: Columnwise

    = ‘R’: Rowwise

  • M – [in]

    M is INTEGER

    The number of rows of the matrix C.

  • N – [in]

    N is INTEGER

    The number of columns of the matrix C.

  • K – [in]

    K is INTEGER

    The order of the matrix T (= the number of elementary reflectors whose product defines the block reflector).

    If SIDE = ‘L’, M >= K >= 0;

    if SIDE = ‘R’, N >= K >= 0.

  • V – [in]

    V is REAL array, dimension

    (LDV,K) if STOREV = ‘C’

    (LDV,M) if STOREV = ‘R’ and SIDE = ‘L’

    (LDV,N) if STOREV = ‘R’ and SIDE = ‘R’

    The matrix V. See Further Details.

  • LDV – [in]

    LDV is INTEGER

    The leading dimension of the array V.

    If STOREV = ‘C’ and SIDE = ‘L’, LDV >= fla_max(1,M);

    if STOREV = ‘C’ and SIDE = ‘R’, LDV >= fla_max(1,N);

    if STOREV = ‘R’, LDV >= K.

  • T – [in]

    T is REAL array, dimension (LDT,K)

    The triangular k by k matrix T in the representation of the block reflector.

  • LDT – [in]

    LDT is INTEGER

    The leading dimension of the array T. LDT >= K.

  • C – [inout]

    C is REAL array, dimension (LDC,N)

    On entry, the m by n matrix C.

    On exit, C is overwritten by H*C or H**T*C or C*H or C*H**T.

  • LDC – [in]

    LDC is INTEGER

    The leading dimension of the array C. LDC >= fla_max(1,M).

  • WORK – [out] WORK is REAL array, dimension (LDWORK,K)

  • LDWORK – [in]

    LDWORK is INTEGER

    The leading dimension of the array WORK.

    If SIDE = ‘L’, LDWORK >= fla_max(1,N);

    if SIDE = ‘R’, LDWORK >= fla_max(1,M).

LARFG#

group larfg

Functions

template<typename T>
void larfg(integer *n, T *alpha, T *x, integer *incx, T *tau)#

Generation of an elementary reflector (Householder matrix)

Purpose:

    Generation of a real elementary reflector (Householder matrix) H of order n, such that

    H * ( alpha) = ( beta),   H**T * H = I.
    (   X  )   (   0 )

    where alpha and beta are scalars, and X is an (n-1)-element real vector.
    H is represented in the form

    H = I - tau * ( 1) * ( 1 v**T) ,
    ( v)

    where tau is a real scalar and v is a real (n-1)-element vector.

    If the elements of X are all zero, then tau = 0 and H is taken to be the unit matrix.

    Otherwise  1 <= tau <= 2.

Parameters:
  • n – [in]

    n is integer*

    The order of the elementary reflector.

  • alpha – [inout]

    alpha is float/double/COMPLEX/COMPLEX*16*

    On entry, the value alpha.

    On exit, it is overwritten with the value beta.

  • x – [inout]

    x is float/double/COMPLEX/COMPLEX*16 array, dimension (1+(N-2)*abs(incx))

    On entry, the vector x.

    On exit, it is overwritten with the vector v.

  • incx – [in]

    incx is integer*

    The increment between elements of X. incx > 0.

  • tau – [out]

    tau is float/double/COMPLEX/COMPLEX*16*

    The value tau.

LARFGP#

group larfgp

Functions

template<typename T>
void larfgp(integer *n, T *alpha, T *x, integer *incx, T *tau)#

Generation of an elementary reflector (Householder matrix) with non-negative beta.

Purpose:

    Generation of a real elementary reflector H (Householder matrix) with non-negative beta
    of order n, such that

    H * ( alpha) = ( beta),   H**T * H = I.
    (   x  )   (   0 )

    where alpha and beta are scalars, beta is non-negative, and x is an (n-1)-element real
vector. H is represented in the form

    H = I - tau * ( 1) * ( 1 v**T) ,
    ( v)

    where tau is a real scalar and v is a real (n-1)-element vector.

    If the elements of x are all zero, then tau = 0 and H is taken to be the unit matrix.

Parameters:
  • n – [in]

    n is integer*

    The order of the elementary reflector.

  • alpha – [inout]

    alpha is float/double/COMPLEX/COMPLEX*16*

    On entry, the value alpha.

    On exit, it is overwritten with the value beta.

  • x – [inout]

    x is float/double/COMPLEX/COMPLEX*16 array, dimension (1+(N-2)*abs(incx))

    On entry, the vector x.

    On exit, it is overwritten with the vector v.

  • incx – [in]

    incx is integer*

    The increment between elements of X. incx > 0.

  • tau – [out]

    tau is float/double/COMPLEX/COMPLEX*16*

    The value tau.

LARFT#

group larft

Functions

template<typename T>
void larft(char *direct, char *storev, integer *n, integer *k, T *v, integer *ldv, T *tau, T *t, integer *ldt)#

Triangular factor of a block reflector.

Purpose:

    Formation of the triangular factor T of a real 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**T

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

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.

                  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)

Parameters:
  • direct – [in]

    direct is char*

    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)

  • storev – [in]

    storev is char*

    Specifies how the vectors which define the elementary reflectors are stored (see also Further Details):

    = ‘C’: columnwise

    = ‘R’: rowwise

  • n – [in]

    n is integer*

    The order of the block reflector H. n >= 0.

  • k – [in]

    k is integer*

    The order of the triangular factor T (= the number of elementary reflectors). K >= 1.

  • v – [in]

    v is float/double/COMPLEX/COMPLEX*16 array, dimension

    (ldv,k) if storev = ‘C’

    (ldv,k) if storev = ‘R’

    The matrix v. See further details.

  • ldv – [in]

    ldv is integer*

    The leading dimension of the array V.

    If storev = ‘C’, ldv >= fla_max(1,n); if storev = ‘R’, ldv >= k.

  • tau – [in]

    tau is float/double/COMPLEX/COMPLEX*16 array, dimension (k)

    tau(i) must contain the scalar factor of the elementary reflector H(i).

  • t – [out]

    t is float/double/COMPLEX/COMPLEX*16 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.

  • ldt – [in]

    ldt is integer*

    The leading dimension of the array T. ldt >= k.