# Class GivensMatrix

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.

• ## Constructor Summary

Constructors
Constructor
Description
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: '&' ... GivensMatrix(GivensMatrix that) Copy constructor. • ## Method Summary Modifier and Type Method Description Matrix add(Matrix that) this + that double c() Gets the value of c. static GivensMatrix Ctor2x2(double c, double s) Same as new GivensMatrix(2, 1, 2, c, s). static GivensMatrix CtorFromRho(int dim, int i, int j, double rho) Constructs a Givens matrix from ρ. static GivensMatrix CtorToRotateColumns(int dim, int j1, int j2, double a, double b) Constructs a Givens matrix such that [a b] * G = [* 0]. 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. static GivensMatrix CtorToZeroOutEntry(Matrix A, int i, int j) Constructs a Givens matrix such that G * A has 0 in the [i,j] entry. static GivensMatrix CtorToZeroOutEntryByTranspose(Matrix A, int i, int j) Constructs a Givens matrix such that Gt * A has 0 in the [i,j] entry. GivensMatrix deepCopy() The implementation returns an instance created from this by the copy constructor of the class, or just this if the instance itself is immutable. boolean equals(Object obj) double get(int i, int j) Get the matrix entry at [i,j]. Vector getColumn(int j) Get the specified column in the matrix as a vector. Vector getRow(int i) Get the specified row in the matrix as a vector. int hashCode() int i() Gets the value of i. int j() Gets the value of j. Matrix minus(Matrix that) this - that Matrix multiply(Matrix A) Left multiplication by G, namely, G * A. Vector multiply(Vector v) Right multiply this matrix, A, by a vector. Matrix multiplyInPlace(Matrix A) Left multiplication by G, namely, G * A. Vector multiplyInPlace(Vector v) Right multiplies this matrix, A, by a vector. int nCols() Gets the number of columns. int nRows() Gets the number of rows. GivensMatrix ONE() Get an identity matrix that has the same dimension as this matrix. Matrix opposite() Get the opposite of this matrix. static Matrix product(GivensMatrix[] Gs) Given an array of Givens matrices {Gi}, computes G, where G = G1 * G2 * ... static Matrix product(List<GivensMatrix> Gs) double rho() Gets ρ as discussed in the reference. Matrix rightMultiply(Matrix A) Right multiplication by G, namely, A * G. Matrix rightMultiplyInPlace(Matrix A) Right multiplication by G, namely, A * G. Vector rotate(Vector x) Deprecated. Not supported yet. double s() Gets the value of s. Matrix scaled(double c) Scale this matrix, A, by a constant. void set(int row, int col, double value) Deprecated. GivensMatrix is immutable GivensMatrix t() Get the transpose of this matrix. String toString() Matrix ZERO() Deprecated. no zero matrix for GivensMatrix ### Methods inherited from class java.lang.Object clone, finalize, getClass, notify, notifyAll, wait, wait, wait ### Methods inherited from interface dev.nm.algebra.linear.matrix.doubles.Matrix toCSV • ## 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

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

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

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

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
hashCode in class Object
equals in class Object