Matrix¶

The Matrix class provides comprehensive matrix operations implemented with Lua tables, supporting arithmetic functions, determinant calculation, inversion, and solving systems of linear equations using Gauss-Jordan elimination. It handles various matrix types including complex and symbolic matrices, allowing for versatile applications from simple to advanced mathematical computations. Typical use cases include matrix addition, multiplication, transposition, and manipulation in scientific computing, engineering, and data analysis tasks within Lua environments.

Usage¶

To use this class, add the following require at the top of your script:

local Matrix = require 'engine/math/matrix'

Reference¶

class Matrix¶

module:

static new4x4(data)¶

Create a new 4×4 matrix.

If no data is provided, this returns the 4×4 identity matrix \(I\). If an array of numbers is provided, it fills the matrix row by row.

Parameters:: data (table) – optional array of 16 numbers to fill the matrix
Returns:: new 4×4 matrix
Return type:: Matrix

static new3x3(data)¶

Create a new 3×3 matrix.

If no data is provided, this returns the 3×3 identity matrix \(I\). If an array of numbers is provided, it fills the matrix row by row.

Parameters:: data (table) – optional array of 9 numbers to fill the matrix
Returns:: new 3×3 matrix
Return type:: Matrix

new(rows, columns, data)¶

Create a new matrix

Usage patterns:

Matrix:new(rows, columns, data) Create a matrix of size rows × columns. If data is a number, all values are initialized with that number. If data is a table, values are filled row by row.

Matrix:new(rows, “I”) Create an identity matrix of size rows × rows.

Matrix:new(table) If table is a 2D array (table of tables), wrap it as a Matrix. If table is a simple array {x, y, z}, create a 3×1 vector matrix.

Parameters:

rows (number or table) – Number of rows or an initializer table
columns (number or str) – Number of columns, or “I” for identity
data (number or table) – Fill value (number) or table of values

Returns:

new matrix

Return type:

Matrix

static add(A, B)¶

Add two matrices element-wise.

The result is defined as \(C = A + B\) with \(c_{ij} = a_{ij} + b_{ij}\). Matrix \(B\) may be of bigger size than matrix \(A\).

Parameters:

A (Matrix) – first matrix \(A\)
B (Matrix) – second matrix \(B\)

Returns:

result of addition \(A + B\)

Return type:

Matrix

static sub(A, B)¶

Subtract two matrices element-wise.

The result is defined as \(C = A - B\) with \(c_{ij} = a_{ij} - b_{ij}\). Matrix \(B\) may be of bigger size than matrix \(A\).

Parameters:

A (Matrix) – first matrix \(A\)
B (Matrix) – second matrix \(B\)

Returns:

result of subtraction \(A - B\)

Return type:

Matrix

static mul(A, B)¶

Multiply two matrices.

The number of columns of matrix \(A\) must equal the number of rows of matrix \(B\): The result is defined as \(C = A \cdot B\) with \(c_{ij} = \sum_k a_{ik} b_{kj}\).

Parameters:

A (Matrix) – first matrix \(A\)
B (Matrix) – second matrix \(B\)

Returns:

result of multiplication \(A \cdot B\)

Return type:

Matrix

static div(A, B)¶

Divide two matrices.

Division is defined as multiplication with the inverse of the second matrix: \(A / B = A \cdot B^{-1}\). The number of columns of matrix \(A\) must equal the number of rows of matrix \(B\): The matrix \(B\) must be square and non-singular, to be invertible. On failure, returns \(B\) and the rank of \(B\).

Parameters:

A (Matrix) – numerator matrix \(A\)
B (Matrix) – denominator matrix \(B\)

Returns:

result of division \(A \cdot B^{-1}\), or nil if singular

Return type:

Matrix or nil

Returns:

? rank of m2 if inversion fails

Return type:

number

static mulnum(A, num)¶

Multiply a matrix with a scalar.

The scalar may be a real number or a complex number. Strings are first attempted to be parsed as complex numbers; if that fails, they are treated as symbols. The result is defined as \(C = \alpha \cdot A\) with \(c_{ij} = \alpha \, a_{ij}\).

Parameters:

A (Matrix) – matrix \(A\)
num (number or str) – scalar multiplier \(\alpha\)

Returns:

result of scalar multiplication \(\alpha \cdot A\)

Return type:

Matrix

static divnum(A, num)¶

Divide a matrix by a scalar.

Parameters:

A (Matrix) – matrix \(A\)
num (number or str) – scalar divisor \(\alpha\)

Returns:

result of division \(A / \alpha\)

Return type:

Matrix

mulVec3(vec)¶

Multiply a 3×3 matrix with a Vector3.

The result is a Vector3 \(v' = A \cdot v\).

Parameters:: vec (Vector3) – vector \(v\)
Returns:: result of multiplication
Return type:: Vector3

mulVec4(vec)¶

Multiply a 4×4 matrix with a Vector4.

The result is a Vector4 \(v' = A \cdot v\).

Parameters:: vec (Vector4) – vector \(v\)
Returns:: result of multiplication
Return type:: Vector4

static det(A)¶

Calculate the determinant \(\det(A)\) of a square matrix \(A\).

The matrix must be square \(n \times n\). Works for symbolic matrices up to 3×3, and numeric matrices of any size. The determinant is a scalar value that represents the scaling factor of the linear transformation defined by the matrix. Geometrically, it represents the area (for 2×2) or volume (for 3×3) spanned by the columns of the matrix.

Parameters:: A (Matrix) – square matrix \(A\)
Returns:: determinant \(\det(A)\)
Return type:: number

static invert(M)¶

Compute the inverse of a matrix.

The inverse \(M^{-1}\) of a matrix \(M\) is defined such that \(M \cdot M^{-1} = I\), where \(I\) is the identity matrix. The matrix \(M\) must be square and non-singular.

On success: returns the inverted matrix. On failure: returns nil and the rank of the matrix.

Parameters:: M (Matrix) – Matrix to invert
Returns:: inverted matrix or nil if singular
Return type:: Matrix or nil
Returns:: ? rank of the matrix when singular
Return type:: integer

static transpose(A)¶

Transpose a matrix.

The transpose of a matrix \(A\) is a new matrix \(A^T\) obtained by flipping rows and columns, so that the element at row \(i\), column \(j\) in \(A\) becomes the element at row \(j\), column \(i\) in \(A^T\).

Parameters:: A (Matrix) – matrix to transpose \(A\)
Returns:: transposed matrix \(A^T\)
Return type:: Matrix