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

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

All Implemented Interfaces:

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

public class PermutationMatrix
extends MatrixMathImpl<PermutationMatrix>

A permutation matrix is a square matrix that has exactly one entry 1 in each row and each column and 0's elsewhere.

This implementation uses a row view. We only store the column position of the 1 in each row. For examples,

 | 1 0 0 |
 | 0 1 0 |  is
 | 0 0 1 |

 [1, 2, 3];

 | 0 0 1 |
 | 0 1 0 |  is
 | 1 0 0 |

 [3, 2, 1]
 

Suppose P is a permutation matrix, A any matrix, then

1. P %*% A swaps the rows of A;
2. A %*% P swaps the columns of A;

There is no set function in this class. The matrix entries can only be modified by the various swap functions. This is to ensure that the matrix represents a consistent permutation.

See Also:

Wikipedia: Permutation matrix

Constructor Summary

PermutationMatrix(int dim)
Construct an identity permutation matrix.

PermutationMatrix(int[] data)
Construct a permutation matrix from a 1D double[] array.

PermutationMatrix(PermutationMatrix P)
Copy constructor.

Method Summary

Matrix	add(Matrix that) this + that
PermutationMatrix	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.
boolean	equals(java.lang.Object obj) Compares this matrix to another matrix.
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.
int	hashCode()
Matrix	minus(Matrix that) this - that
void	moveColumn2End(int col) This swaps a column of a permutation matrix with the last column.
void	moveRow2End(int row) This swaps a row of a permutation matrix with the last row.
Matrix	multiply(Matrix A) Left multiplication by P.
Vector	multiply(Vector v) Left multiplication by P.
PermutationMatrix	ONE() Get an identity matrix that has the same dimension as this matrix.
Matrix	rightMultiply(Matrix A) Right multiplication by P.
Matrix	scaled(double scalar) scalar * this
void	set(int row, int col, double value) Deprecated. use the swap functions instead
double	sign() Get the sign of this Permutation matrix which is essentially the determinant.
void	swapColumn(int col1, int col2) This swaps two columns of a permutation matrix.
void	swapRow(int row1, int row2) This swaps two rows of a permutation matrix.
PermutationMatrix	t() The transpose of a permutation matric is the same as its inverse.
Matrix	ZERO() The additive element 0 in the group, such that for all elements a in the group, the equation 0 + a = a + 0 = a holds.

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

call, getSample, nCols, nRows, opposite, setColumn, setColumn, setRow, setRow, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PermutationMatrix

public PermutationMatrix(int dim)

Construct an identity permutation matrix.

Parameters:

dim - dimension of the permutation matrix

PermutationMatrix

public PermutationMatrix(int[] data)

Construct a permutation matrix from a 1D double[] array.

Parameters:

data - the 1D double[] array indicating the column position of the 1 on each row

Throws:

java.lang.IllegalArgumentException - if data is not a permutation matrix

PermutationMatrix

public PermutationMatrix(PermutationMatrix P)

Copy constructor.

Parameters:

P - a permutation matrix to be copied

Method Detail

deepCopy

public PermutationMatrix 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

sign

public double sign()

Get the sign of this Permutation matrix which is essentially the determinant. It is +1 for an even (or 0) number of swaps, and -ve for an odd number of swaps.

Returns:

sign of this Permutation matrix

swapRow

public void swapRow(int row1,
                    int row2)

This swaps two rows of a permutation matrix. It does so by swapping the values of the two indices.

Parameters:

row1 - row 1/index 1

row2 - row 2/index 2

swapColumn

public void swapColumn(int col1,
                       int col2)

This swaps two columns of a permutation matrix. It does so by swapping the values of the inputs.

Parameters:

col1 - column 1/index 1

col2 - column 2/index 2

moveRow2End

public void moveRow2End(int row)

This swaps a row of a permutation matrix with the last row.

Parameters:

row - the row to be swapped with the last row

moveColumn2End

public void moveColumn2End(int col)

This swaps a column of a permutation matrix with the last column.

Parameters:

col - the column to be swapped with the last column

get

public double get(int row,
                  int col)
           throws MatrixAccessException

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]

Throws:

MatrixAccessException - if row or col is out of range

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<PermutationMatrix>

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<PermutationMatrix>

Parameters:

col - the column index

Returns:

a vector A[, col]

Throws:

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

rightMultiply

public Matrix rightMultiply(Matrix A)

Right multiplication by P. A %*% P is the same as swapping columns in A according to P.

Parameters:

A - a matrix to be right multiplied

Returns:

A %*% P

multiply

public Vector multiply(Vector v)

Left multiplication by P. P %*% vector is the same as swapping the vector entries/rows according to P.

Specified by:

multiply in interface Matrix

Overrides:

multiply in class MatrixMathImpl<PermutationMatrix>

Parameters:

v - column vector whose rows are to be swapped

Returns:

the vector with rows swapped

multiply

public Matrix multiply(Matrix A)

Left multiplication by P. P %*% A is the same as swapping rows in A according to P.

Specified by:

multiply in interface Monoid<Matrix>

Specified by:

multiply in interface MatrixRing

Overrides:

multiply in class MatrixMathImpl<PermutationMatrix>

Parameters:

A - a matrix to be left multiplied

Returns:

P %*% A

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

Overrides:

add in class MatrixMathImpl<PermutationMatrix>

Parameters:

that - another 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

Overrides:

minus in class MatrixMathImpl<PermutationMatrix>

Parameters:

that - another matrix

Returns:

the difference between this and that

scaled

public Matrix scaled(double scalar)

Description copied from interface: Matrix

scalar * this

Specified by:

scaled in interface Matrix

Overrides:

scaled in class MatrixMathImpl<PermutationMatrix>

Parameters:

scalar - a double

Returns:

scalar * this

t

public PermutationMatrix t()

The transpose of a permutation matric is the same as its inverse. That is,

P.multiply(P.t()) == P.t().multiply(P) == P.toDense().ONE()

Specified by:

t in interface MatrixRing

Overrides:

t in class MatrixMathImpl<PermutationMatrix>

Returns:

a copy of itself

ONE

public PermutationMatrix 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

ZERO

public Matrix ZERO()

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

equals

public boolean equals(java.lang.Object obj)

Compares this matrix to another matrix. Check whether all elements are equals.

This implementation is optimized if both matrices are subclass of PermutationMatrix.

Overrides:

equals in class java.lang.Object

Parameters:

obj - a matrix (of any implementation)

Returns:

true iff all entries are equals, entry by entry

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

set

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

Deprecated. use the swap functions instead

Don't use this function to change entries in a Permutation matrix. Use the swap functions instead.

swapRow(int, int), swapColumn(int, int), moveRow2End(int), moveColumn2End(int),

Parameters:

row - the row index

col - the column index

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

Throws:

java.lang.UnsupportedOperationException - when called

MatrixAccessException - if row or col is out of range