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 for applications such as the QR decomposition, Hessenberg reduction, and least-squares solutions. A Givens rotation is a matrix \( G\left(i, j, \theta \right) \) which, when left multiplied to a vector, represents a counterclockwise rotation of a vector in the \( \left(i, j\right) \) plane by \( \theta \) radians.

Supported Operations:

General Givens rotation matrices for arbitrary rotation angles.
Specialized rotators for zeroing elements in a given vector.
Efficient \( 2\times2 \) Givens rotations for small-scale transformations.
Optimized left and right multiplication of \( 2\times2 \) 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\times2 \) 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 \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).

static CMatrix

get2x2Rotator(CVector v)

Constructs a Givens rotator \( G \) of size 2 such that for a vector \( v = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).

static Matrix

get2x2Rotator(Vector v)

Constructs a Givens rotator \( G \) of size 2 such that for a vector \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).

static CMatrix

get2x2Rotator(Complex128 v0, Complex128 v1)

Constructs a Givens rotator \( G \) of size 2 such that for a vector \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).

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 \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] where \( r_{i} = 0 \).

static CMatrix

getRotator(CVector v, int i)

Constructs a Givens rotator \( G \) such that for a vector \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] where \( r_{i} = 0 \).

static Matrix

getRotator(Vector v, int i)

Constructs a Givens rotator \( G \) such that for a vector \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] where \( r_{i} = 0 \).

static void

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

Left multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i.

static void

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

Left multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i.

static void

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

Right multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i.

static void

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

Right multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i.

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. That 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 \( \left(i, j\right) \) 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 \( \left(i, j\right) \) 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 \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] 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 \( \mathbf{v} \) to construct Givens rotator for.
  
  i - Position to zero out when applying the rotator to \( \mathbf{v} \).
  
  Returns:
  
  A Givens rotator \( G \) such that for a vector \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] 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 \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] where \( r_{i} = 0 \). That is, when the rotator \( G \) is left multiplied to the vector \( \mathbf{v} \), it zeros out the entry at position i.
  
  Parameters:
  
  v - Vector \( \mathbf{v} \) to construct Givens rotator for.
  
  i - Position to zero out when applying the rotator to \( \mathbf{v} \).
  
  Returns:
  
  A Givens rotator \( G \) such that for a vector \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] 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 \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] where \( r_{i} = 0 \). That is, when the rotator \( G \) is left multiplied to the vector \( \mathbf{v} \), it zeros out the entry at position i.
  
  Parameters:
  
  v - Vector \( \mathbf{v} \) to construct Givens rotator for.
  
  i - Position to zero out when applying the rotator to \( \mathbf{v} \).
  
  Returns:
  
  A Givens rotator \( G \) such that for a vector \( \mathbf{v} \), \[ G\mathbf{v} = \begin{bmatrix} r_1 & \cdots & r_i & \cdots r_n \end{bmatrix} \] 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 \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).
  
  Parameters:
  
  v - Vector \( \mathbf{v} \) of size 2 to construct Givens rotator for.
  
  Returns:
  
  A Givens rotator \( G \) of size 2 such that for a vector \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).
  
  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 \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).
  
  Parameters:
  
  v0 - First entry in vector \( \mathbf{v} \) to construct rotator for.
  
  v1 - Second entry in vector \( \mathbf{v} \) to construct rotator for.
  
  Returns:
  
  A Givens rotator \( G \) of size 2 such that for a vector \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).
- leftMult2x2Rotator
  
  public static void leftMult2x2Rotator(Matrix src, Matrix G, int i, double[] workArray)
  
  Left multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i. This is done in place.
  Specifically, computes \( GA\left[i-1:i+1\right]\left[i-1:i+1\right] \) where i=i, \( G \) is the \( 2\times2 \) Givens rotator, \( A \) is the matrix to apply the reflector to, and \( A\left[i-1:i+1\right]\left[i-1:\right] \) 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\times2 \) givens rotator. Note, the size is not explicitly checked.
  
  i - The i 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 i, double[] workArray)
  
  Right multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i. This is done in place
  Specifically, computes \( A\left[:\right]\left[i-1:i+1\right]G^{H} \) where i=i, \( G \) is the \( 2\times2 \) Givens rotator, \( A \) is the matrix to apply the reflector to, and \( A\left[:i+1\right]\left[i-1:i+1\right] \) represents the slice of \( A \) the reflector effects which has shape i+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\times2 \) givens rotator. Note, the size is not explicitly checked.
  
  i - The i 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*(i+1) data.
- leftMult2x2Rotator
  
  public static void leftMult2x2Rotator(CMatrix src, CMatrix G, int i, Complex128[] workArray)
  
  Left multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i. This is done in place.
  Specifically, computes \( GA\left[i-1:i+1\right]\left[i-1:i+1\right] \) where i=i, \( G \) is the \( 2\times2 \) Givens rotator, \( A \) is the matrix to apply the reflector to, and \( A\left[i-1:i+1\right]\left[i-1:\right] \) 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\times2 \) givens rotator. Note, the size is not explicitly checked.
  
  i - The i 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 i, Complex128[] workArray)
  
  Right multiplies a \( 2\times2 \) Givens rotator to a matrix at the specified i. This is done in place
  Specifically, computes \( A\left[:\right]\left[i-1:i+1\right]G^{H} \) where i=i, \( G \) is the \( 2\times2 \) Givens rotator, \( A \) is the matrix to apply the reflector to, and \( A\left[:i+1\right]\left[i-1:i+1\right] \) represents the slice of \( A \) the reflector effects which has shape i+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\times2 \) givens rotator. Note, the size is not explicitly checked.
  
  i - The i 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*(i+1) data.
- get2x2Rotator
  
  public static CMatrix get2x2Rotator(CVector v)
  
  Constructs a Givens rotator \( G \) of size 2 such that for a vector \( v = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).
  
  Parameters:
  
  v - Vector \( \mathbf{v} \) to construct Givens rotator for.
  
  Returns:
  
  A Givens rotator \( G \) of size 2 such that for a vector \( v = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).
  
  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 \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).
  
  Parameters:
  
  v0 - First entry in vector \( \mathbf{v} \) to construct rotator for.
  
  v1 - Second entry in vector \( \mathbf{v} \) to construct rotator for.
  
  Returns:
  
  A Givens rotator \( G \) of size 2 such that for a vector \( \mathbf{v} = \begin{bmatrix}a & b\end{bmatrix} \) we have \( G\mathbf{v} = \begin{bmatrix}r & 0\end{bmatrix} \).

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