NAME

Sidef::Types::Array::Matrix - Mathematical matrix operations in Sidef

DESCRIPTION

This class implements a mathematical matrix type with support for standard linear algebra operations including addition, subtraction, multiplication, division, inversion, determinants, and solving systems of linear equations. Matrices can be manipulated using both operator overloading and method calls.

The Matrix class provides efficient implementations of common matrix operations and supports both element-wise and matrix-specific computations. It inherits from Array, allowing array methods to be used on matrices when appropriate.

SYNOPSIS

var A = Matrix(
    [2, -3,  1],
    [1, -2, -2],
    [3, -4,  1],
)

var B = Matrix(
    [9, -3, -2],
    [3, -1,  7],
    [2, -4, -8],
)

say (A + B)     # matrix addition
say (A - B)     # matrix subtraction
say (A * B)     # matrix multiplication
say (A / B)     # matrix division

say (A + 42)    # matrix-scalar addition
say (A - 42)    # matrix-scalar subtraction
say (A * 42)    # matrix-scalar multiplication
say (A / 42)    # matrix-scalar division

say A**20       # matrix exponentiation
say A**-1       # matrix inverse: A^-1
say A**-2       # (A^2)^-1

say B.det             # matrix determinant
say B.solve([1,2,3])  # solve a system of linear equations

# Create special matrices
var identity = Matrix.I(3)          # 3×3 identity matrix
var zeros = Matrix.zero(2, 3)       # 2×3 zero matrix
var random = Matrix.rand(3, 3)      # 3×3 random matrix

# Matrix properties and operations
say A.transpose         # transpose of A
say A.row_len          # number of rows
say A.col_len          # number of columns
say A.is_square        # check if square matrix
say A.diagonal         # extract diagonal elements

INHERITS

Inherits methods from:

* Sidef::Types::Array::Array

METHODS

%

a % b

Returns the element-wise modulo of matrix a with matrix or scalar b. Each element of the result is the modulo of the corresponding elements.

Matrix([[5, 8], [10, 15]]) % 3  #=> Matrix([[2, 2], [1, 0]])

Aliases: mod

&

a & b

Returns the element-wise bitwise AND of matrix a with matrix or scalar b.

Matrix([[12, 8], [15, 7]]) & 3  #=> Matrix([[0, 0], [3, 3]])

Aliases: and

*

a * b

Returns the matrix product of a and b. If b is a scalar, performs scalar multiplication (each element multiplied by the scalar). If both are matrices, performs standard matrix multiplication.

Matrix([[1, 2], [3, 4]]) * Matrix([[5, 6], [7, 8]])  # matrix multiplication
Matrix([[1, 2], [3, 4]]) * 10                         # scalar multiplication

Aliases: mul

**

a ** b

Returns the matrix a raised to the power b. For positive integers, performs repeated matrix multiplication. For negative integers, computes the inverse first. For b = 0, returns the identity matrix.

A ** 3      # A * A * A
A ** -1     # inverse of A
A ** 0      # identity matrix

Aliases: pow

+

a + b

Returns the element-wise sum of matrix a and matrix or scalar b. For two matrices, they must have the same dimensions.

Matrix([[1, 2], [3, 4]]) + Matrix([[5, 6], [7, 8]])  #=> Matrix([[6, 8], [10, 12]])
Matrix([[1, 2], [3, 4]]) + 10                         #=> Matrix([[11, 12], [13, 14]])

Aliases: add

-

a - b

Returns the element-wise difference of matrix a and matrix or scalar b. For two matrices, they must have the same dimensions.

Matrix([[5, 6], [7, 8]]) - Matrix([[1, 2], [3, 4]])  #=> Matrix([[4, 4], [4, 4]])
Matrix([[5, 6], [7, 8]]) - 5                          #=> Matrix([[0, 1], [2, 3]])

Aliases: sub

/

a / b

Returns the matrix division of a by b. If b is a matrix, this computes a * b^-1 (matrix a multiplied by the inverse of matrix b). If b is a scalar, divides each element by the scalar.

Matrix([[2, 4], [6, 8]]) / 2  #=> Matrix([[1, 2], [3, 4]])

Aliases: ÷, div

^

a ^ b

Returns the element-wise bitwise XOR of matrix a with matrix or scalar b.

Matrix([[12, 8], [15, 7]]) ^ 5  #=> Matrix([[9, 13], [10, 2]])

Aliases: xor

I

Matrix.I(n)

Returns an n×n identity matrix (square matrix with 1s on the main diagonal and 0s elsewhere).

Matrix.I(3)  #=> Matrix([[1, 0, 0], [0, 1, 0], [0, 0, 1]])

Aliases: identity

|

a | b

Returns the element-wise bitwise OR of matrix a with matrix or scalar b.

Matrix([[8, 4], [2, 1]]) | 1  #=> Matrix([[9, 5], [3, 1]])

Aliases: or

abs

m1.abs

Returns a new matrix with the absolute value of each element.

Matrix([[-1, 2], [-3, -4]]).abs  #=> Matrix([[1, 2], [3, 4]])

anti_diagonal

self.anti_diagonal

Returns an array containing the elements on the anti-diagonal (secondary diagonal) of the matrix, from top-right to bottom-left.

Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]]).anti_diagonal  #=> [3, 5, 7]

build

Matrix.build(n, m, block)

Returns an n×m matrix where each element at position (i, j) is computed by calling block with arguments i and j.

Matrix.build(3, 3, {|i,j| i + j })  #=> Matrix([[0, 1, 2], [1, 2, 3], [2, 3, 4]])

ceil

self.ceil

Returns a new matrix with each element rounded up to the nearest integer.

Matrix([[1.2, 2.7], [3.1, 4.9]]).ceil  #=> Matrix([[2, 3], [4, 5]])

col

self.col(n)

Returns the nth column of the matrix as an array (0-indexed).

Matrix([[1, 2, 3], [4, 5, 6]]).col(1)  #=> [2, 5]

Aliases: column, get_column

col_len

A.col_len

Returns the number of columns in matrix A.

Matrix([[1, 2, 3], [4, 5, 6]]).col_len  #=> 3

Aliases: col_size, col_count, column_len, column_size, column_count

cols

self.cols(*cols)

Returns a new matrix constructed from the specified column indices of the current matrix.

Matrix([[1, 2, 3], [4, 5, 6]]).cols(0, 2)  #=> Matrix([[1, 3], [4, 6]])

Aliases: columns, from_cols, from_columns

col_vector

Matrix.col_vector(*list)

Creates a column vector (n×1 matrix) from the provided list of values.

Matrix.col_vector(1, 2, 3)  #=> Matrix([[1], [2], [3]])

Aliases: column_vector

concat

m1.concat(m2)

Returns a new matrix formed by concatenating matrix m2 to the right of matrix m1. Both matrices must have the same number of rows.

Matrix([[1, 2], [3, 4]]).concat(Matrix([[5], [6]]))  #=> Matrix([[1, 2, 5], [3, 4, 6]])

det

self.det

Returns the determinant of the matrix. The matrix must be square.

Matrix([[1, 2], [3, 4]]).det  #=> -2

Aliases: determinant

det_bareiss

self.det_bareiss

Returns the determinant of the matrix using the Bareiss algorithm, which is efficient for integer matrices and preserves exactness.

Matrix([[2, 3], [4, 5]]).det_bareiss  #=> -2

diagonal

self.diagonal

Returns an array containing the elements on the main diagonal of the matrix (from top-left to bottom-right).

Matrix([[1, 2, 3], [4, 5, 6], [7, 8, 9]]).diagonal  #=> [1, 5, 9]

flip

self.flip

Returns a new matrix that is the vertical flip (reflection) of the current matrix. Equivalent to reversing the order of rows.

Matrix([[1, 2], [3, 4], [5, 6]]).flip  #=> Matrix([[5, 6], [3, 4], [1, 2]])

floor

self.floor

Returns a new matrix with each element rounded down to the nearest integer.

Matrix([[1.7, 2.3], [3.8, 4.2]]).floor  #=> Matrix([[1, 2], [3, 4]])

gauss_jordan_invert

self.gauss_jordan_invert

Returns the inverse of the matrix using Gauss-Jordan elimination. The matrix must be square and invertible (non-zero determinant).

Matrix([[1, 2], [3, 4]]).gauss_jordan_invert  #=> Matrix([[-2, 1], [1.5, -0.5]])

gauss_jordan_solve

self.gauss_jordan_solve(vector)

Solves the system of linear equations Ax = b using Gauss-Jordan elimination, where A is the matrix, x is the unknown vector, and b is the provided vector.

Matrix([[2, 1], [1, 3]]).gauss_jordan_solve([5, 6])  #=> [1.8, 1.4]

horizontal_flip

self.horizontal_flip

Returns a new matrix that is the horizontal flip (reflection) of the current matrix. Each row is reversed.

Matrix([[1, 2, 3], [4, 5, 6]]).horizontal_flip  #=> Matrix([[3, 2, 1], [6, 5, 4]])

inv

self.inv

Returns the inverse of the matrix. The matrix must be square and invertible (have a non-zero determinant).

Matrix([[1, 2], [3, 4]]).inv  #=> Matrix([[-2, 1], [1.5, -0.5]])

Aliases: invert, inverse

invmod

self.invmod(mod)

Returns the modular inverse of the matrix modulo mod. The matrix must be square and have a determinant coprime to mod.

Matrix([[1, 2], [3, 4]]).invmod(7)  #=> Matrix([[5, 1], [4, 3]])

is_square

self.is_square

Returns true if the matrix is square (has the same number of rows and columns), false otherwise.

Matrix([[1, 2], [3, 4]]).is_square          #=> true
Matrix([[1, 2, 3], [4, 5, 6]]).is_square    #=> false

neg

m1.neg

Returns a new matrix with the negation of each element (each element multiplied by -1).

Matrix([[1, -2], [3, -4]]).neg  #=> Matrix([[-1, 2], [-3, 4]])

new

self.new

Creates a new matrix from arrays representing rows. Can also be called as Matrix(...).

Matrix.new([1, 2], [3, 4])  #=> Matrix([[1, 2], [3, 4]])
Matrix([1, 2], [3, 4])      #=> Matrix([[1, 2], [3, 4]])

Aliases: call

powmod

A.powmod(pow, mod)

Returns the matrix A raised to the power pow modulo mod. Useful for modular exponentiation of matrices.

Matrix([[1, 1], [1, 0]]).powmod(10, 1000)  # Fibonacci matrix exponentiation

prod

A.prod(block)

Returns the product of all elements obtained by applying block to each element of the matrix.

Matrix([[1, 2], [3, 4]]).prod {|x| x + 1 }  #=> 120  (2*3*4*5)

Aliases: prod_by

rand

Matrix.rand(n, m)

Returns an n×m matrix with random floating-point values between 0 and 1.

Matrix.rand(2, 3)  #=> Matrix with 2 rows and 3 columns of random values

row

self.row(n)

Returns the nth row of the matrix as an array (0-indexed).

Matrix([[1, 2, 3], [4, 5, 6]]).row(0)  #=> [1, 2, 3]

Aliases: get_row

row_len

A.row_len

Returns the number of rows in matrix A.

Matrix([[1, 2, 3], [4, 5, 6]]).row_len  #=> 2

Aliases: row_size, row_count

rows

self.rows(*rows)

Returns a new matrix constructed from the specified row indices of the current matrix.

Matrix([[1, 2], [3, 4], [5, 6]]).rows(0, 2)  #=> Matrix([[1, 2], [5, 6]])

Aliases: from_rows

row_vector

Matrix.row_vector(*list)

Creates a row vector (1×n matrix) from the provided list of values.

Matrix.row_vector(1, 2, 3)  #=> Matrix([[1, 2, 3]])

rref

self.rref

Returns the reduced row echelon form (RREF) of the matrix using Gaussian elimination. Useful for solving systems of linear equations and finding matrix rank.

Matrix([[2, 1, -1], [1, 3, 2]]).rref  #=> reduced form

Aliases: reduced_row_echelon_form

scalar

Matrix.scalar(n, value)

Returns an n×n scalar matrix (diagonal matrix with the same value on all diagonal positions).

Matrix.scalar(3, 5)  #=> Matrix([[5, 0, 0], [0, 5, 0], [0, 0, 5]])

set_col

A.set_col(k, col)

Sets the kth column of matrix A to the values in array col. Modifies the matrix in place.

var m = Matrix([[1, 2], [3, 4]])
m.set_col(0, [5, 6])  #=> Matrix([[5, 2], [6, 4]])

Aliases: set_column

set_row

A.set_row(k, row)

Sets the kth row of matrix A to the values in array row. Modifies the matrix in place.

var m = Matrix([[1, 2], [3, 4]])
m.set_row(0, [5, 6])  #=> Matrix([[5, 6], [3, 4]])

size

self.size

Returns an array containing the dimensions of the matrix as [rows, columns].

Matrix([[1, 2, 3], [4, 5, 6]]).size  #=> [2, 3]

solve

self.solve(vector)

Solves the system of linear equations Ax = b, where A is the matrix, x is the unknown vector, and b is the provided vector. Returns the solution vector x.

Matrix([[3, 2], [1, 2]]).solve([7, 5])  #=> [1, 2]

sum

A.sum(block)

Returns the sum of all elements obtained by applying block to each element of the matrix.

Matrix([[1, 2], [3, 4]]).sum {|x| x * x }  #=> 30  (1+4+9+16)

Aliases: sum_by

t

matrix.t

Returns the transpose of the matrix (rows and columns swapped).

Matrix([[1, 2, 3], [4, 5, 6]]).t  #=> Matrix([[1, 4], [2, 5], [3, 6]])

Aliases: not, transpose

to_a

A.to_a

Returns the matrix as an array of arrays (each inner array represents a row).

Matrix([[1, 2], [3, 4]]).to_a  #=> [[1, 2], [3, 4]]

Aliases: to_array

to_s

self.to_s

Returns a string representation of the matrix suitable for display or debugging.

Matrix([[1, 2], [3, 4]]).to_s  #=> "Matrix([[1, 2], [3, 4]])"

Aliases: dump, to_str

vec_cols

self.vec_cols

Returns an array of column vectors, where each column of the matrix is represented as a separate column vector (matrix).

Matrix([[1, 2], [3, 4]]).vec_cols  #=> [Matrix([[1], [3]]), Matrix([[2], [4]])]

Aliases: vec_columns, vector_columns

vec_rows

self.vec_rows

Returns an array of row vectors, where each row of the matrix is represented as a separate row vector (matrix).

Matrix([[1, 2], [3, 4]]).vec_rows  #=> [Matrix([[1, 2]]), Matrix([[3, 4]])]

Aliases: vector_rows

vertical_flip

self.vertical_flip