# LispKit Math Matrix

Library `(lispkit math matrix)` provides abstractions for representing vectors, matrices and for performing vector and matrix arithmetics. A matrix is a rectangular array of numbers. The library supports common matrix operations such as matrix addition, subtraction, and multiplication. There are operations to create matrices and to manipulate matrix objects. Furthermore, there is support to compute matrix determinants and to transpose and invert matrices. Matrices can be transformed into reduced row echelon form and matrix ranks can be determined.

matrix-type-tag [constant]

Symbol representing the `matrix` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all matrix objects.

(make-matrix m n) [procedure]

Returns a new matrix with m rows and n columns.

(matrix rows) [procedure]
(matrix row0 row1 …)

Returns a new matrix consisting of the given rows. Either rows is a list of list or numbers, or it is a vector of vectors of numbers. Instead of specifying one rows argument, it is also possible to provide the rows row0, row1, etc. as individual arguments to procedure `matrix`.

    (display (matrix->string
               (matrix '(1 2 3) '(4 5 6))))
    ⇒  ⎛1 2 3⎞
       ⎝4 5 6⎠

(identity-matrix n) [procedure]

Returns a new identity matrix with `n` rows and columns.

    (display (matrix->string
               (identity-matrix 3)))
    ⇒  ⎛1 0 0⎞
       ⎜0 1 0⎟
       ⎝0 0 1⎠

(matrix-copy matrix) [procedure]

Returns a copy of matrix.

(matrix-eliminate matrix i j) [procedure]

Returns a copy of matrix with row i and column j removed.

(matrix-normalize obj) [procedure]

Returns a normalized version of obj, representing 1*1 matrices and vectors of length 1 as a number, and m*1 and 1*n matrices as a vector.

(matrix? obj) [procedure]

Returns `#t` if obj is a matrix object, otherwise `#f` is returned.

(matrix-vector? obj) [procedure]

Returns `#t` if obj is a vector of numbers.

(matrix-zero? matrix) [procedure]

Returns `#t` if matrix is a zero matrix, i.e. all its elements are zero.

(matrix-square? matrix) [procedure]

Returns `#t` if matrix is a square matrix, i.e. it has size n*n.

(matrix-identity? matrix) [procedure]

Returns `#t` if matrix is an identity matrix, i.e. it has `1` at the positions (i, i) and all other elements are zero.

(matrix-symmetric? matrix) [procedure]

Returns `#t` if matrix is symmetric, i.e. matrix is equal to its transposed matrix.

(matrix-dimensions? matrix m n) [procedure]

Returns `#t` if matrix is a matrix of the given dimensions. m is the number of rows, n is the number of columns.

(matrix=? m0 m1 …) [procedure]

Returns `#t` if all matrices m0, m1, … are equal to each other, otherwise `#f` is returned.

(matrix-size matrix) [procedure]

Returns the size of matrix as a pair whose car is the number of rows and cdr is the number of columns.

(matrix-rows matrix) [procedure]

Returns the number of rows of matrix.

(matrix-columns matrix) [procedure]

Returns the number of columns of matrix.

(matrix-row matrix i) [procedure]

Returns row i of matrix as a vector.

(matrix-column matrix j) [procedure]

Returns column j of matrix as a vector.

(matrix->vector matrix) [procedure]

Returns matrix as a vector of vectors.

(matrix-row->list matrix i) [procedure]

Returns row i of matrix as a list.

(matrix-column->list matrix j) [procedure]

Returns column j of matrix as a list.

(matrix->list matrix) [procedure]

Returns matrix as a list of lists.

(matrix-column-swap! matrix j k) [procedure]

Swaps columns j and k of matrix.

(matrix-row-swap! matrix i k) [procedure]

Swaps rows `i` and `k` of `matrix`.

(matrix-ref matrix i j) [procedure]

Returns the j-th element of the i-th row of matrix.

(matrix-set! matrix i j x) [procedure]

Sets the j-th element of the i-th row of matrix to x.

(matrix-for-each f matrix) [procedure]

Invokes f for every element of matrix. f is a procedure taking three arguments: the row, the column, and the element at this position. The traversal order is by row, from left to right.

(matrix-fold f z matrix) [procedure]

Folds the matrix elements row by row from left to right, invoking f with the accumulator, the row, the column and the element at this position.

(matrix-transpose matrix) [procedure]

Returns matrix in transposed form.

    (define m (matrix '(1 2 3) '(4 5 6)))
    (display (matrix->string
               (matrix-transpose m)))
    ⇒  ⎛1 4⎞
       ⎜2 5⎟
       ⎝3 6⎠

(matrix-sum! matrix m0 …) [procedure]

Sums up matrix and all matrices m0, … storing the result in matrix.

(matrix-difference! matrix m0 …) [procedure]

Subtracts the matrices m0, … from matrix, storing the result in matrix.

(matrix-add m0 m1 …) [procedure]

Returns the sum of matrices or vectors m0, m1, …

(matrix-subtract m0 m1 …) [procedure]

Returns the difference of matrix or vector m0 and the matrices or vectors m1, … This procedure also supports vector differences.

(matrix-mult m0 m1 …) [procedure]

Returns the matrix product m0 * m1 * … or the dot product if m0, m1, … are vectors.

(matrix-minor matrix i j) [procedure]

Returns a minor of matrix by removing row i and column j and computing the determinant of the remaining matrix. matrix needs to be a square matrix.

(matrix-cofactor matrix i j) [procedure]

Returns a minor of matrix by removing row i and column j and computing the determinant of the remaining matrix. The result is negative if the sum of i and j is odd. matrix needs to be a square matrix.

(matrix-determinant matrix) [procedure]

Returns the determinant of matrix. matrix needs to be a square matrix.

(matrix-inverse matrix) [procedure]

Returns the inverse of matrix if it exists. If it does not exist, `#f` is being returned. matrix needs to be a square matrix.

    (define a (matrix '(1 2 3) '(0 1 0) '(1 1 0)))
    (define b (matrix-inverse a))
    (matrix-identity? (matrix-mult a b))  ⇒  #t

(matrix-row-echelon! matrix) [procedure]

Returns the reduced row echelon matrix of `matrix` by continuously applying Gaussian Elimination.

    (define m (matrix '(5 -6 -7   7)
                      '(6 -4 10 -34)
                      '(2  4 -3  29)))
    (matrix-row-echelon! m)
    (display (matrix->string m))
    ⇒  ⎛1 0 0  2⎞
       ⎜0 1 0  4⎟
       ⎝0 0 1 -3⎠

(matrix-rank matrix) [procedure]

Returns the rank of matrix. The rank of matrix is the dimension of the vector space generated by its columns. This corresponds to the maximal number of linearly independent columns of matrix.

(matrix->string matrix) [procedure]
(matrix->string matrix len)
(matrix->string matrix len prec)
(matrix->string matrix len prec noexp)

Returns a multi-line string representation of matrix. The elements x of matrix are converted into a string by invoking `(number->string x len prec noexp)`.