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.
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.
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.
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 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.
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? M)Returns true if the supplied matrix M is equal to the negation of its own
transpose (i.e., antisymmetric), false otherwise.
Returns true if the supplied matrix `M` is equal to the negation of its own transpose (i.e., antisymmetric), false otherwise.
(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)
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 & 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*.
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* 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.
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 & 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*.
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* 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.
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 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.
Returns the [characteristic polynomial](https://en.wikipedia.org/wiki/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 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.
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 m)Returns the matrix of cofactors of the supplied square matrix m.
Returns the matrix of cofactors of the supplied square matrix `m`.
(column & xs)Returns a column matrix populated by the supplied xs. Variadic equivalent
to column*.
Returns a column matrix populated by the supplied `xs`. Variadic equivalent to [[column*]].
(column* xs)Returns a column matrix populated by the supplied xs. For a variadic equivalent,
see column.
Returns a column matrix populated by the supplied `xs`. For a variadic equivalent, see [[column]].
(column-matrix->up m)Returns the single column from the supplied column matrix as an up. Errors if
some other type is supplied.
Returns the single column from the supplied column matrix as an `up`. Errors if some other type is supplied.
(column-matrix->vector m)Returns the single column from the supplied column matrix as a vector. Errors if some other type is supplied.
Returns the single column from the supplied column matrix as a vector. Errors if some other type is supplied.
(column? m)Returns true if m is a matrix with a single column (a 'column matrix'),
false otherwise.
Returns true if `m` is a matrix with a single column (a 'column matrix'), false otherwise.
(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.
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 m)Returns the determinant of the supplied square matrix m.
Generic operations are used, so this works on symbolic square matrices.
Returns the determinant of the supplied square matrix `m`. Generic operations are used, so this works on symbolic square matrices.
(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.
Returns the diagonal of the supplied matrix `m` as an up structure. Errors if a type other than a diagonal matrix is supplied.
(diagonal? m)Returns true if m is a diagonal matrix (i.e., a square matrix where every
non-diagonal element is zero), false otherwise.
Returns true if `m` is a diagonal matrix (i.e., a square matrix where every non-diagonal element is zero), false otherwise.
(dimension m)Returns the 'dimension', i.e., the number of rows & columns, of the supplied square matrix. Errors if some other type is supplied.
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 v)Returns a row matrix with the contents of the supplied down structure.
Errors if any other type is provided.
Returns a row matrix with the contents of the supplied `down` structure. Errors if any other type is provided.
(fmap f m)Maps f over the elements of the matrix m returning a new matrix of the same
dimensions as m.
Maps `f` over the elements of the matrix `m` returning a new matrix of the same dimensions as `m`.
(fmap-indexed f m)Maps f over three arguments:
mijand returns a new matrix of the same dimensions as 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 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.
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 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).
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 `i`th row and `j`-th column is `(f i j)`.
(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...
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 n)Return the identity matrix of order n.
Return the identity matrix of order `n`.
(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.
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? m)Returns true if the supplied matrix m is an identity matrix, false
otherwise.
Returns true if the supplied matrix `m` is an identity matrix, false otherwise.
(invert A)Returns the inverse of the supplied square matrix m.
Returns the inverse of the supplied square matrix `m`.
(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]))
Returns a column matrix of `nrows` symbolic entries, each prefixed by the supplied symbol `sym`. For example: ```clojure (= (literal-column-matrix 'x 3) (by-cols ['x↑0 'x↑1 'x↑2])) ```
(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]))
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:
```clojure
(= (literal-matrix 'x 2 2)
(by-rows ['x_0↑0 'x_1↑0]
['x_0↑1 'x_1↑1]))
```(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]))
Returns a row matrix of `ncols` symbolic entries, each prefixed by the supplied symbol `sym`. For example: ```clojure (= (literal-row-matrix 'x 3) (by-rows ['x_0 'x_1 'x_2])) ```
(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.
Convert the matrix `m` into a structure `S`, guided by the requirement that `(* ls S rs)` should be a scalar.
(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).
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 n)(make-zero m n)Return a zero-valued matrix of m rows and n columns (nXn if only n is
supplied).
Return a zero-valued matrix of `m` rows and `n` columns (`nXn` if only `n` is supplied).
(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).
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? m)Returns true if the supplied m is an instance of [[Matrix]], false
otherwise.
Returns true if the supplied `m` is an instance of [[Matrix]], false otherwise.
(nth-col m n)Returns the n-th column of the supplied matrix m as an up structure.
Returns the `n`-th column of the supplied matrix `m` as an `up` structure.
(nth-row m n)Returns the n-th row of the supplied matrix m as a down structure.
Returns the `n`-th row of the supplied matrix `m` as a `down` structure.
(num-cols m)Returns the number of columns of the supplied matrix m. Throws if a
non-matrix is supplied.
Returns the number of columns of the supplied matrix `m`. Throws if a non-matrix is supplied.
(num-rows m)Returns the number of rows of the supplied matrix m. Throws if a
non-matrix is supplied.
Returns the number of rows of the supplied matrix `m`. Throws if a non-matrix is supplied.
(row & xs)Returns a row matrix populated by the supplied xs. Variadic equivalent
to row*.
Returns a row matrix populated by the supplied `xs`. Variadic equivalent to [[row*]].
(row* xs)Returns a row matrix populated by the supplied xs. For a variadic equivalent,
see row.
Returns a row matrix populated by the supplied `xs`. For a variadic equivalent, see [[row]].
(row-matrix->down m)Returns the single row from the supplied row matrix as a down. Errors if some
other type is supplied.
Returns the single row from the supplied row matrix as a `down`. Errors if some other type is supplied.
(row-matrix->vector m)Returns the single row from the supplied row matrix as a vector. Errors if some other type is supplied.
Returns the single row from the supplied row matrix as a vector. Errors if some other type is supplied.
(row? m)Returns true if m is a matrix with a single row (a 'row matrix'), false
otherwise.
Returns true if `m` is a matrix with a single row (a 'row matrix'), false otherwise.
(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.
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 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.
Convert the structure `ms`, which would be a scalar if the (compatible) multiplication `(* ls ms rs)` were performed, to a matrix.
(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.
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: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.
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:
```clj
(* <ls| (* ms |rs>)) = (* <rs| (* (s:transpose ms) |ls>))
```
For example:
```clj
(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 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.
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: ```clj ;; 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-> 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.
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 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.
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 f m)Returns true if f is true for some element of the matrix m, false
otherwise. (Also works on arbitrary nested sequences.)
Returns true if `f` is true for some element of the matrix `m`, false otherwise. (Also works on arbitrary nested sequences.)
(square? m)Returns true if m is a square matrix, false otherwise.
Returns true if `m` is a square matrix, false otherwise.
(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.
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 x lowrow hirow lowcol hicol)Returns the submatrix of the matrix (or matrix-like structure) s generated by
taking
lowrow -> hirow (inclusive)lowcol -> hicol (inclusive)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? M)Returns true if the supplied matrix M is equal to its own transpose (i.e.,
symmetric), false otherwise.
Returns true if the supplied matrix `M` is equal to its own transpose (i.e., symmetric), false otherwise.
(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.
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 m)Returns the transpose of the matrix m. The transpose is the original matrix,
with rows and columns swapped.
Returns the transpose of the matrix `m`. The transpose is the original matrix, with rows and columns swapped.
(two-tensor-> s cont)Converts the square structure s into a matrix, and calls the supplied
continuation cont with
Returns the result of the continuation call.
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 s f)Applies matrix operation f to square structure s and returns a structure of
the same type as the supplied structure.
Applies matrix operation `f` to square structure `s` and returns a structure of the same type as the supplied structure.
(up->column-matrix v)Returns a column matrix with the contents of the supplied up structure.
Errors if any other type is provided.
Returns a column matrix with the contents of the supplied `up` structure. Errors if any other type is provided.
(with-substituted-row m i v)Returns a new matrix of identical shape to m, with the vector v substituted
for the ith row.
Returns a new matrix of identical shape to `m`, with the vector `v` substituted for the `i`th row.
(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.
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.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |