emmy.matrix — org.mentat/emmy 0.31.0

This namespace contains an implementation of a [[Matrix]] datatype and various operations for creating and working with [[Matrix]] instances.

emmy.matrix also extends many Emmy generic operations to the [[Matrix]] datatype.

*careful-conversion* clj/s

Set this dynamic variable to false to allow s->m to operate on structures for which (* ls ms rs) does NOT yield a numerical value.

->structure clj/s

(->structure m)

(->structure m outer-orientation inner-orientation t?)

Returns a structure generated by converting m into a nested structure with the supplied outer-orientation and inner-orientation.

If t? is true, the columns of m will form the inner tuples. If t? is false, the rows of m will form the inner tuples.

By default, if you supply a single argument (the matrix m), a matrix turns into a single outer ::s/down of inner columns represented as ::up structures.

antisymmetric? clj/s

(antisymmetric? M)

Returns true if the supplied matrix M is equal to the negation of its own transpose (i.e., antisymmetric), false otherwise.

as-matrix clj/s

(as-matrix F)

Any one argument function of a structure can be seen as a matrix. This is only useful if the function has a linear multiplier (e.g. derivative)

by-cols clj/s

(by-cols & cols)

Returns a matrix whose columns consist of the supplied sequence of cols. These all must be the same length.

Variadic equivalent to by-cols*.

by-cols* clj/s

(by-cols* cols)

Returns a matrix whose columns consist of the supplied sequence of cols. These all must be the same length.

for a variadic equivalent, see by-cols.

by-rows clj/s

(by-rows & rows)

Returns a matrix whose rows consist of the supplied sequence of rows. These all must be the same length.

Variadic equivalent to by-rows*.

by-rows* clj/s

(by-rows* rows)

Returns a matrix whose rows consist of the supplied sequence of rows. These all must be the same length.

for a variadic equivalent, see by-rows.

characteristic-polynomial clj/s

(characteristic-polynomial m)

(characteristic-polynomial m x)

Returns the characteristic polynomial of the square matrix m.

If only m is supplied, returns a [[polynomial/Polynomial]] instance representing the matrix m's characteristic polynomial.

If x is supplied, returns the value of the characteristic polynomial of m evaluated at x.

Typically x will be a symbolic variable, but if you wanted to get the value of the characteristic polynomial at some particular numerical point x you could pass that too.

classical-adjoint-formula clj/s

(classical-adjoint-formula add sub mul div zero?)

Given coefficient procedures add, sub, mul and zero?, returns a procedure that efficiently computes the inverse of the supplied square matrix m.

classical-adjoint-formula is useful for generating fast type-specific matrix inversion routines. See invert for a default using generic arithmetic.

cofactors clj/s

(cofactors m)

Returns the matrix of cofactors of the supplied square matrix m.

column clj/s

(column & xs)

Returns a column matrix populated by the supplied xs. Variadic equivalent to column*.

column* clj/s

(column* xs)

Returns a column matrix populated by the supplied xs. For a variadic equivalent, see column.

column-matrix->up clj/s

(column-matrix->up m)

Returns the single column from the supplied column matrix as an up. Errors if some other type is supplied.

column-matrix->vector clj/s

(column-matrix->vector m)

Returns the single column from the supplied column matrix as a vector. Errors if some other type is supplied.

column? clj/s

(column? m)

Returns true if m is a matrix with a single column (a 'column matrix'), false otherwise.

cramers-rule clj/s

(cramers-rule add sub mul div zero?)

Given coefficient procedures add, sub, mul, div and zero?, returns a procedure that efficiently computes the solution to an inhomogeneous system of linear equations, A*x=b, where the matrix A and the column matrix b are given. The returned procedure returns the column matrix x.

Unlike LU decomposition, Cramer's rule generalizes to symbolic solutions.

cramers-rule is useful for generating fast type-specific linear equation solvers. See solve for a default using generic arithmetic.

determinant clj/s

(determinant m)

Returns the determinant of the supplied square matrix m.

Generic operations are used, so this works on symbolic square matrices.

diagonal clj/s

(diagonal m)

Returns the diagonal of the supplied matrix m as an up structure. Errors if a type other than a diagonal matrix is supplied.

diagonal? clj/s

(diagonal? m)

Returns true if m is a diagonal matrix (i.e., a square matrix where every non-diagonal element is zero), false otherwise.

dimension clj/s

(dimension m)

Returns the 'dimension', i.e., the number of rows & columns, of the supplied square matrix. Errors if some other type is supplied.

down->row-matrix clj/s

(down->row-matrix v)

Returns a row matrix with the contents of the supplied down structure. Errors if any other type is provided.

fmap clj/s

(fmap f m)

Maps f over the elements of the matrix m returning a new matrix of the same dimensions as m.

fmap-indexed clj/s

(fmap-indexed f m)

Maps f over three arguments:

• each element of the matrix m
• its row i
• its column j

and returns a new matrix of the same dimensions as m.

general-determinant clj/s

(general-determinant add sub mul zero?)

Given coefficient procedures add, sub, mul and zero?, returns a procedure that efficiently computes the determinant of the supplied square matrix m.

general-determinant is useful for generating fast type-specific determinant routines. See determinant for a default using generic arithmetic.

generate clj/s

(generate n f)

(generate r c f)

Returns a matrix with r rows and c columns, whose entries are generated by the supplied function f.

If you only supply one dimension n the returned matrix will be square.

The entry in the ith row and j-th column is (f i j).

get-in clj/s

(get-in m is)

Like [[clojure.core/get-in]] for matrices, but obeying the scmutils convention: only one index is required to get an unboxed element from a column vector.

NOTE that this is perhaps an unprincipled exception...

I clj/s

(I n)

Return the identity matrix of order n.

identity-like clj/s

(identity-like M)

Return an identity matrix whose ones and zeros match the types of the supplied square matrix M. Errors if a non-square matrix M is supplied.

identity? clj/s

(identity? m)

Returns true if the supplied matrix m is an identity matrix, false otherwise.

invert clj/s

(invert A)

Returns the inverse of the supplied square matrix m.

literal-column-matrix clj/s

(literal-column-matrix sym nrows)

Returns a column matrix of nrows symbolic entries, each prefixed by the supplied symbol sym.

For example:

(= (literal-column-matrix 'x 3)
   (by-cols ['x↑0 'x↑1 'x↑2]))

literal-matrix clj/s

(literal-matrix sym nrows)

(literal-matrix sym nrows ncols)

Generates a nrows x ncols matrix of symbolic entries, each prefixed by the supplied symbol sym.

If ncols (the third argument) is not supplied, returns a square matrix of size nrows x nrows.

NOTE: The symbols in the returned matrix record their Einstein-notation path into the structure that this matrix represents; a down of up columns. This means that the returned indices embedded in the symbols look flipped, ji vs ij.

For example:

(= (literal-matrix 'x 2 2)
   (by-rows ['x_0↑0 'x_1↑0]
            ['x_0↑1 'x_1↑1]))

literal-row-matrix clj/s

(literal-row-matrix sym ncols)

Returns a row matrix of ncols symbolic entries, each prefixed by the supplied symbol sym.

For example:

(= (literal-row-matrix 'x 3)
   (by-rows ['x_0 'x_1 'x_2]))

m->s clj/s

(m->s ls m rs)

Convert the matrix m into a structure S, guided by the requirement that (* ls S rs) should be a scalar.

make-diagonal clj/s

(make-diagonal v)

(make-diagonal n x)

Given a single (sequential) argument v, returns the diagonal matrix of order (count v) with the elements of the sequence v along the diagonal.

Given two arguments n and some constant x, returns a diagonal n by n matrix with x in every entry of the diagonal.

(make-diagonal <n> 1) is equivalent to (I n).

make-zero clj/s

(make-zero n)

(make-zero m n)

Return a zero-valued matrix of m rows and n columns (nXn if only n is supplied).

matrix->vector clj/s

(matrix->vector m)

If m is already a vector, acts as identity. Else, returns the matrix as a vector of rows (or throws if neither of these types is passed).

matrix? clj/s

(matrix? m)

Returns true if the supplied m is an instance of [[Matrix]], false otherwise.

nth-col clj/s

(nth-col m n)

Returns the n-th column of the supplied matrix m as an up structure.

nth-row clj/s

(nth-row m n)

Returns the n-th row of the supplied matrix m as a down structure.

num-cols clj/s

(num-cols m)

Returns the number of columns of the supplied matrix m. Throws if a non-matrix is supplied.

num-rows clj/s

(num-rows m)

Returns the number of rows of the supplied matrix m. Throws if a non-matrix is supplied.

row clj/s

(row & xs)

Returns a row matrix populated by the supplied xs. Variadic equivalent to row*.

row* clj/s

(row* xs)

Returns a row matrix populated by the supplied xs. For a variadic equivalent, see row.

row-matrix->down clj/s

(row-matrix->down m)

Returns the single row from the supplied row matrix as a down. Errors if some other type is supplied.

row-matrix->vector clj/s

(row-matrix->vector m)

Returns the single row from the supplied row matrix as a vector. Errors if some other type is supplied.

row? clj/s

(row? m)

Returns true if m is a matrix with a single row (a 'row matrix'), false otherwise.

rsolve clj/s

(rsolve b A)

Generalization of solve that can handle up and down structures, as well as row and column matrices.

Given row or down values for b, A is appropriately transposed before solving.

s->m clj/s

(s->m ms rs)

(s->m ls ms rs)

Convert the structure ms, which would be a scalar if the (compatible) multiplication (* ls ms rs) were performed, to a matrix.

s:divide-by-structure clj/s

(s:divide-by-structure rv s)

s:inverse clj/s

(s:inverse ms rs)

(s:inverse ls ms rs)

s:invert clj/s

(s:invert s)

Given some 2-tensor s (a 'square' nested structure), returns a structure that represents the multiplicative inverse of the supplied structure. The inner and outer structure orientations of (s:invert s) are the SAME as s.

If s is an up-of-downs or down-of-ups, (g/* s (s:invert s)) and (g/* (s:invert s) s) will evaluate to an identity-matrix-shaped up-of-downs or down-of-ups.

If s is an up-of-ups or down-of-downs, multiplying s (s:invert s) will result in a scalar, as both structures collapse.

NOTE: I DO NOT yet understand the meaning of this scalar! If you do, please open a pull request and explain it here.

s:solve-linear-left clj/s

(s:solve-linear-left M product)

s:solve-linear-right clj/s

(s:solve-linear-right product M)

s:transpose clj/s

(s:transpose ms rs)

(s:transpose ls ms rs)

Given structural inputs ls (optional), ms and rs, constrained such that (* ls ms rs) returns a numerical quantity, returns a result such that the following relationship remains true:

(* <ls| (* ms |rs>)) = (* <rs| (* (s:transpose ms) |ls>))

For example:

(let [ls (s/up 1 2)
    ms (s/up (s/down 1 2) (s/down 3 4))
    rs (s/down 1 2)]
(g/* ls (g/* ms rs))
;;=> 27

(g/* rs (g/* (s:transpose ls ms rs) ls))
;;=> 27
)

ls is optional. If ls is not supplied, a compatible shape is generated internally.

s:transpose-orientation clj/s

(s:transpose-orientation s)

Given some 2 tensor s, returns a structure with elements 'transposed' by swapping the inner and outer orientations and dimensions, like a matrix transpose.

Orientations are only flipped if they are different in the input. If the inner and outer orientations of s are the same, the returned structure has this identical orientation.

For example:

;; opposite orientation gets flipped:
(s:transpose-orientation (s/up (s/down 1 2 3) (s/down 4 5 6)))
;;=> (down (up 1 4) (up 2 5) (up 3 6))

;; same orientation stays the same:
(s:transpose-orientation (s/down (s/down 1 2 3) (s/down 4 5 6)))
;;=> (down (down 1 4) (down 2 5) (down 3 6))

See structure/two-tensor? for more detail on 2 tensors.

NOTE: In scmutils, this function is called s:transpose2.

seq-> clj/s

(seq-> xs)

Convert a sequence xs (typically, of function arguments) to an up-structure.

Any matrix present in the argument list will be converted to row of columns via ->structure.

solve clj/s

(solve A b)

Given a matrix A and a column matrix b, computes the solution to an inhomogeneous system of linear equations, A*x=b, where the matrix A and the column matrix b are given.

Returns the column matrix x.

Unlike LU decomposition, Cramer's rule generalizes to symbolic solutions.

some clj/s

(some f m)

Returns true if f is true for some element of the matrix m, false otherwise. (Also works on arbitrary nested sequences.)

square? clj/s

(square? m)

Returns true if m is a square matrix, false otherwise.

structure->matrix clj/s

(structure->matrix s)

Given some 2-tensor-shaped structure s, returns the corresponding matrix.

The outer orientation is ignored; If the inner structures are up, they're treated as columns. Inner down structures are treated as rows.

submatrix clj/s

(submatrix x lowrow hirow lowcol hicol)

Returns the submatrix of the matrix (or matrix-like structure) s generated by taking

• rows from lowrow -> hirow (inclusive)
• columns from lowcol -> hicol (inclusive)

symmetric? clj/s

(symmetric? M)

Returns true if the supplied matrix M is equal to its own transpose (i.e., symmetric), false otherwise.

trace clj/s

(trace m)

Returns the trace (the sum of diagonal elements) of the square matrix m.

Generic operations are used, so this works on symbolic square matrices.

transpose clj/s

(transpose m)

Returns the transpose of the matrix m. The transpose is the original matrix, with rows and columns swapped.

two-tensor-> clj/s

(two-tensor-> s cont)

Converts the square structure s into a matrix, and calls the supplied continuation cont with

• the generated matrix
• a function which will restore a matrix to a structure with the same inner and outer orientations as s

Returns the result of the continuation call.

two-tensor-operation clj/s

(two-tensor-operation s f)

Applies matrix operation f to square structure s and returns a structure of the same type as the supplied structure.

up->column-matrix clj/s

(up->column-matrix v)

Returns a column matrix with the contents of the supplied up structure. Errors if any other type is provided.

with-substituted-row clj/s

(with-substituted-row m i v)

Returns a new matrix of identical shape to m, with the vector v substituted for the ith row.

without clj/s

(without m i j)

Returns the matrix formed by deleting the i-th row and j-th column of the given matrix m.

This is also called the 'minor' of m.