Givens/Jacobi Plane Rotations APIs#

LARTG#

group lartg_jacobi

Functions

template<typename T>
void lartg(T *f, T *g, T *cs, T *sn, T *r__)#

LARTG generates a plane rotation with real cosine and real sine.

Purpose:

   LARTG generate a plane rotation so that

      [  CS  SN  ]  .  [ F ]  =  [ R ]   where CS**2 + SN**2 = 1.
      [ -SN  CS  ]     [ G ]     [ 0 ]

   This is a slower, more accurate version of the BLAS1 routine SROTG,
   with the following other differences:
      F and G are unchanged on   return.
      If G=0, then CS=1 and SN=0.
      If F=0 and (G .ne. 0), then CS=0 and SN=1 without doing any
         floating point operations (saves work in SBDSQR when
         there are zeros on the diagonal).

   If F exceeds G in magnitude, CS will be positive.

Parameters:
  • F – [in]

    F is REAL

    The first component of vector to be rotated.

  • G – [in]

    G is REAL

    The second component of vector to be rotated.

  • CS – [out]

    CS is REAL

    The cosine of the rotation.

  • SN – [out]

    SN is REAL

    The sine of the rotation.

  • R – [out]

    R is REAL

    The nonzero component of the rotated vector.

    This version has a few statements commented out for thread safety (machine parameters are computed on each entry). 10 feb 03, SJH.

template<typename T, typename Ta>
void lartg(T *f, T *g, Ta *cs, T *sn, T *r__)#

LARTGP#

group lartgp

Functions

template<typename T>
void lartgp(T *f, T *g, T *cs, T *sn, T *r)#

LARTGP generates a plane rotation so that the diagonal is nonnegative.

Purpose:

   LARTGP generates a plane rotation so that

      [  CS  SN  ]  .  [ F ]  =  [ R ]   where CS**2 + SN**2 = 1.
      [ -SN  CS  ]     [ G ]     [ 0 ]

   This is a slower, more accurate version of the Level 1 BLAS routine SROTG,
   with the following other differences:
      F and G are unchanged on return.
      If G=0, then CS=(+/-)1 and SN=0.
      If F=0 and (G .ne. 0), then CS=0 and SN=(+/-)1.

   The sign is chosen so that R >= 0.

Parameters:
  • F – [in]

    F is REAL

    The first component of vector to be rotated.

  • G – [in]

    G is REAL

    The second component of vector to be rotated.

  • CS – [out]

    CS is REAL

    The cosine of the rotation.

  • SN – [out]

    SN is REAL

    The sine of the rotation.

  • R – [out]

    R is REAL

    The nonzero component of the rotated vector.

    This version has a few statements commented out for thread safety (machine parameters are computed on each entry). 10 feb 03, SJH.

LASR#

group lasr

Functions

template<typename T>
void lasr(char *side, char *pivot, char *direct, integer *m, integer *n, T *c, T *s, T *a, integer *lda)#

LASR applies a sequence of plane rotations to a general rectangular matrix.

Purpose:

 LASR applies a sequence of plane rotations to a real matrix A,
 from either the left or the right.

 When SIDE = 'L', the transformation takes the form

    A := P*A

 and when SIDE = 'R', the transformation takes the form

    A := A*P**T

 where P is an orthogonal matrix consisting of a sequence of z plane
 rotations, with z = M when SIDE = 'L' and z = N when SIDE = 'R',
 and P**T is the transpose of P.

 When DIRECT = 'F' (Forward sequence), then

    P = P(z-1) * ... * P(2) * P(1)

 and when DIRECT = 'B' (Backward sequence), then

    P = P(1) * P(2) * ... * P(z-1)

 where P(k) is a plane rotation matrix defined by the 2-by-2 rotation

    R(k) = ( c(k)  s(k))
         = (-s(k)  c(k)).

 When PIVOT = 'V' (Variable pivot), the rotation is performed
 for the plane (k,k+1), i.e., P(k) has the form

    P(k) = ( 1                                           )
           (      ...                                    )
           (             1                               )
           (                  c(k)  s(k)                 )
           (                 -s(k)  c(k)                 )
           (                               1             )
           (                                    ...      )
           (                                           1 )

 where R(k) appears as a rank-2 modification to the identity matrix in
 rows and columns k and k+1.

 When PIVOT = 'T' (Top pivot), the rotation is performed for the
 plane (1,k+1), so P(k) has the form

    P(k) = ( c(k)                    s(k)                )
           (        1                                    )
           (             ...                             )
           (                    1                        )
           (-s(k)                    c(k)                )
           (                                1            )
           (                                     ...     )
           (                                            1)

 where R(k) appears in rows and columns 1 and k+1.

 Similarly, when PIVOT = 'B' (Bottom pivot), the rotation is
 performed for the plane (k,z), giving P(k) the form

    P(k) = (1                                            )
           (     ...                                     )
           (            1                                )
           (                 c(k)                    s(k))
           (                        1                    )
           (                             ...             )
           (                                    1        )
           (                -s(k)                    c(k))

 where R(k) appears in rows and columns k and z.  The rotations are
 performed without ever forming P(k) explicitly.

Parameters:
  • SIDE – [in]

    SIDE is CHARACTER*1

    Specifies whether the plane rotation matrix P is applied to A on the left or the right.

    = ‘L’: Left, compute A := P*A

    = ‘R’: Right, compute A:= A*P**T

  • PIVOT – [in]

    PIVOT is CHARACTER*1

    Specifies the plane for which P(k) is a plane rotation matrix.

    = ‘V’: Variable pivot, the plane (k,k+1)

    = ‘T’: Top pivot, the plane (1,k+1)

    = ‘B’: Bottom pivot, the plane (k,z)

  • DIRECT – [in]

    DIRECT is CHARACTER*1

    Specifies whether P is a forward or backward sequence of plane rotations.

    = ‘F’: Forward, P = P(z-1)*…*P(2)*P(1)

    = ‘B’: Backward, P = P(1)*P(2)*…*P(z-1)

  • M – [in]

    M is INTEGER

    The number of rows of the matrix A. If m <= 1, an immediate return is effected.

  • N – [in]

    N is INTEGER

    The number of columns of the matrix A. If n <= 1, an immediate return is effected.

  • C – [in]

    C is REAL array, dimension

    (M-1) if SIDE = ‘L’

    (N-1) if SIDE = ‘R’

    The cosines c(k) of the plane rotations.

  • S – [in]

    S is REAL array, dimension

    (M-1) if SIDE = ‘L’

    (N-1) if SIDE = ‘R’

    The sines s(k) of the plane rotations. The 2-by-2 plane rotation part of the matrix P(k), R(k), has the form

    R(k) = ( c(k) s(k))

    (-s(k) c(k)).

  • A – [inout]

    A is REAL array, dimension (LDA,N)

    The M-by-N matrix A. On exit, A is overwritten by P*A if SIDE = ‘R’ or by A*P**T if SIDE = ‘L’.

  • LDA – [in]

    LDA is INTEGER

    The leading dimension of the array A. LDA >= fla_max(1,M).

template<typename T, typename Ta>
void lasr(char *side, char *pivot, char *direct, integer *m, integer *n, Ta *c, Ta *s, T *a, integer *lda)#

LARGV#

group largv

Functions

template<typename T>
void largv(integer *n, T *x, integer *incx, T *y, integer *incy, T *c, integer *incc)#

LARGV generates a vector of plane rotations with real cosines and real sines.

Purpose:

 LARGV generates a vector of real plane rotations, determined by
 elements of the real vectors x and y. For i = 1,2,...,n

    ( c(i)  s(i)) (x(i)) = (a(i))
    (-s(i)  c(i)) (y(i)) = (  0 )

Parameters:
  • N – [in]

    N is INTEGER

    The number of plane rotations to be generated.

  • X – [inout]

    X is REAL array, dimension (1+(N-1)*INCX)

    On entry, the vector x. On exit, x(i) is overwritten by a(i), for i = 1,…,n.

  • INCX – [in]

    INCX is INTEGER

    The increment between elements of X. INCX > 0.

  • Y – [inout]

    Y is REAL array, dimension (1+(N-1)*INCY)

    On entry, the vector y. On exit, the sines of the plane rotations.

  • INCY – [in]

    INCY is INTEGER

    The increment between elements of Y. INCY > 0.

  • C – [out]

    C is REAL array, dimension (1+(N-1)*INCC)

    The cosines of the plane rotations.

  • INCC – [in]

    INCC is INTEGER

    The increment between elements of C. INCC > 0.

template<typename T, typename Ta>
void largv(integer *n, T *x, integer *incx, T *y, integer *incy, Ta *c, integer *incc)#

LARTV#

group lartv

Functions

template<typename T>
void lartv(integer *n, T *x, integer *incx, T *y, integer *incy, T *c, T *s, integer *incc)#

LARTV applies a vector of plane rotations with real cosines and

real sines to the elements of a pair of vectors.

Purpose:

 LARTV applies a vector of real plane rotations to elements of the
 real vectors x and y. For i = 1,2,...,n

    (x(i)) := ( c(i)  s(i)) (x(i))
    (y(i))    (-s(i)  c(i)) (y(i))

Parameters:
  • N – [in]

    N is INTEGER

    The number of plane rotations to be applied.

  • X – [inout]

    X is REAL array, dimension (1+(N-1)*INCX)

    The vector x.

  • INCX – [in]

    INCX is INTEGER

    The increment between elements of X. INCX > 0.

  • Y – [inout]

    Y is REAL array, dimension (1+(N-1)*INCY)

    The vector y.

  • INCY – [in]

    INCY is INTEGER

    The increment between elements of Y. INCY > 0.

  • C – [in]

    C is REAL array, dimension (1+(N-1)*INCC)

    The cosines of the plane rotations.

  • S – [in]

    S is REAL array, dimension (1+(N-1)*INCC)

    The sines of the plane rotations.

  • INCC – [in]

    INCC is INTEGER

    The increment between elements of C and S. INCC > 0.

template<typename T, typename Ta>
void lartv(integer *n, T *x, integer *incx, T *y, integer *incy, Ta *c, T *s, integer *incc)#

LAR2V#

group lar2v

Functions

template<typename T>
void lar2v(integer *n, T *x, T *y, T *z, integer *incx, T *c, T *s, integer *incc)#

LAR2V applies a vector of plane rotations with real cosines and real

sines from both sides to a sequence of 2-by-2 symmetric/Hermitian matrices.

Purpose:

 LAR2V applies a vector of real plane rotations from both sides to
 a sequence of 2-by-2 real symmetric matrices, defined by the elements
 of the vectors x, y and z. For i = 1,2,...,n

 (x(i)  z(i)) := ( c(i)  s(i)) (x(i)  z(i)) (c(i) -s(i))
 (z(i)  y(i))    (-s(i)  c(i)) (z(i)  y(i)) (s(i)  c(i))

Parameters:
  • N – [in]

    N is INTEGER

    The number of plane rotations to be applied.

  • X – [inout]

    X is REAL array, dimension (1+(N-1)*INCX)

    The vector x.

  • Y – [inout]

    Y is REAL array, dimension (1+(N-1)*INCX)

    The vector y.

  • Z – [inout]

    Z is REAL array, dimension (1+(N-1)*INCX)

    The vector z.

  • INCX – [in]

    INCX is INTEGER

    The increment between elements of X, Y and Z. INCX > 0.

  • C – [in]

    C is REAL array, dimension (1+(N-1)*INCC)

    The cosines of the plane rotations.

  • S – [in]

    S is REAL array, dimension (1+(N-1)*INCC)

    The sines of the plane rotations.

  • INCC – [in]

    INCC is INTEGER

    The increment between elements of C and S. INCC > 0.

template<typename T, typename Ta>
void lar2v(integer *n, T *x, T *y, T *z, integer *incx, Ta *c, T *s, integer *incc)#

LACRT#

group lacrt

Functions

template<typename T>
void lacrt(integer *n, T *cx, integer *incx, T *cy, integer *incy, T *c, T *s)#

LACRT performs a linear transformation of a pair of complex vectors.

Purpose:

 LACRT performs the operation

    ( c  s)(x)  ==> (x)
    (-s  c)(y)      (y)

 where c and s are complex and the vectors x and y are complex.

Parameters:
  • N – [in]

    N is INTEGER

    The number of elements in the vectors CX and CY.

  • CX – [inout]

    CX is COMPLEX array, dimension (N)

    On input, the vector x. On output, CX is overwritten with c*x + s*y.

  • INCX – [in]

    INCX is INTEGER

    The increment between successive values of CX. INCX <> 0.

  • CY – [inout]

    CY is COMPLEX array, dimension (N)

    On input, the vector y. On output, CY is overwritten with -s*x + c*y.

  • INCY – [in]

    INCY is INTEGER

    The increment between successive values of CY. INCY <> 0.

  • C – [in] C is COMPLEX

  • S – [in]

    S is COMPLEX

    C and S define the matrix

    [ C S ].

    [ -S C ]