====================================================================
drotg examples
====================================================================

A Givens rotation is a rotation in the plane spanned by two 
coordinate axes, named after Wallace Givens. [REF-Wiki3]
 
A Givens rotation is represented by a matrix of the form

               +-                         -+
               | 1  ...  0  ...  0  ...  0 |
               | .  .    .  .    .  .    . |
               | .   .   .   .   .   .   . |
               | .    .  .    .  .    .  . |
               | 0  ...  c  ... -s  ...  0 |
               | .  .    .  .    .  .    . |
G(i,j,theta) = | .   .   .   .   .   .   . |
               | .    .  .    .  .    .  . |
               | 0  ...  s  ...  c  ...  0 |
               | .  .    .  .    .  .    . |
               | .   .   .   .   .   .   . |
               | .    .  .    .  .    .  . |
               | 0  ...  0  ...  0  ...  1 |
               +-                         -+

where c = cos(theta) and s = sin(theta) appear at the intersections
of the ith, jth rows and columns. The non-zero elements of a Givens
matrix are given by:

g   = 1 for k != i,j
 kk
g   = c
 ii
g   = c              (sign of sine switches for j>i)
 jj
g   = -s
 ji
g   = s  for i > j
 ij

The product G(i,j,theta)*x represents the counterclockwise rotation
of the vector in the (i,j) plane of theta radians. 

The main use of Givens rotations in numerical linear algebra is to
introduce zeros in vectors or matrices. This effect can be employed
for computing the QR decomposition of a matrix. One advantage over
the Householder tranformations is that they can easily be parallelized,
and another is that often for very sparse matrices they have a lower
operation count.

When a Givens rotation matrix, G(i,k,theta) multiplies another 
matrix A from the left, GA, only rows i and j of A are affected.
Thus we restrict attention to the following problem. Given a and b,
find c=cos(theta) and s=sin(theta) such that

+-     -+ +- -+   +- -+
| c  -s | | a |   | r |
|       | |   | = |   |
| s   c | | b |   | 0 |
+-     -+ +- -+   +- -+

The solution is

r = sqrt(a^2+b^2)
c = a/r
s = -b/r

However, the computation for r may overflow or underflow. An alternative
formulation avoiding this problem [REF-GC96, p5.1.8] is implemented as the
hypot function in many programming languages.

As Anderson [REF-And00] discovered in improving LAPACK, a previously
overlooked numerical consideration is continuity. To achieve this
we require r to be positive.

   if (b = 0) then { c = copysign(1,a); s=0; r=abs(a) }
   else if (a = 0) then { c = 0; s = copysign(1,b); r = abs(b) }
   else if (abs(b) > abs(a)) then
     t = a/b
     u = copysign(sqrt(1+t*t),b)
     s = 1/u
     c = s*t
     r = b*u
   else
     t = b/a
     u = copysign(sqrt(1+t*t),a)
     c = 1/u
     s = c*t
     r = a*u

copysign can be implemented as x*sgn(y) using the sign function.

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

NAME
       DGROTG - BLAS level one rotation subroutines

SYNOPSIS
       SUBROUTINE DROTG    ( a, b, c, s )

           DOUBLE PRECISION  a, b, c, s


DESCRIPTION
       DROTG  computes  the  elements  of  a Givens plane rotation matrix such
       that:

             _      _     _   _    _   _
             | c  s |     | a |    | r |
             |-s  c | *   | b | =  | 0 |
             -      -     -   -    -   -

       where  r = +- sqrt ( a**2 + b**2 )  and c**2 + s**2 =1.

       The Givens plane rotation can be used to introduce zero elements into
       a matrix selectively.



ARGUMENTS
       a       (input and output) DOUBLE PRECISION

               First vector component.  On input, the first component  of  the
               vector to be rotated.  On output, a is overwritten by r, the
               first component of the vector in the rotated coordinate  system
               where:

               r = sign(sqrt(a**2 + b**2),a), if |a| > |b|

               r = sign(sqrt(a**2 + b**2),b), if |a| <= |b|

       b       (input and output) DOUBLE PRECISION
               Second vector component.

               On input, the second component of the vector to be rotated.  On
               output, b contains z, where:

                   z=s    if  |a| >  |b|
                   z=1/c  if  |a| <= |b|  and  c != 0  and r != 0
                   z=1    if  |a| <= |b|  and  c  = 0  and r != 0
                   z=0    if  r = 0

       c       (output) DOUBLE PRECISION
               Cosine of the angle of rotation:

                    c = a/r  if  r != 0
                    c = 1    if  r  = 0

       s       (output) DOUBLE PRECISION
               Sine of the angle of rotation:

                    s = b/r  if  r != 0
                    s = 0    if  r  = 0


NOTE
       The value of z, returned in b by DROTG, gives a compact  representation
       of  the rotation matrix, which can be used later to reconstruct c and s
       as in the following example:

            IF (B .EQ. 1. ) THEN
                C = 0.
                S = 1.
            ELSEIF( ABS( B) .LT. 1) THEN
                C = SQRT( 1. - B * B)
                S = B
            ELSE
                C = 1. / B
                S = SQRT( 1 - C * C)
            ENDIF

