Package org.flag4j.linalg.transformations

Class Givens

java.lang.Object

org.flag4j.linalg.transformations.Givens

public final class Givens
extends Object

This class contains methods for computing real or complex Givens' rotation matrices. A Givens' rotator is a square matrix G(i, k, theta) which, when left multiplied to a vector, represents a counterclockwise rotation of theta radians of the vector in the (i, j) plane. Givens rotators are a unitary transformation.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Givens()

Method Summary

Modifier and Type	Method	Description
static Matrix	get2x2Rotator(double v0, double v1)	Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].
static CMatrix	get2x2Rotator(CVector v)	Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].
static Matrix	get2x2Rotator(Vector v)	Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].
static CMatrix	get2x2Rotator(CNumber v0, CNumber v1)	Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].
static Matrix	getGeneralRotator(int size, int i, int j, double theta)	Constructs a general Givens rotation matrix.
static Matrix	getRotator(double[] v, int i)	Constructs a Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where ri=0.
static CMatrix	getRotator(CVector v, int i)	Constructs a Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where ri=0.
static Matrix	getRotator(Vector v, int i)	Constructs a Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where ri=0.
static void	leftMult2x2Rotator(CMatrix src, CMatrix G, int row, CNumber[] workArray)	Left multiplies a 2x2 Givens rotator to a matrix at the specified row.
static void	leftMult2x2Rotator(Matrix src, Matrix G, int row, double[] workArray)	Left multiplies a 2x2 Givens rotator to a matrix at the specified row.
static void	rightMult2x2Rotator(CMatrix src, CMatrix G, int row, CNumber[] workArray)	Right multiplies a 2x2 Givens rotator to a matrix at the specified row.
static void	rightMult2x2Rotator(Matrix src, Matrix G, int row, double[] workArray)	Right multiplies a 2x2 Givens rotator to a matrix at the specified row.
private static double[]	stableTrigVals(double a, double b)	Computes the sine and cosine values for a Givens' rotation in a stable manner which avoids any possibility of overflow.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Givens

private Givens()

Method Details

getGeneralRotator

public static Matrix getGeneralRotator(int size,
 int i,
 int j,
 double theta)

Constructs a general Givens rotation matrix. This method can be numerically unstable. See getRotator(Vector, int) if the goal is to zero an element of a vector using a Givens rotator. This method will produce more accurate results in general and is more robust to overflows.

Parameters:

size - The size of the Givens' rotation matrix.

i - Index of the first axis to rotate through.

j - Index of the second axis to rotate through.

theta - Angle in radians of rotation through the (i, j) plane.

Returns:

A Givens' rotation matrix with specified size which, when left multiplied to a vector, represents a counterclockwise rotation of theta radians of the vector in the (i, j) plane.

Throws:

IndexOutOfBoundsException - If i or j is greater than or equal to size.

getRotator

public static Matrix getRotator(Vector v,
 int i)

Constructs a Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where r_i=0. That is, when the rotator G is left multiplied to the vector v, it zeros out the entry at position i.

Parameters:

v - Vector to construct Givens rotator for.

i - Position to zero out when applying the rotator to v.

Returns:

A Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where r_i=0.

Throws:

IndexOutOfBoundsException - If i is not in the range [0, v.size).

getRotator

public static Matrix getRotator(double[] v,
 int i)

Constructs a Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where r_i=0. That is, when the rotator G is left multiplied to the vector v, it zeros out the entry at position i.

Parameters:

v - Vector to construct Givens rotator for.

i - Position to zero out when applying the rotator to v.

Returns:

A Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where r_i=0.

Throws:

IndexOutOfBoundsException - If i is not in the range [0, v.size).

getRotator

public static CMatrix getRotator(CVector v,
 int i)

Constructs a Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where r_i=0. That is, when the rotator G is left multiplied to the vector v, it zeros out the entry at position i.

Parameters:

v - Vector to construct Givens rotator for.

i - Position to zero out when applying the rotator to v.

Returns:

A Givens rotator G such that for a vector v, Gv = [r<sub>1</sub> ... r<sub>i</sub> ... r<sub>n</sub>] where r_i=0.

Throws:

IndexOutOfBoundsException - If i is not in the range [0, v.size).

get2x2Rotator

public static Matrix get2x2Rotator(Vector v)

Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].

Parameters:

v - Vector of size 2 to construct Givens rotator for.

Returns:

A Givens rotator G of size 2 such that for a vector v = [a, b] we have Gx = [r, 0].

Throws:

IllegalArgumentException - If the vector v is not of size 2.

get2x2Rotator

public static Matrix get2x2Rotator(double v0,
 double v1)

Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].

Parameters:

v0 - First entry in vector to construct rotator for.

v1 - Second entry in vector to construct rotator for.

Returns:

A Givens rotator G of size 2 such that for a vector v = [a, b] we have Gx = [r, 0].

Throws:

IllegalArgumentException - If the vector v is not of size 2.

leftMult2x2Rotator

public static void leftMult2x2Rotator(Matrix src,
 Matrix G,
 int row,
 double[] workArray)

Left multiplies a 2x2 Givens rotator to a matrix at the specified row. This is done in place.

Specifically, computes G*A[i-1:i+1][i-1:i+1] where i=row, G is the 2x2 Givens rotator, A is the matrix to apply the reflector to, and A[i-1:i+1][i-1:] represents the slice of A the reflector effects which has shape (2, A.numCols - i - 1).

This method is likely to be faster than computing this multiplication explicitly.

Parameters:

src - The matrix to left multiply the rotator to (modified).

G - The 2x2 givens rotator. Note, the size is not explicitly checked.

row - The row to the rotator is being applied to.

workArray - Array to store temporary values. If null, a new array will be created (modified).

Throws:

ArrayIndexOutOfBoundsException - If the workArray is not at least large enough to store the 2*(A.numCols - i - 1) entries.

rightMult2x2Rotator

public static void rightMult2x2Rotator(Matrix src,
 Matrix G,
 int row,
 double[] workArray)

Right multiplies a 2x2 Givens rotator to a matrix at the specified row. This is done in place

Specifically, computes A[:][i-1:i+1]*G^H where i=row, G is the 2x2 Givens rotator, A is the matrix to apply the reflector to, and A[:i+1][i-1:i+1] represents the slice of A the reflector effects which has shape (row+1, 2).

This method is likely to be faster than computing this multiplication explicitly.

Parameters:

src - The matrix to left multiply the rotator to (modified).

G - The 2x2 givens rotator. Note, the size is not explicitly checked.

row - The row to the rotator is being applied to.

workArray - Array to store temporary values. If null, a new array will be created (modified). If the workArray is not at least large enough to store the 2*(row+1) entries.

leftMult2x2Rotator

public static void leftMult2x2Rotator(CMatrix src,
 CMatrix G,
 int row,
 CNumber[] workArray)

Left multiplies a 2x2 Givens rotator to a matrix at the specified row. This is done in place.

Specifically, computes G*A[i-1:i+1][i-1:i+1] where i=row, G is the 2x2 Givens rotator, A is the matrix to apply the reflector to, and A[i-1:i+1][i-1:] represents the slice of A the reflector effects which has shape (2, A.numCols - i - 1).

This method is likely to be faster than computing this multiplication explicitly.

Parameters:

src - The matrix to left multiply the rotator to (modified).

G - The 2x2 givens rotator. Note, the size is not explicitly checked.

row - The row to the rotator is being applied to.

workArray - Array to store temporary values. If null, a new array will be created (modified). If the workArray is not at least large enough to store the 2*(A.numCols - i - 1) entries.

rightMult2x2Rotator

public static void rightMult2x2Rotator(CMatrix src,
 CMatrix G,
 int row,
 CNumber[] workArray)

Right multiplies a 2x2 Givens rotator to a matrix at the specified row. This is done in place

Specifically, computes A[:][i-1:i+1]*G^H where i=row, G is the 2x2 Givens rotator, A is the matrix to apply the reflector to, and A[:i +1][i -1:i+1] represents the slice of A the reflector effects which has shape (row+1, 2).

This method is likely to be faster than computing this multiplication explicitly.

Parameters:

src - The matrix to left multiply the rotator to (modified).

G - The 2x2 givens rotator. Note, the size is not explicitly checked.

row - The row to the rotator is being applied to.

workArray - Array to store temporary values. If null, a new array will be created (modified). If the workArray is not at least large enough to store the 2*(row+1) entries.

get2x2Rotator

public static CMatrix get2x2Rotator(CVector v)

Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].

Parameters:

v - Vector to construct Givens rotator for.

Returns:

A Givens rotator G of size 2 such that for a vector v = [a, b] we have Gx = [r, 0].

Throws:

IllegalArgumentException - If the vector v is not of size 2.

get2x2Rotator

public static CMatrix get2x2Rotator(CNumber v0,
 CNumber v1)

Constructs a Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].

Parameters:

v0 - First entry in vector to construct rotator for.

v1 - Second entry in vector to construct rotator for.

Returns:

A Givens rotator G of size 2 such that for a vector v = [a, b] we have Gx = [r, 0].

Throws:

IllegalArgumentException - If the vector v is not of size 2.

stableTrigVals

private static double[] stableTrigVals(double a,
 double b)

Computes the sine and cosine values for a Givens' rotation in a stable manner which avoids any possibility of overflow.

Returns:

An array of length two containing in order the cosine value and sine value for the Givens' rotation.