java.lang.Object
dev.nm.algebra.linear.matrix.doubles.matrixtype.GivensMatrix
All Implemented Interfaces:
Matrix, MatrixAccess, MatrixRing, MatrixTable, AbelianGroup<Matrix>, Monoid<Matrix>, Ring<Matrix>, Table, DeepCopyable

public class GivensMatrix extends Object implements Matrix
Givens rotation is a rotation in the plane spanned by two coordinates axes. That is, left multiplying a vector x by G(i, j, θ), i.e., G(i, j, θ)x, amounts to rotating x counter-clockwise by radians in the (i ,j) coordinate plane. Its main use is to zero out entries in matrices and vectors. Compared to Householder transformation, Givens rotation can zero out entries more selectively. For example, given a matrix A, we can construct a Givens matrix, G, such that GA has a 0 at an entry GA[i,j] of our choice. Givens matrices are orthogonal.

This implementation of a Givens matrix is immutable.

See Also:
  • Constructor Details

    • GivensMatrix

      public GivensMatrix(int dim, int i, int j, double c, double s)
      Constructs a Givens matrix in the form \[ G(i,j,c,s) = \begin{bmatrix} 1 invalid input: '&' ... invalid input: '&' 0 invalid input: '&' ... invalid input: '&' 0 invalid input: '&' ... invalid input: '&' 0\\ ... invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' \\ 0 invalid input: '&' ... invalid input: '&' c invalid input: '&' ... invalid input: '&' s invalid input: '&' ... invalid input: '&' 0\\ ... invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' \\ 0 invalid input: '&' ... invalid input: '&' -s invalid input: '&' ... invalid input: '&' c invalid input: '&' ... invalid input: '&' 0\\ ... invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' invalid input: '&' \\ 0 invalid input: '&' ... invalid input: '&' 0 invalid input: '&' ... invalid input: '&' 0 invalid input: '&' ... invalid input: '&' 1 \end{bmatrix} \] We have,
       G[i,i] = c (diagonal entry)
       G[j,j] = c (diagonal entry)
       G[i,j] = s
       G[j,i] = -s
       
      Parameters:
      dim - the dimension of G
      i - i
      j - j
      c - c
      s - s
    • GivensMatrix

      public GivensMatrix(GivensMatrix that)
      Copy constructor.
      Parameters:
      that - a Givens matrix
  • Method Details

    • CtorFromRho

      public static GivensMatrix CtorFromRho(int dim, int i, int j, double rho)
      Constructs a Givens matrix from ρ. This construction is discussed in the reference.
      Parameters:
      dim - the dimension of G
      i - i
      j - j
      rho - ρ
      Returns:
      a Givens matrix
    • Ctor2x2

      public static GivensMatrix Ctor2x2(double c, double s)
      Same as new GivensMatrix(2, 1, 2, c, s).
      Parameters:
      c - c
      s - s
      Returns:
      a 2x2 Givens matrix
    • CtorToRotateRows

      public static GivensMatrix CtorToRotateRows(int dim, int i1, int i2, double a, double b)
      Constructs a Givens matrix such that G * [a b]t = [* 0]t. This operation rotates rows i1 and i2 to make the entry in row i1 0. This implementation is a variant of the numerically stable version in the reference.
      Parameters:
      dim - the dimension of G
      i1 - i1 as in A[i1,i1] = c
      i2 - i2 as in A[i1,i2] = s
      a - a as in [a b]t
      b - b as in [a b]t
      Returns:
      G
    • CtorToZeroOutEntry

      public static GivensMatrix CtorToZeroOutEntry(Matrix A, int i, int j)
      Constructs a Givens matrix such that G * A has 0 in the [i,j] entry.
      Parameters:
      A - a matrix
      i - i as in A[i,j]
      j - j as in A[i,j]
      Returns:
      a Givens matrix
    • CtorToRotateColumns

      public static GivensMatrix CtorToRotateColumns(int dim, int j1, int j2, double a, double b)
      Constructs a Givens matrix such that [a b] * G = [* 0]. This operation rotates columns j1 and j2 to make the entry in column j2 0.
      Parameters:
      dim - the dimension of G
      j1 - j1 as in A[j1,j1] = c
      j2 - j2 as in A[j1,j2] = s
      a - a as in [a b]t
      b - b as in [a b]t
      Returns:
      a Givens matrix
    • CtorToZeroOutEntryByTranspose

      public static GivensMatrix CtorToZeroOutEntryByTranspose(Matrix A, int i, int j)
      Constructs a Givens matrix such that Gt * A has 0 in the [i,j] entry.
      Parameters:
      A - a matrix
      i - i as in A[i,j]
      j - j as in A[i,j]
      Returns:
      G
    • i

      public int i()
      Gets the value of i.
      Returns:
      the value of i
    • j

      public int j()
      Gets the value of j.
      Returns:
      the value of j
    • c

      public double c()
      Gets the value of c.
      Returns:
      the value of c
    • s

      public double s()
      Gets the value of s.
      Returns:
      the value of s
    • rho

      public double rho()
      Gets ρ as discussed in the reference.
      Returns:
      ρ
    • rotate

      @Deprecated public Vector rotate(Vector x)
      Deprecated.
      Not supported yet.
      Rotates x in the [i,j] coordinate plane.
      Parameters:
      x - a vector
      Returns:
      G(i, j, θ)x
    • get

      public double get(int i, int j)
      Description copied from interface: MatrixAccess
      Get the matrix entry at [i,j].
      Specified by:
      get in interface MatrixAccess
      Parameters:
      i - the row index
      j - the column index
      Returns:
      A[i,j]
    • getRow

      public Vector getRow(int i) throws MatrixAccessException
      Description copied from interface: Matrix
      Get the specified row in the matrix as a vector.
      Specified by:
      getRow in interface Matrix
      Parameters:
      i - the row index
      Returns:
      the vector A[i, ]
      Throws:
      MatrixAccessException - when i < 1, or when i > the number of rows
    • getColumn

      public Vector getColumn(int j) throws MatrixAccessException
      Description copied from interface: Matrix
      Get the specified column in the matrix as a vector.
      Specified by:
      getColumn in interface Matrix
      Parameters:
      j - the column index
      Returns:
      a vector A[, j]
      Throws:
      MatrixAccessException - when j < 1, or when j > the number of columns
    • t

      public GivensMatrix t()
      Description copied from interface: MatrixRing
      Get the transpose of this matrix. This is the involution on the matrix ring.
      Specified by:
      t in interface MatrixRing
      Returns:
      the transpose of this matrix
    • multiply

      public Matrix multiply(Matrix A)
      Left multiplication by G, namely, G * A. This operation affects only the i-th and the j-th rows. This implementation uses this fact for performance.
      Specified by:
      multiply in interface MatrixRing
      Specified by:
      multiply in interface Monoid<Matrix>
      Parameters:
      A - a left multiply matrix
      Returns:
      G * A
    • multiplyInPlace

      public Matrix multiplyInPlace(Matrix A)
      Left multiplication by G, namely, G * A. This operation changes the input matrix A for performance reason (skipping copying).
      Parameters:
      A - a left multiply matrix; it is changed after the operation
      Returns:
      G * A
    • multiply

      public Vector multiply(Vector v)
      Description copied from interface: Matrix
      Right multiply this matrix, A, by a vector.
      Specified by:
      multiply in interface Matrix
      Parameters:
      v - a vector
      Returns:
      Av, a vector
    • multiplyInPlace

      public Vector multiplyInPlace(Vector v)
      Right multiplies this matrix, A, by a vector. This operation changes the input vector v for performance reason (skipping copying).
      Parameters:
      v - a vector; it is changed after the operation
      Returns:
      Av, a vector
    • rightMultiply

      public Matrix rightMultiply(Matrix A)
      Right multiplication by G, namely, A * G. This operation affects only the i-th and the j-th columns. This implementation uses this fact for performance.
      Parameters:
      A - a right multiply matrix
      Returns:
      A * G
    • rightMultiplyInPlace

      public Matrix rightMultiplyInPlace(Matrix A)
      Right multiplication by G, namely, A * G. This operation changes the input matrix A for performance reason (skipping copying).
      Parameters:
      A - a left multiply matrix; it is changed after the operation
      Returns:
      A * G
    • product

      public static Matrix product(GivensMatrix[] Gs)
      Given an array of Givens matrices {Gi}, computes G, where
      G = G1 * G2 * ... * Gn
      Parameters:
      Gs - an array of Givens matrices
      Returns:
      G
    • product

      public static Matrix product(List<GivensMatrix> Gs)
    • ONE

      public GivensMatrix ONE()
      Description copied from interface: MatrixRing
      Get an identity matrix that has the same dimension as this matrix. For a non-square matrix, it zeros out the rows (columns) with index > nCols (nRows).
      Specified by:
      ONE in interface MatrixRing
      Specified by:
      ONE in interface Monoid<Matrix>
      Returns:
      an identity matrix
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • deepCopy

      public GivensMatrix deepCopy()
      Description copied from interface: DeepCopyable
      The implementation returns an instance created from this by the copy constructor of the class, or just this if the instance itself is immutable.
      Specified by:
      deepCopy in interface DeepCopyable
      Specified by:
      deepCopy in interface Matrix
      Returns:
      an independent (deep) copy of the instance
    • set

      @Deprecated public void set(int row, int col, double value)
      Deprecated.
      GivensMatrix is immutable
      Description copied from interface: MatrixAccess
      Set the matrix entry at [i,j] to a value. This is the only method that may change a matrix.
      Specified by:
      set in interface MatrixAccess
      Parameters:
      row - the row index
      col - the column index
      value - the value to set A[i,j] to
    • ZERO

      @Deprecated public Matrix ZERO()
      Deprecated.
      no zero matrix for GivensMatrix
      Description copied from interface: MatrixRing
      Get a zero matrix that has the same dimension as this matrix.
      Specified by:
      ZERO in interface AbelianGroup<Matrix>
      Specified by:
      ZERO in interface MatrixRing
      Returns:
      the 0 matrix
    • nRows

      public int nRows()
      Description copied from interface: Table
      Gets the number of rows. Rows count from 1.
      Specified by:
      nRows in interface Table
      Returns:
      the number of rows
    • nCols

      public int nCols()
      Description copied from interface: Table
      Gets the number of columns. Columns count from 1.
      Specified by:
      nCols in interface Table
      Returns:
      the number of columns
    • add

      public Matrix add(Matrix that)
      Description copied from interface: MatrixRing
      this + that
      Specified by:
      add in interface AbelianGroup<Matrix>
      Specified by:
      add in interface MatrixRing
      Parameters:
      that - a matrix
      Returns:
      the sum of this and that
    • minus

      public Matrix minus(Matrix that)
      Description copied from interface: MatrixRing
      this - that
      Specified by:
      minus in interface AbelianGroup<Matrix>
      Specified by:
      minus in interface MatrixRing
      Parameters:
      that - a matrix
      Returns:
      the difference between this and that
    • scaled

      public Matrix scaled(double c)
      Description copied from interface: Matrix
      Scale this matrix, A, by a constant.
      Specified by:
      scaled in interface Matrix
      Parameters:
      c - a double
      Returns:
      cA
    • opposite

      public Matrix opposite()
      Description copied from interface: MatrixRing
      Get the opposite of this matrix.
      Specified by:
      opposite in interface AbelianGroup<Matrix>
      Specified by:
      opposite in interface MatrixRing
      Returns:
      -this
      See Also:
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object