Matrix operations - Factor Documentation (original) (raw)

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:
( m n element -- matrix )
( ... m n quot: ( ... -- ... elt ) -- ... matrix )
( ... m n quot: ( ... m' n' -- ... elt ) -- ... matrix )

( m n -- matrix )
( n -- matrix )
( diagonal-seq -- matrix )
( diagonal-seq -- matrix )
( n -- matrix )
( m n k -- matrix )
( m n k z -- matrix )

( dim -- coordinates )
( desc -- matrix )
( desc -- matrix )
( object m n -- matrix )
( object m n -- matrix )
( 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 )