com.numericalmethod.suanshu.matrix.doubles.matrixtype
Class GivensMatrix

java.lang.Object
  com.numericalmethod.suanshu.matrix.doubles.matrixtype.MatrixMathImpl<GivensMatrix>
      com.numericalmethod.suanshu.matrix.doubles.matrixtype.GivensMatrix

All Implemented Interfaces:

DeepCopyable, AbelianGroup<Matrix>, Monoid<Matrix>, Ring<Matrix>, Matrix, MatrixAccessor, MatrixRing, MatrixDimension

public class GivensMatrix
extends MatrixMathImpl<GivensMatrix>

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 instance, 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.

Givens matrices are immutable.

See Also:

Wikipedia: Givens rotation

Constructor Summary

GivensMatrix(GivensMatrix that)
Copy constructor performing a deep copy.

GivensMatrix(int dim, int i, int j, double c, double s)
Construct a Givens matrix of the form | 1 ... 0 ... 0 ... 0 | |

Method Summary

static GivensMatrix	Ctor2x2(double c, double s) Construct GivensMatrix(2, 1, 2, c, s)
static GivensMatrix	CtorFromRho(int dim, int i, int j, double rho) Construct a Givens matrix from ρ.
static GivensMatrix	CtorToRotateColumns(int dim, int col1, int col2, double a, double b) Construct a Givens matrix such that [a b] %*% G = [* 0].
static GivensMatrix	CtorToRotateRows(int dim, int row1, int row2, double a, double b) Construct a Givens matrix such that G %*% [a b]transpose = [* 0]transpose.
static GivensMatrix	CtorToZeroOutEntry(Matrix A, int i, int j) Construct a Givens matrix such that G %*% A has 0 in the A[i, j] entry.
static GivensMatrix	CtorToZeroOutEntryByTranspose(Matrix A, int i, int j) Construct a Givens matrix such that Gtranspose %*% A has 0 in the A[i, j] entry.
GivensMatrix	deepCopy() The implementation can return an instance created from this by the copy constructor of the class, or just this if the instance itself is immutable.
double	get(int row, int col) Get the matrix entry at [row, col].
Vector	getColumn(int col) Get a specified column as a vector.
Vector	getRow(int row) Get a specified row as a vector.
Matrix	multiply(Matrix A) Left multiplication by G, namely, G %*% A affects only the i-th and the j-th rows.
Vector	multiply(Vector v) Right multiply this matrix, A by a vector.
GivensMatrix	ONE() Get an identity matrix that has the same dimension as this matrix.
static Matrix	product(GivensMatrix[] Gs) Given Givens matrices {Gi}, compute G, where G = G1 %*% ... %*% G2 %*% Gn
double	rho() Get ρ as in Section 5.1.11 in Matrix Computations, 3rd edition, by Golub G.
Matrix	rightMultiply(Matrix A) Right multiplication by G, namely, A %*% G affects only the i-th and the j-th columns.
Vector	rotate(Vector x) Deprecated. Not supported yet.
void	set(int row, int col, double value) Deprecated. GivensMatrix is immutable
GivensMatrix	t() t(this) Compute the transpose of this matrix.
java.lang.String	toString()
Matrix	ZERO() Deprecated. no zero matrix for GivensMatrix

Methods inherited from class com.numericalmethod.suanshu.matrix.doubles.matrixtype.MatrixMathImpl

add, call, getSample, minus, nCols, nRows, opposite, scaled, setColumn, setColumn, setRow, setRow

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

GivensMatrix

public GivensMatrix(int dim,
                    int i,
                    int j,
                    double c,
                    double s)

Construct a Givens matrix of the form

                 | 1 ... 0 ... 0 ... 0 |
                 | ...                 |
                 | 0 ... c ... s ... 0 |
 G(i, j, c, s) = | ...                 |
                 | 0 ...-s ... c ... 0 |
                 | ...                 |
                 | 0 ... 0 ... 0 ... 1 |
 

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 performing a deep copy.

Parameters:

that - another GivensMatrix

Method Detail

CtorFromRho

public static GivensMatrix CtorFromRho(int dim,
                                       int i,
                                       int j,
                                       double rho)

Construct a Givens matrix from ρ.

This implements the discussion in

 Section 5.1.11 in
 Matrix Computations, 3rd edition, by
 Golub G. H., van Loan C. F.
 

Parameters:

dim -

i - i

j - j

rho - ρ

Returns:

a Givens matrix

Ctor2x2

public static GivensMatrix Ctor2x2(double c,
                                   double s)

Construct

GivensMatrix(2, 1, 2, c, s)

Parameters:

c - c

s - s

Returns:

a 2x2 Givens matrix

CtorToRotateRows

public static GivensMatrix CtorToRotateRows(int dim,
                                            int row1,
                                            int row2,
                                            double a,
                                            double b)

Construct a Givens matrix such that G %*% [a b]transpose = [* 0]transpose. This operation rotates rows row1 and row2 to make the entry in row row2 0.

This implements a variant of the numerically stable version in

 Algorithm 1.6 in
 Matrix Algorithms Vol. 1 by
 G. W. Stewart
 

Parameters:

dim - the dimension of G

row1 - i as in A[i, i] = c

row2 - j as in A[i, j] = s

a - y as in [a b]transpose

b - z as in [a b]transpose

Returns:

G

CtorToZeroOutEntry

public static GivensMatrix CtorToZeroOutEntry(Matrix A,
                                              int i,
                                              int j)

Construct a Givens matrix such that G %*% A has 0 in the A[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 col1,
                                               int col2,
                                               double a,
                                               double b)

Construct a Givens matrix such that [a b] %*% G = [* 0]. This operation rotates columns col1 and col2 to make the entry in column col2 0.

Parameters:

dim - the dimension of G

col1 - i as in A[i, i] = c

col2 - j as in A[i, j] = s

a - y as in [a b]transpose

b - z as in [a b]transpose

Returns:

a Givens matrix

CtorToZeroOutEntryByTranspose

public static GivensMatrix CtorToZeroOutEntryByTranspose(Matrix A,
                                                         int i,
                                                         int j)

Construct a Givens matrix such that Gtranspose %*% A has 0 in the A[i, j] entry.

Parameters:

A - a matrix

i - i as in A[i, j]

j - j as in A[i, j]

Returns:

G

rho

public double rho()

Get ρ as in

 Section 5.1.11 in
 Matrix Computations, 3rd edition, by
 Golub G. H., van Loan C. F.
 

Returns:

ρ

rotate

@Deprecated
public Vector rotate(Vector x)

Deprecated. Not supported yet.

Rotate x in the (i ,j) coordinate plane.

Parameters:

x - a vector

Returns:

G(i, j, θ)x

get

public double get(int row,
                  int col)

Description copied from interface: MatrixAccessor

Get the matrix entry at [row, col].

Parameters:

row - the row index

col - the column index

Returns:

A[row, col]

getRow

public Vector getRow(int row)
              throws MatrixAccessException

Description copied from interface: MatrixAccessor

Get a specified row as a vector.

Specified by:

getRow in interface MatrixAccessor

Overrides:

getRow in class MatrixMathImpl<GivensMatrix>

Parameters:

row - the row index

Returns:

a vector A[row, ]

Throws:

MatrixAccessException - when row < 1, or when row > number of rows

getColumn

public Vector getColumn(int col)
                 throws MatrixAccessException

Description copied from interface: MatrixAccessor

Get a specified column as a vector.

Specified by:

getColumn in interface MatrixAccessor

Overrides:

getColumn in class MatrixMathImpl<GivensMatrix>

Parameters:

col - the column index

Returns:

a vector A[, col]

Throws:

MatrixAccessException - when col < 1, or when col > number of columns

t

public GivensMatrix t()

Description copied from interface: MatrixRing

t(this)

Compute the transpose of this matrix. The original matrix does not change. The returned value is independent and can be modified anyhow.

This is the involution on the matrix ring.

Specified by:

t in interface MatrixRing

Overrides:

t in class MatrixMathImpl<GivensMatrix>

Returns:

the transpose of this matrix, of the same type

multiply

public Matrix multiply(Matrix A)

Left multiplication by G, namely, G %*% A affects only the i-th and the j-th rows.

That is,

 [i-th row, j-th row]transpose = G %*% [i-th row, j-th row]transpose
 

Specified by:

multiply in interface Monoid<Matrix>

Specified by:

multiply in interface MatrixRing

Overrides:

multiply in class MatrixMathImpl<GivensMatrix>

Parameters:

A - left multiply matrix

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

Overrides:

multiply in class MatrixMathImpl<GivensMatrix>

Parameters:

v - a vector

Returns:

A %*% v

rightMultiply

public Matrix rightMultiply(Matrix A)

Right multiplication by G, namely, A %*% G affects only the i-th and the j-th columns.

That is,

 [i-th column, j-th column] = [i-th column, j-th column] %*% G
 

Parameters:

A - left multiply matrix

Returns:

A %*% G

product

public static Matrix product(GivensMatrix[] Gs)

Given Givens matrices {Gi}, compute 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).

Returns:

an identity matrix

toString

public java.lang.String toString()

Overrides:

toString in class MatrixMathImpl<GivensMatrix>

deepCopy

public GivensMatrix deepCopy()

Description copied from interface: Matrix

The implementation can return an instance created from this by the copy constructor of the class, or just this if the instance itself is immutable.

Override the return type.

Returns:

an independent copy of Matrix instance

set

@Deprecated
public void set(int row,
                           int col,
                           double value)

Deprecated. GivensMatrix is immutable

Description copied from interface: MatrixAccessor

Set the matrix entry at [row, col] to value.

This is the only method that may change the entries of a matrix.

Parameters:

row - the row index

col - the column index

value - the value to set A[row, col] to

ZERO

@Deprecated
public Matrix ZERO()

Deprecated. no zero matrix for GivensMatrix

Description copied from interface: AbelianGroup

The additive element 0 in the group, such that for all elements a in the group, the equation

0 + a = a + 0 = a

holds.

Returns:

0