SuanShu, a Java numerical and statistical library

com.numericalmethod.suanshu.algebra.linear.matrix.doubles.matrixtype

Class GivensMatrix

• java.lang.Object
• com.numericalmethod.suanshu.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.

Wikipedia: Givens rotation
• Constructor Summary

Constructors
Constructor and Description
GivensMatrix(GivensMatrix that)
Copy constructor.
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 & ... • Method Summary All Methods Modifier and Type Method and 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 • 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
"G. H. Golub, C. F. van Loan, "Section 5.1.11," Matrix Computations, 3rd edition."
• 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
"G. W. Stewart, "Algorithm 1.6," Matrix Algorithms Vol. 1"
• 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:
ρ
"G. H. Golub, C. F. van Loan, "Section 5.1.11," Matrix Computations, 3rd edition."
• 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 Matrix
Specified by:
deepCopy in interface DeepCopyable
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 MatrixRing
Specified by:
ZERO in interface AbelianGroup<Matrix>
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

public Matrix add(Matrix that)
Description copied from interface: MatrixRing
this + that
Specified by:
add in interface MatrixRing
Specified by:
add in interface AbelianGroup<Matrix>
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 MatrixRing
Specified by:
minus in interface AbelianGroup<Matrix>
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 MatrixRing
Specified by:
opposite in interface AbelianGroup<Matrix>
Returns:
-this
public int hashCode()
hashCode in class Object
public boolean equals(Object obj)
equals in class Object