feat: Enhance Matrix class with row/column getters and permutation matrix checks

[mitsuki31]

Overview

This pull request introduces several enhancements to the Matrix class, including new methods for row and column retrieval, as well as functionality for checking permutation matrices.

Changes Made

Introduce Row and Column Retrieval Methods

getRow(int) and getColumn(int) Methods

These instance methods allow retrieval of a specific row or column from the matrix based on the provided index. Negative indices are supported to access rows or columns from the end of the matrix.

public double[] getRow(int index);

public double[] getColumn(int index);

Static Variants

Static methods getRow(int, Matrix) and getColumn(int, Matrix) have been added to retrieve rows and columns from a given Matrix instance.

public static double[] getRow(int index, Matrix m);

public static double[] getColumn(int index, Matrix m);

Alias for Consistency

The getCol(int) and getCol(Matrix, int) method has been introduced as an alias for getColumn(int) and getColumn(Matrix, int) respectively to maintain a consistent naming convention across the matrix operations.

public double[] getCol(int index);

public double[] getCol(Matrix m, int index);

Add Permutation Matrix Checks

isPermutationMatrix()

public boolean isPermutationMatrix();

This instance method checks if the current matrix is a permutation matrix. A permutation matrix is defined as a square matrix where each row and column contains exactly one 1 and all other entries are 0. It uses the isSquare() method to verify the matrix's square property and then validates each row and column to confirm the canonical basis array condition.

Static isPermutationMatrix(Matrix m)

public static boolean isPermutationMatrix(Matrix m);

This static method checks if a provided Matrix instance is a permutation matrix, performing similar checks as the instance method.

Static isPermutationMatrix(double[][] arr)

public static boolean isPermutationMatrix(double[][] arr);

A static convenience method to determine if a two-dimensional array represents a permutation matrix. It creates a Matrix instance from the given array and uses the isPermutationMatrix(Matrix m) method for the check.

Documentation

• Detailed JavaDoc comments have been added for all new methods, including descriptions, usage examples, and potential exceptions (NullMatrixException and IllegalMatrixSizeException).

Impact

Enhanced Matrix Functionality

• The addition of getRow and getColumn methods (including their static variants) improves the flexibility of matrix manipulation by allowing direct access to specific rows and columns. This enhancement is particularly useful for matrix operations where specific rows or columns need to be extracted and analyzed.
• The introduction of getCol as an alias for getColumn standardizes the naming conventions, making the API more intuitive and consistent for users.

Improved Matrix Validation

• The new methods for checking permutation matrices (isPermutationMatrix() instance method, isPermutationMatrix(Matrix m) static method, and isPermutationMatrix(double[][] arr) static method) provide a robust way to validate matrices against the permutation matrix criteria. This is essential for applications that require verification of matrix properties, such as those involving matrix decompositions or combinatorial algorithms.

Backward Compatibility

• The changes are backward-compatible and introduce new functionality without altering existing methods. This ensures that existing code relying on the Matrix class remains unaffected, while new features can be utilized where needed.

Performance Considerations

• The new permutation matrix checks are designed to operate with a time complexity of O(n^2) and a space complexity of O(1), making them efficient for matrices of reasonable size. However, users should be aware of the potential performance implications for very large matrices.

Example Usage

// Creating a matrix
Matrix matrix = new Matrix(new double[][] {
    {1, 0, 0},
    {0, 1, 0},
    {0, 0, 1}
});

// Retrieving a row and column
double[] row = matrix.getRow(0);  // [1, 0, 0]
double[] column = matrix.getColumn(1);  // [0, 1, 0]

// Checking if the matrix is a permutation matrix
boolean isPermMatrix = matrix.isPermutationMatrix();  // true

// Using static methods
double[][] arr = {
    {1, 0},
    {0, 1}
};
boolean isPermMatrixFromArray = Matrix.isPermutationMatrix(arr);  // true

These updates aim to enhance the functionality and usability of the Matrix class by providing more robust methods for matrix operations and checks.