Package org.flag4j.arrays.sparse

Class PermutationMatrix

java.lang.Object

org.flag4j.arrays.sparse.PermutationMatrix

All Implemented Interfaces:

Serializable

public class PermutationMatrix
extends Object
implements Serializable

A permutation matrix is a square matrix containing only zeros and ones such that each row and column have exactly a single one. The identity matrix is a special case of a permutation matrix. Permutation matrices are commonly used to track or apply row/column swaps in a matrix.

All permutation matrices are orthogonal/unitary meaning their inverse is equal to their transpose.

When a permutation matrix is left multiplied to a second matrix, it has the result of swapping rows in the second matrix.

Similarly, when a permutation matrix is right multiplied to another matrix, it has the result of swapping columns in the other matrix.

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
final int	size	Size of this permutation matrix.
final int[]	swapPointers	Tracks row/column swaps within the permutation matrix.

Constructor Summary

Constructors

Constructor	Description
PermutationMatrix(int size)	Creates a permutation matrix which is equivalent to the identity matrix of the specified size.
PermutationMatrix(int[] swapPointers)	Creates a permutation matrix where the position of its ones are specified by a swap pointer array.
PermutationMatrix(PermutationMatrix src)	Copy constructor which creates a copy of the src permutation matrix.
PermutationMatrix(Shape shape)	Creates a permutation matrix which is equivalent to the identity matrix of the specified size.

Method Summary

Modifier and Type	Method	Description
int	computeSwaps()	Computes the number of row/column swaps required for this permutation matrix to be converted to the identity matrix.
PermutationMatrix	copy()	Creates a copy of this permutation matrix.
int	det()	Computes the determinant of this permutation matrix (will be +/- 1).
boolean	equals(Object object)	Checks if this permutation matrix is equal to the given object.
static PermutationMatrix	fromColSwaps(int[] colSwaps)	Creates a permutation matrix with the specified column swaps.
int	hashCode()	Returns a hashcode for this permutation matrix by calling Arrays.hashCode(swapPointers).
PermutationMatrix	inv()	Computes the inverse/transpose of this permutation matrix.
CMatrix	leftMult(CMatrix src)	Left multiplies this permutation matrix to the specified matrix.
CVector	leftMult(CVector src)	Left multiplies this permutation matrix to the specified vector.
Matrix	leftMult(Matrix src)	Left multiplies this permutation matrix to the specified matrix.
Vector	leftMult(Vector src)	Left multiplies this permutation matrix to the specified vector.
void	permuteRows(int[] swaps)	Permutes rows of this permutation matrix.
CMatrix	rightMult(CMatrix src)	Right multiplies this permutation matrix to the specified matrix.
CVector	rightMult(CVector src)	Right multiplies this permutation matrix to the specified vector.
Matrix	rightMult(Matrix src)	Right multiplies this permutation matrix to the specified matrix.
Vector	rightMult(Vector src)	Right multiplies this permutation matrix to the specified vector.
void	swapCols(int col1, int col2)	Swaps two columns in this permutation matrix.
void	swapRows(int row1, int row2)	Swaps two rows in this permutation matrix.
PermutationMatrix	T()	Computes the transpose/inverse of this permutation matrix.
Matrix	toDense()	Converts this permutation matrix to a real dense matrix.
String	toString()	Converts this permutation matrix to a human-readable string.
int	tr()	Computes the trace of this permutation matrix.
int	trace()	Computes the trace of this permutation matrix.

Methods inherited from class java.lang.Object

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

Field Details

swapPointers

public final int[] swapPointers

Tracks row/column swaps within the permutation matrix. For an n-by-n permutation matrix, this array will have size n. Each entry of the array represents a 1 in the permutation matrix. The index of an entry corresponds to the row index of the 1, and the value of this array corresponds to the column index of the 1.

size

public final int size

Size of this permutation matrix.

Constructor Details

PermutationMatrix

public PermutationMatrix(int size)

Creates a permutation matrix which is equivalent to the identity matrix of the specified size.

Parameters:

size - Size of the permutation matrix. That is, the number of rows and columns

PermutationMatrix

public PermutationMatrix(Shape shape)

Creates a permutation matrix which is equivalent to the identity matrix of the specified size.

Parameters:

shape - Shape of the permutation matrix. That is, the number of rows and columns. Must be a square shape.

Throws:

LinearAlgebraException - If shape is not square.

PermutationMatrix

public PermutationMatrix(PermutationMatrix src)

Copy constructor which creates a copy of the src permutation matrix.

Parameters:

src - The permutation matrix to copy.

PermutationMatrix

public PermutationMatrix(int[] swapPointers)

Creates a permutation matrix where the position of its ones are specified by a swap pointer array.

Parameters:

swapPointers - An array which defines row/column swaps within the permutation matrix. For an n-by-n permutation matrix, this array will have size n. Each entry of the array represents a 1 in the permutation matrix. The index of an entry corresponds to the row index of the 1, and the value of this array corresponds to the column index of the 1. This must be a permutation matrix. However, the validity of this is not enforced by this constructor.

Method Details

fromColSwaps

public static PermutationMatrix fromColSwaps(int[] colSwaps)

Creates a permutation matrix with the specified column swaps.

Parameters:

colSwaps - Array specifying column swaps. The entry x at index i indicates that column i has been swapped with column x. Must be a permutation array.

Returns:

A permutation matrix with the specified column swaps.

Throws:

IllegalArgumentException - If colSwaps is not a permutation array.

copy

public PermutationMatrix copy()

Creates a copy of this permutation matrix.

Returns:

A copy of this permutation matrix.

equals

public boolean equals(Object object)

Checks if this permutation matrix is equal to the given object. A permutation matrix is considered equal to an object if that object is also a permutation matrix and represents the same matrix.

Overrides:

equals in class Object

Parameters:

object - Object to compare to this permutation matrix.

Returns:

True if b is a permutation matrix and equivalent to this matrix (in terms of matrix equality).

hashCode

public int hashCode()

Returns a hashcode for this permutation matrix by calling Arrays.hashCode(swapPointers).

Overrides:

hashCode in class Object

Returns:

The hashcode for this permutation matrix.

leftMult

public Matrix leftMult(Matrix src)

Left multiplies this permutation matrix to the specified matrix. This will have the effect of swapping rows in the src matrix.

Parameters:

src - The matrix to left multiply this permutation matrix to.

Returns:

The result of left multiplying this permutation matrix to the src matrix.

Throws:

IllegalArgumentException - If the number of rows in src does not equal the size of this permutation matrix.

See Also:

• rightMult(Matrix)

leftMult

public Vector leftMult(Vector src)

Left multiplies this permutation matrix to the specified vector. This will have the effect of swapping rows in the src vector. The vector will be treated as a column vector.

Parameters:

src - The vector to left multiply this permutation matrix to.

Returns:

The result of left multiplying this permutation matrix to the src vector.

Throws:

IllegalArgumentException - If size of src does not equal the size of this permutation matrix.

See Also:

• rightMult(Vector)

leftMult

public CMatrix leftMult(CMatrix src)

Left multiplies this permutation matrix to the specified matrix. This will have the effect of swapping rows in the src matrix.

Parameters:

src - The matrix to left multiply this permutation matrix to.

Returns:

The result of left multiplying this permutation matrix to the src matrix.

Throws:

IllegalArgumentException - If the number of rows in src does not equal the size of this permutation matrix.

See Also:

• rightMult(CMatrix)

leftMult

public CVector leftMult(CVector src)

Left multiplies this permutation matrix to the specified vector. This will have the effect of swapping rows in the src vector. The vector will be treated as a column vector.

Parameters:

src - The vector to left multiply this permutation matrix to.

Returns:

The result of left multiplying this permutation matrix to the src vector.

Throws:

IllegalArgumentException - If size of src does not equal the size of this permutation matrix.

See Also:

• rightMult(CVector)

rightMult

public Matrix rightMult(Matrix src)

Right multiplies this permutation matrix to the specified matrix. This is equivalent to swapping columns in the src matrix.

Parameters:

src - The matrix to right multiply this permutation matrix to.

Returns:

The result of right multiplying this permutation matrix to the src matrix.

Throws:

IllegalArgumentException - If the number of columns in src does not match the size of this permutation matrix.

See Also:

• leftMult(Matrix)

rightMult

public Vector rightMult(Vector src)

Right multiplies this permutation matrix to the specified vector. This will have the effect of swapping columns in the src vector. The vector will be treated as a row vector.

Parameters:

src - The vector to right multiply this permutation matrix to.

Returns:

The result of right multiplying this permutation matrix to the src vector.

Throws:

IllegalArgumentException - If size of src does not equal the size of this permutation matrix.

See Also:

• leftMult(Vector)

rightMult

public CMatrix rightMult(CMatrix src)

Right multiplies this permutation matrix to the specified matrix. This is equivalent to swapping columns in the src matrix.

Parameters:

src - The matrix to right multiply this permutation matrix to.

Returns:

The result of right multiplying this permutation matrix to the src matrix.

Throws:

IllegalArgumentException - If the number of columns in src does not match the size of this permutation matrix.

See Also:

• leftMult(Matrix)

rightMult

public CVector rightMult(CVector src)

Right multiplies this permutation matrix to the specified vector. This will have the effect of swapping columns in the src vector. The vector will be treated as a row vector.

Parameters:

src - The vector to right multiply this permutation matrix to.

Returns:

The result of right multiplying this permutation matrix to the src vector.

Throws:

IllegalArgumentException - If size of src does not equal the size of this permutation matrix.

See Also:

• leftMult(Vector)

swapRows

public void swapRows(int row1,
 int row2)

Swaps two rows in this permutation matrix.

Parameters:

row1 - First row to swap in the permutation matrix.

row2 - Second row to swap in the permutation matrix.

Throws:

ArrayIndexOutOfBoundsException - If either row1 or row2 is out of bounds of this permutation matrix.

swapCols

public void swapCols(int col1,
 int col2)

Swaps two columns in this permutation matrix.

Parameters:

col1 - First column to swap in the permutation matrix.

col2 - Second column to swap in the permutation matrix.

Throws:

ArrayIndexOutOfBoundsException - If either col1 or col2 is out of bounds of this permutation matrix.

permuteRows

public void permuteRows(int[] swaps)

Permutes rows of this permutation matrix.

Parameters:

swaps - Defines row swaps of this permutation matrix. The entry x at index i represents row i has been swapped with row x. This must be a permutation array.

Throws:

IllegalArgumentException - If swaps is not the same length as the number of rows/columns in this permutation matrix. Or, if swaps is not a permutation array.

inv

public PermutationMatrix inv()

Computes the inverse/transpose of this permutation matrix.

Returns:

The inverse/transpose of this permutation matrix.

T

public PermutationMatrix T()

Computes the transpose/inverse of this permutation matrix.

Returns:

The transpose/inverse of this permutation matrix.

trace

public int trace()

Computes the trace of this permutation matrix.

Returns:

The trace of this permutation matrix.

tr

public int tr()

Computes the trace of this permutation matrix. Alias for trace().

Returns:

The trace of this permutation matrix.

computeSwaps

public int computeSwaps()

Computes the number of row/column swaps required for this permutation matrix to be converted to the identity matrix.

Returns:

The total number of row/column swaps required to convert this permutation matrix to the identity matrix.

det

public int det()

Computes the determinant of this permutation matrix (will be +/- 1).

Returns:

The determinant of this permutation matrix (will be +/- 1).

toDense

public Matrix toDense()

Converts this permutation matrix to a real dense matrix.

Returns:

A real dense matrix which is equivalent to this permutation matrix.

toString

public String toString()

Converts this permutation matrix to a human-readable string.

Overrides:

toString in class Object

Returns:

This permutation matrix represented as a human-readable string.