Matrix operations


The math.matrices vocabulary implements many ways of working with matrices — sequences which have a minimum of 2 dimensions. Operations on 1-dimensional numeric vectors are implemented in math.vectors, upon which this vocabulary relies.

In this vocabulary's documentation, m and matrix are the conventional names used for a given matrix object. m may also refer to a number.

The math.matrices.extras vocabulary implements extensions to this one.

Matrices are classified their mathematical properties, and by predicate words:

matrix

irregular-matrix

square-matrix

zero-matrix

zero-square-matrix

null-matrix


matrix? ( object -- ? )

irregular-matrix? ( object -- ? )

square-matrix? ( object -- ? )

zero-matrix? ( object -- ? )

zero-square-matrix? ( object -- ? )

null-matrix? ( object -- ? )


There are many ways to create 2-dimensional matrices:
<matrix> ( m n element -- matrix )

<matrix-by> ( ... m n quot: ( ... -- ... elt ) -- ... matrix )

<matrix-by-indices> ( ... m n quot: ( ... m' n' -- ... elt ) -- ... matrix )


<zero-matrix> ( m n -- matrix )

<zero-square-matrix> ( n -- matrix )

<diagonal-matrix> ( diagonal-seq -- matrix )

<anti-diagonal-matrix> ( diagonal-seq -- matrix )

<identity-matrix> ( n -- matrix )

<simple-eye> ( m n k -- matrix )

<eye> ( m n k z -- matrix )


<coordinate-matrix> ( dim -- coordinates )

<square-rows> ( desc -- matrix )

<square-cols> ( desc -- matrix )

<upper-matrix> ( object m n -- matrix )

<lower-matrix> ( object m n -- matrix )

<cartesian-square-indices> ( n -- matrix )


By-element mathematical operations on a matrix:
matrix-normalize ( m -- m' )

mneg ( m -- m' )

m+n ( m n -- m )

m-n ( m n -- m )

m*n ( m n -- m )

m/n ( m n -- m )

n+m ( n m -- m )

n-m ( n m -- m )

n*m ( n m -- m )

n/m ( n m -- m )


By-element mathematical operations of two matrices:
m+ ( m1 m2 -- m )

m- ( m1 m2 -- m )

m* ( m1 m2 -- m )

m/ ( m1 m2 -- m )

m~ ( m1 m2 epsilon -- ? )


Dot product (multiplication) of vectors and matrices:
vdotm ( v m -- p )

mdotv ( m v -- p )

mdot ( m m -- m )


Transformations and elements of matrices:
dimension ( matrix -- dimension )

transpose ( matrix -- newmatrix )

anti-transpose ( matrix -- newmatrix )

matrix-nth ( pair matrix -- elt )

matrix-nths ( pairs matrix -- elts )

matrix-set-nth ( obj pair matrix -- )

matrix-set-nths ( obj pairs matrix -- )


row ( n matrix -- row )

rows ( seq matrix -- rows )

rows-except ( matrix desc -- others )

col ( n matrix -- col )

cols ( seq matrix -- cols )

cols-except ( matrix desc -- others )


matrix-except ( matrix exclude-pair -- submatrix )

matrix-except-all ( matrix -- submatrices )


matrix-map ( matrix quot: ( ... elt -- ... elt' ) -- matrix' )

column-map ( matrix quot: ( ... col -- ... col' ) -- matrix' )

stitch ( m -- m' )


main-diagonal ( matrix -- seq )

anti-diagonal ( matrix -- seq )


The following matrix norms are provided in the 𝑙ₚ and L^p,q vector spaces; these words are equivalent to ∥・∥ₚ and ∥・∥^p,q for p = 1, 2, ∞, ℝ, and p, q ∈ ℝ, respectively:
matrix-l1-norm ( m -- n )

matrix-l2-norm ( m -- n )

matrix-l-infinity-norm ( m -- n )

matrix-p-norm ( m p -- n )

matrix-p-q-norm ( m p q -- n )


For readability, user code should prefer the available generic versions of the above, from math.vectors, which are optimized the same:
l1-norm ( k -- x )

l2-norm ( k -- x )

l-infinity-norm ( k -- x )

p-norm ( k p -- x )