JMatrix

Developed by one person (Ryuu Mitsuki) :fire:

🪐 About JMatrix

JMatrix is an educational Java library and designed to facilitate and simplify matrix operations.
It offers a range of intuitive methods to perform common matrix operations with ease, making it an ideal learning tool for high school students exploring linear algebra concepts.

[!IMPORTANT]
This project is currently in development and is intended for educational purposes only.
It is not recommended for use in large-scale projects or production environments.

JMatrix provides following basic matrix operations:

• Addition
• Subtraction
• Multiplication
• Transposition
• (additional matrix operations will be added in the future)

In addition to the fundamental matrix operations, JMatrix also includes matrix type checkers, allowing students or users to identify certain characteristics of matrices:

• isDiagonal - Check whether the matrix is diagonal.
• isSquare - Check whether the matrix is square.
• isLowerTriangular - Check whether the matrix is lower triangular.
• isUpperTriangular - Check whether the matrix is upper triangular.
• (more matrix type checkers will be added in the future).

🔌 Installation

If you are interested in obtaining the latest stable version of the project, please check the latest version. You can download the archived package containing compiled classes from there.

For improved stability and better usability, we highly recommend downloading the archived package that also includes the source files (jmatrix-<VERSION>_with_sources.jar). This package contains all the necessary documentation about classes, methods, and other aspects related to JMatrix, making it easier to explore and understand the project.

[!WARNING]
Currently, there is an issue with pre-build processes when using Make on Windows systems. The issue was that it failed while trying to create child processes to configure the build requirements.

For better functionality, we recommend using Maven instead. Because using Make is an alternative way for flexibility on UNIX systems.

🎯 Prerequisites

For Normal Use

• Java (min. JDK 11, recommended is JDK 17 and later)
• Git Bash (optional, Windows only)

For Building the Project

• Java (min. JDK 11, recommended is JDK 17 and later).
• Python (min. version 3.7, recommended is 3.11 and later).
• Latest version of Make or Maven.

[!IMPORTANT]
If you choose to build the project using Maven, you don't need Python.

Sadly, we're having a problem with pre-build processes on Windows systems. It is recommended to use Maven instead if you're using Windows to build the project, ensuring better functionality.

For more detailed instructions on building the project, you can refer to the :bookmark:Getting Started page.

Once you have the necessary prerequisites, you can start exploring and using JMatrix in your projects. The documentation included in the archived package will guide you through the classes, methods, and functionalities offered by the library.

Constructor Summary

[!NOTE]
If you are unfamiliar with matrices or need a refresher, you can check the :bookmark:Introduction to Matrix page to gain a basic understanding before delving into matrix constructors.

Matrix()

// Create a null entries matrix
Matrix m = new Matrix();

Matrix(int rows, int cols)

With this constructor, you can create a zero matrix with ease by providing two arguments: the number of rows and columns. A zero matrix contains all elements as zeros. For example:

// Create null matrix with size 3x4
Matrix m = new Matrix(3, 4);

The code above constructs a new zero matrix with size $3 \times 4$. The matrix will look like this:

\begin{bmatrix}
  0.0 & 0.0 & 0.0 & 0.0 \\
  0.0 & 0.0 & 0.0 & 0.0 \\
  0.0 & 0.0 & 0.0 & 0.0
\end{bmatrix}

Matrix(int rows, int cols, int val)

This constructor is similar to Matrix(int rows, int cols) but with an additional argument that sets the value for all elements of the constructed matrix. For example:

// Create a new matrix with size 4x4 and set all elements to 5
Matrix m = new Matrix(4, 4, 5);

The constructed matrix will look like this:

\begin{bmatrix}
  5.0 & 5.0 & 5.0 & 5.0 \\
  5.0 & 5.0 & 5.0 & 5.0 \\
  5.0 & 5.0 & 5.0 & 5.0 \\
  5.0 & 5.0 & 5.0 & 5.0
\end{bmatrix}

Matrix(double[][] array)

This constructor is highly recommended for constructing a new matrix. You can declare the entries first and then convert them into a Matrix object whenever needed.

[!NOTE]
Please note, this constructor only accepts two-dimensional array with type of double.

For example:

// Declare and initialize entries "a"
double[][] a = {
    { 1, 2, 3 },
    { 4, 5, 6 }
};

// Convert to Matrix
Matrix m = new Matrix(a);

Alternatively, you can directly create a new matrix using this code:

// Create new matrix
Matrix m = new Matrix(new double[][] {
    { 1, 2, 3 },
    { 4, 5, 6 }
});

Matrix.identity(int)

// Create new identity matrix with size 5x5
Matrix mI = Matrix.identity(5);

\begin{bmatrix}
  1.0 & 0.0 & 0.0 & 0.0 & 0.0 \\
  0.0 & 1.0 & 0.0 & 0.0 & 0.0 \\
  0.0 & 0.0 & 1.0 & 0.0 & 0.0 \\
  0.0 & 0.0 & 0.0 & 1.0 & 0.0 \\
  0.0 & 0.0 & 0.0 & 0.0 & 1.0
\end{bmatrix}

Matrix Operations

• Addition
• Subtraction
• Scalar Multiplication
• Matrix Multiplication
• Transposition

For more detailed information about each matrix operation, you can refer to the :books: JMatrix Wikis.

Addition

:book: Wiki: Matrix Addition

In matrix addition, two matrices with the same dimensions are added together element-wise. Each element of the resulting matrix is the sum of the corresponding elements from the two input matrices.

[!IMPORTANT]
Before performing matrix addition, ensure that the two matrices have the same dimensions.

Example code:

// Construct new matrices
Matrix m = new Matrix(new double[][] {
    { 6, 7, 0, 1 },
    { 2, 6, 1, 8 }
});

Matrix n = new Matrix(new double[][] {
    { 1, 9, 3, -4 },
    { 7, 1, -1, 5 }
});

// Perform addition for both matrices and
// create a new matrix as the resultant matrix
Matrix k = Matrix.sum(m, n);

Result:

\mathbf{k} =
\begin{bmatrix}
  7.0 & 16.0 & 3.0 & -3.0 \\
  9.0 & 7.0 & 0.0 & 13.0
\end{bmatrix}

In the example above, two matrices $m$ and $n$ are created. The Matrix.sum(m, n) method is used to add both matrices element-wise, and the resulting matrix $k$ is computed and stored. The output matrix $k$ is the sum of matrices $m$ and $n$.

Subtraction

:book: Wiki: Matrix Subtraction

Matrix subtraction involves subtracting corresponding elements of one matrix from another.

Important
Before performing matrix subtraction, ensure that the two matrices have the same dimensions.

Example code:

// Construct new matrices
Matrix m = new Matrix(new double[][] {
    { 1, -5, 8, -2, 3 },
    { 2, 12, -2, 7, 0 },
    { 6, 7, 9, 1, -5 }
});

Matrix n = new Matrix(new double[][] {
    { 4, 6, 8, -3, 9 },
    { -10, 6, 8, 1, 1 },
    { 6, -7, 2, 3, 5 }
});

// Perform subtraction for both matrices and
// create a new matrix as the resultant matrix
Matrix k = Matrix.sub(m, n);

Result:

\mathbf{k} =
\begin{bmatrix}
  -3.0 & -11.0 & 0.0 & 1.0 & -6.0 \\
  12.0 & 6.0 & -10.0 & 6.0 & -1.0 \\
  0.0 & 14.0 & 7.0 & -2.0 & -10.0
\end{bmatrix}

In the example above, two matrices $m$ and $n$ are created. The Matrix.sub(m, n) method is used to subtract $n$ from $m$ element-wise, and the resulting matrix $k$ is computed and stored. The output matrix $k$ is the difference between matrices $m$ and $n$.

Scalar Multiplication

:book: Wiki: Scalar Multiplication

Scalar multiplication involves multiplying all elements of a matrix by a scalar value. The resulting matrix will have each of its elements multiplied by the given scalar value.

[!NOTE]
The resulting matrix's sizes of scalar multiplication will be always the same with the sizes of the operand matrix.

Example code:

// Construct new matrix
Matrix m = new Matrix(new double[][] {
    { 9, 6, 4 },
    { 2, 1, 5 }
});

// Perform scalar multiplication with the scalar equal to 5
// and create a new matrix as the resultant matrix
Matrix s = Matrix.mult(m, 5);

Result:

\mathbf{s} =
\begin{bmatrix}
  45.0 & 30.0 & 20.0 \\
  10.0 & 5.0 & 25.0
\end{bmatrix}

In the example above, a matrix $m$ is created. The Matrix.mult(m, 5) method is used to multiply each element of matrix $m$ by the scalar value 5, resulting in a new matrix $s$.

Matrix Multiplication

:book: Wiki: Matrix Multiplication

Matrix multiplication involves multiplying two matrices together following a specific rule.

[!IMPORTANT]
Before performing matrix multiplication, ensure the number of columns in the first matrix must be equal to the number of rows in the second matrix.

Example code:

// Create and construct new matrices
Matrix m = new Matrix(new double[][] {
    { 2, 2, 2, 2 },
    { 2, 2, 2, 2 }
});

Matrix n = new Matrix(new double[][] {
    { 4, 4 },
    { 4, 4 },
    { 4, 4 },
    { 4, 4 }
});

// Operate matrix multiplication for both matrices
// and create a new matrix as the resultant matrix
Matrix mn = Matrix.mult(m, n);

Result:

\mathbf{mn} =
\begin{bmatrix}
  32.0 & 32.0 \\
  32.0 & 32.0
\end{bmatrix}

In the example above, two matrices $m$ and $n$ are created. The Matrix.mult(m, n) method is used to perform matrix multiplication between matrices $m$ and $n$, resulting in a new matrix $mn$.

Transposition

:book: Wiki: Matrix Transposition

Matrix transposition involves swapping the rows and columns of a matrix. The resulting matrix will have its rows and columns interchanged.

[!NOTE]
Repeating this operation to the transposed matrix will reset their indices position to the original position.

Example code:

// Create and construct new matrix
Matrix m = new Matrix (new double[][] {
    { 1, 2, 3, 4 },
    { 5, 6, 7, 8 }
});

// Transpose the matrix and create a new matrix
// to store the transposed matrix
Matrix mT = Matrix.transpose(m);

Result:

\mathbf{mT} =
\begin{bmatrix}
  1.0 & 5.0 \\
  2.0 & 6.0 \\
  3.0 & 7.0 \\
  4.0 & 8.0
\end{bmatrix}

In the example above, a matrix $m$ is created. The Matrix.transpose(m) method is used to transpose matrix $m$, resulting in a new matrix $mT$ with the rows and columns interchanged.

Author

JMatrix is developed and maintained by Ryuu Mitsuki.

As the sole developer of the project, Ryuu Mitsuki responsible for the continuous improvement and updates of the library. He is committed to providing a valuable and user-friendly educational resource for high school students and anyone interested in exploring linear algebra concepts through the JMatrix library and Java.

License

JMatrix is licensed under the Apache License 2.0. This license permits you to use, modify, distribute, and sublicense the software, subject to certain conditions.

You are free to use JMatrix for both commercial and non-commercial purposes. If you modify the software, you must clearly indicate the changes you made. Any contributions you make to the project are also subject to the same license terms.

The Apache License 2.0 allows you to distribute derivative works, but you must include the full text of the license in your distribution. Additionally, you are responsible for ensuring that any downstream recipients of the software are aware of its licensing terms.

For more details about the permissions, limitations, and conditions under which JMatrix is licensed, please refer to the LICENSE file provided with the project. The LICENSE file contains the complete text of "The License", ensuring full transparency and clarity regarding the terms of use for the software.

By using JMatrix, you agree to comply with the terms of the Apache License 2.0 and understand your rights and responsibilities as a user of this open-source software.