Class 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:
    Wikipedia: Givens rotation
    • Constructor Detail

      • 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 & ... & 0 & ... & 0 & ... & 0\\ ... & & & & & & \\ 0 & ... & c & ... & s & ... & 0\\ ... & & & & & & \\ 0 & ... & -s & ... & c & ... & 0\\ ... & & & & & & \\ 0 & ... & 0 & ... & 0 & ... & 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 Detail

      • 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
      • 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
      • 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
      • 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
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object