Digital

Name

srotg, drotg, crotg, zrotg − Generate elements for a givens plane rotation

FORMAT

{S,D,C.Z}ROTG (a, b, c, s)

Arguments

areal∗4 | real∗8 | complex∗8 | complex∗16
On entry, the first element of the input vector.
On exit, a is overwritten with the rotated element r.

breal∗4 | real∗8 | complex∗8 | complex∗16
On entry, the second element of the input vector. On exit, for SROTG and DROTG, b is overwritten with the reconstruction element z.  For CROTG and ZROTG, b is unchanged.

creal∗4 | real∗8
On entry, an unspecified variable.
On exit, c is overwritten with the first rotation element, that is, the cosine of the angle of rotation.

sreal∗4 | real∗8 | complex∗8 | complex∗16
On entry, an unspecified variable.
On exit, s is overwritten with the second rotation element, that is, the sine of the angle of rotation.

Description

The _ROTG subroutines construct a Givens plane rotation that eliminates the second element of a two-element vector and can be used to introduce zeros selectively into a matrix. 

Using a and b to represent elements of an input real vector, the SROTG and DROTG functions calculate the elements c and s of  an orthogonal matrix such that:

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

Using a and b to represent elements of an input complex vector, the CROTG and ZROTG functions calculate the elements real c and complex s of an orthogonal matrix such that:

            c∗a + s∗b = r
-conjugate(s)∗a + c∗b = 0

A real Givens plane rotation is constructed for values a and b by computing values for r, c, s, and z, as follows:

r=p ∗ (a∗∗(2)+b∗∗(2))∗∗(1/2)

p = SIGN(a)  if  |a| > |b|
p = SIGN(b)  if  |a|<=|b|

c = a/r if r is not equal to 0
c = 1 if r = 0

s = b/r if r is not equal to 0
s = 0 if r = 0

z = s if |a| > |b|
z = 1/c if |a|<=|b|, c is not equal to 0, and r is not equal to 0.
z = 1 if |a|<=|b|, c = 0, and r is not equal to 0.
z = 0 if r = 0

SROTG and DROTG can use the reconstruction element z to store the rotation elements for future use. The quantities c and s are reconstructed from z as follows:

For |z| = 1, c = 0.0  and  s = 1.0

For |z| < 1, c = (1-z∗∗(2))∗∗(1/2) and s = z

For |z| > 1, c = 1/z and s = (1-c∗∗(2))∗∗(1/2)

A complex Givens plane rotation is constructed for values a and b by computing values for real c, complex s and complex r, as follows:

p=(|a|∗∗(2)+|b|∗∗(2))∗∗(1/2)

q = a/|a|

r = qp  if  |a| is not equal to 0. 
r = b  if  |a| is equal to 0.

c = |a|/p if |a| is not equal to 0
c = 0 if |a| is equal to 0

s = q∗conjugate(b)/p if |a| is not equal to 0
s = (1.0,0.0) if |a| is equal to 0

The absolute value used in the above definitions corresponds to the strict definition of the absolute value of a complex number. 

The arguments c and s are passed to the _ROT subroutines. 

Example

REAL∗4 A, B, C, S
CALL SROTG(A,B,C,S)

This FORTRAN code shows how to generate the rotation elements for a vector of elements a and b.