Class Matrix

java.lang.Object
cloud.opencode.base.math.linalg.Matrix
public final class Matrix extends Object
Immutable mathematical matrix backed by a double[][] array. 不可变数学矩阵，底层使用 double[][] 数组存储。

All operations return new Matrix instances; the original is never modified. Thread-safe by virtue of immutability.

所有运算均返回新的 Matrix 实例，原始对象不会被修改。 因不可变性而天然线程安全。

For determinant and inverse of matrices larger than 3x3, LU decomposition with partial pivoting is used for numerical stability and performance.

对于大于 3x3 的矩阵，其行列式和逆矩阵计算使用带部分主元选取的 LU 分解， 以保证数值稳定性和性能。

Since:
JDK 25, opencode-base-math V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Matrix
    add(Matrix other)
    Returns the element-wise sum of this matrix and another.
    int
    cols()
    Returns the number of columns.
    double
    determinant()
    Returns the determinant of this square matrix.
    boolean
    equals(Object o)
     
    double
    get(int row, int col)
    Returns the element at the given row and column.
    int
    hashCode()
     
    static Matrix
    identity(int n)
    Creates an identity matrix of size n.
    Matrix
    inverse()
    Returns the inverse of this square matrix using LU decomposition with partial pivoting.
    boolean
    isSquare()
    Returns true if this matrix is square.
    boolean
    isSymmetric()
    Returns true if this matrix is symmetric (A = A^T).
    Matrix
    multiply(Matrix other)
    Returns the product of this matrix and another.
    Vector
    multiplyVector(Vector v)
    Returns the result of multiplying this matrix by a vector.
    static Matrix
    of(double[][] data)
     
    int
    rows()
    Returns the number of rows.
    Matrix
    scalarMultiply(double scalar)
    Returns this matrix multiplied by a scalar.
    Matrix
    subtract(Matrix other)
    Returns the element-wise difference of this matrix and another.
    double[][]
    toArray()
    Returns a defensive copy of the internal data as a 2D array.
    String
    toString()
     
    double
    trace()
    Returns the trace (sum of diagonal elements) of this square matrix.
    Matrix
    transpose()
    Returns the transpose of this matrix.
    static Matrix
    zero(int rows, int cols)
    Creates a zero matrix with the given dimensions.

    Methods inherited from class Object

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

  • Method Details

    • of

      public static Matrix of(double[][] data)

    • identity

      public static Matrix identity(int n)
      Creates an identity matrix of size n. 创建 n 阶单位矩阵。
      Parameters:
      n - the size / 阶数
      Returns:
      the identity matrix / 单位矩阵
      Throws:
      MathException - if n is not positive / 如果 n 不是正整数

    • zero

      public static Matrix zero(int rows, int cols)
      Creates a zero matrix with the given dimensions. 创建指定维度的零矩阵。
      Parameters:
      rows - the number of rows / 行数
      cols - the number of columns / 列数
      Returns:
      the zero matrix / 零矩阵
      Throws:
      MathException - if rows or cols is not positive / 如果行数或列数不是正整数

    • rows

      public int rows()
      Returns the number of rows. 返回行数。
      Returns:
      the number of rows / 行数

    • cols

      public int cols()
      Returns the number of columns. 返回列数。
      Returns:
      the number of columns / 列数

    • get

      public double get(int row, int col)
      Returns the element at the given row and column. 返回指定行列处的元素。
      Parameters:
      row - the row index (zero-based) / 行索引（从 0 开始）
      col - the column index (zero-based) / 列索引（从 0 开始）
      Returns:
      the element value / 元素值
      Throws:
      MathException - if the indices are out of bounds / 如果索引越界

    • add

      public Matrix add(Matrix other)
      Returns the element-wise sum of this matrix and another. 返回此矩阵与另一个矩阵的逐元素之和。
      Parameters:
      other - the other matrix / 另一个矩阵
      Returns:
      the sum matrix / 求和矩阵
      Throws:
      MathException - if dimensions do not match / 如果维度不匹配

    • subtract

      public Matrix subtract(Matrix other)
      Returns the element-wise difference of this matrix and another. 返回此矩阵与另一个矩阵的逐元素之差。
      Parameters:
      other - the other matrix / 另一个矩阵
      Returns:
      the difference matrix / 差值矩阵
      Throws:
      MathException - if dimensions do not match / 如果维度不匹配

    • multiply

      public Matrix multiply(Matrix other)
      Returns the product of this matrix and another. 返回此矩阵与另一个矩阵的乘积。
      Parameters:
      other - the other matrix / 另一个矩阵
      Returns:
      the product matrix / 乘积矩阵
      Throws:
      MathException - if inner dimensions do not match / 如果内部维度不匹配

    • multiplyVector

      public Vector multiplyVector(Vector v)
      Returns the result of multiplying this matrix by a vector. 返回此矩阵与向量相乘的结果。
      Parameters:
      v - the vector / 向量
      Returns:
      the resulting vector / 结果向量
      Throws:
      MathException - if the vector dimension does not match the number of columns / 如果向量维度与列数不匹配

    • scalarMultiply

      public Matrix scalarMultiply(double scalar)
      Returns this matrix multiplied by a scalar. 返回此矩阵乘以标量的结果。
      Parameters:
      scalar - the scalar / 标量
      Returns:
      the scaled matrix / 缩放后的矩阵

    • transpose

      public Matrix transpose()
      Returns the transpose of this matrix. 返回此矩阵的转置。
      Returns:
      the transposed matrix / 转置矩阵

    • determinant

      public double determinant()
      Returns the determinant of this square matrix. 返回此方阵的行列式。

      Uses LU decomposition with partial pivoting for matrices larger than 3x3.

      对于大于 3x3 的矩阵使用带部分主元选取的 LU 分解。

      Returns:
      the determinant / 行列式
      Throws:
      MathException - if the matrix is not square / 如果矩阵不是方阵

    • inverse

      public Matrix inverse()
      Returns the inverse of this square matrix using LU decomposition with partial pivoting. 使用带部分主元选取的 LU 分解返回此方阵的逆矩阵。

      Uses in-place LU decomposition followed by forward/back substitution for each column of the identity matrix, reducing memory usage by ~50% compared to the augmented matrix approach.

      使用原地 LU 分解，再对单位矩阵的每一列进行前向/回代求解， 相比增广矩阵方法减少约 50% 内存使用。

      Returns:
      the inverse matrix / 逆矩阵
      Throws:
      MathException - if the matrix is not square or is singular / 如果矩阵不是方阵或是奇异矩阵

    • trace

      public double trace()
      Returns the trace (sum of diagonal elements) of this square matrix. 返回此方阵的迹（对角线元素之和）。
      Returns:
      the trace / 迹
      Throws:
      MathException - if the matrix is not square / 如果矩阵不是方阵

    • isSquare

      public boolean isSquare()
      Returns true if this matrix is square. 如果此矩阵是方阵，返回 true。
      Returns:
      whether the matrix is square / 是否为方阵

    • isSymmetric

      public boolean isSymmetric()
      Returns true if this matrix is symmetric (A = A^T). 如果此矩阵是对称的（A = A^T），返回 true。
      Returns:
      whether the matrix is symmetric / 是否对称

    • toArray

      public double[][] toArray()
      Returns a defensive copy of the internal data as a 2D array. 返回内部数据的防御性拷贝（二维数组）。
      Returns:
      a copy of the data / 数据的拷贝

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object