org.flag4j.linalg.transformations.Givens

public final class Givens extends Object

Utility class for constructing and applying Givens rotation matrices for both real and complex-valued matrices.

Givens rotations are orthogonal (unitary in the complex case) transformations used in numerical linear algebra for applications such as QR decomposition, Hessenberg reduction, and least-squares solutions. A Givens rotation is a matrix G(i, j, θ) which, when left multiplied to a vector, represents a counterclockwise rotation of θ radians of the vector in the (i, j) plane.

Supported Operations:

General Givens rotation matrices for arbitrary rotation angles.
Specialized rotators for zeroing elements in a given vector.
Efficient 22 Givens rotations for small-scale transformations.
Optimized left and right multiplication of 2×2 rotators for structured matrices.

Usage Examples:

Creating a General Givens Rotation Matrix.


 int size = 5;
 int i = 1, j = 3;
 double theta = Math.PI / 4.0;  // 45-degree rotation.
 Matrix G = Givens.getGeneralRotator(size, i, j, theta);

Creating a General Givens Rotation Matrix.


 int size = 5;
 int i = 1, j = 3;
 double theta = Math.PI / 4.0;  // 45-degree rotation
 Matrix G = Givens.getGeneralRotator(size, i, j, theta);

Constructing a Rotator to Zero an Element.


 Vector v = new Vector(3.0, 4.0, 5.0);
 Matrix G = Givens.getRotator(v, 1);  // Rotates to zero v[1]

Applying a 2×2 Givens Rotator.


 Matrix A = ...;  // Some matrix
 Matrix G = Givens.get2x2Rotator(3.0, 4.0);
 Givens.leftMult2x2Rotator(A, G, 2, null);  // Applies G at row 2 efficiently.

All methods in this class are static, as the class is not instantiable and should be used as a utility class.

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(Complex128 v0, Complex128 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 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₁ ... r_i ... r_n] where r_i=0.

static CMatrix

getRotator(CVector v, int i)

Constructs a Givens rotator G such that for a vector v, Gv = [r₁ ... r_i ... r_n] where r_i=0.

static Matrix

getRotator(Vector v, int i)

Constructs a Givens rotator G such that for a vector v, Gv = [r₁ ... r_i ... r_n] where r_i=0.

static void

leftMult2x2Rotator(CMatrix src, CMatrix G, int row, Complex128[] workArray)

Left multiplies a 2×2 Givens rotator to a matrix at the specified row.

static void

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

Left multiplies a 2×2 Givens rotator to a matrix at the specified row.

static void

rightMult2x2Rotator(CMatrix src, CMatrix G, int row, Complex128[] workArray)

Right multiplies a 2×2 Givens rotator to a matrix at the specified row.

static void

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

Right multiplies a 2×2 Givens rotator to a matrix at the specified row.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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₁ ... r_i ... r_n] 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 v 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₁ ... r_i ... r_n] 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₁ ... r_i ... r_n] 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 v 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₁ ... r_i ... r_n] 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₁ ... r_i ... r_n] 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 v 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₁ ... r_i ... r_n] 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 v 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 Gv = [r, 0].
  
  Throws:
  
  IllegalArgumentException - If v.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 v to construct rotator for.
  
  v1 - Second entry in vector v to construct rotator for.
  
  Returns:
  
  A Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].
- leftMult2x2Rotator
  
  public static void leftMult2x2Rotator(Matrix src, Matrix G, int row, double[] workArray)
  
  Left multiplies a 2×2 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 2×2 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 2×2 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) data.
- rightMult2x2Rotator
  
  public static void rightMult2x2Rotator(Matrix src, Matrix G, int row, double[] workArray)
  
  Right multiplies a 2×2 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 2×2 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 2×2 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) data.
- leftMult2x2Rotator
  
  public static void leftMult2x2Rotator(CMatrix src, CMatrix G, int row, Complex128[] workArray)
  
  Left multiplies a 2×2 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 2×2 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 2×2 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) data.
- rightMult2x2Rotator
  
  public static void rightMult2x2Rotator(CMatrix src, CMatrix G, int row, Complex128[] workArray)
  
  Right multiplies a 2×2 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 2×2 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 2×2 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) data.
- 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 v to construct Givens rotator for.
  
  Returns:
  
  A Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].
  
  Throws:
  
  IllegalArgumentException - If v.size != 2.
- get2x2Rotator
  
  public static CMatrix get2x2Rotator(Complex128 v0, Complex128 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 v to construct rotator for.
  
  v1 - Second entry in vector v to construct rotator for.
  
  Returns:
  
  A Givens rotator G of size 2 such that for a vector v = [a, b] we have Gv = [r, 0].
  
  Throws:
  
  IllegalArgumentException - If v.size != 2.

Class Givens

Supported Operations:

Usage Examples:

Method Summary

Methods inherited from class java.lang.Object

Method Details

getGeneralRotator

getRotator

getRotator

getRotator

get2x2Rotator

get2x2Rotator

leftMult2x2Rotator

rightMult2x2Rotator

leftMult2x2Rotator

rightMult2x2Rotator

get2x2Rotator

get2x2Rotator