Linear algebra API proposal

Namespace: clojure.core.matrix.linear

norm

(norm x)

(norm x type)

Computes norm of matrix or vector X. Norm is specified by type parameter.
By default, calculates 2 norm for vectors and Frobenius norm for matrices. 

Norm types:
:fro - Frobenius norm
:inf - Infinity norm
:-inf
p norms are specified with a number

Intendend usage: (let [n (norm v 2)] ....)
                 (let [n (norm v :fro)] ....)
                 (let [n (norm v)] ....)

rank

(rank m)

Computes the rank of a matrix, i.e. the number of linearly independent rows

Intended usage: (let [r (rank m)] ....)

qr

(qr m)

(qr m options)

Computes QR decomposition. Returns a map containing matrices with the keys [:Q :R] such that:

        M = Q.R 

Where:
    - Q is an orthogonal matrix
    - R is an upper triangular matrix (= right triangular matrix)
If :return parameter is specified in options map, it returns only specified keys.

Intended usage: (let [{:keys [Q R]} (qr M)] ....)
                (let [{:keys [R]} (qr M {:return [:R]}) ....)

cholesky

(cholesky m)

(cholesky m options)

Computes the Cholesky decomposition of a hermitian, positive definite matrix.
Returns a map containing two matrices with the keys [:L :L*] such that
     
Such that:
      M = L.L*

Where
     - M must be a hermitian, positive definite matrix
     - L is a lower triangular matrix
     - L* is the conjugate transpose of L

If :return parameter is specified in options map, it returns only specified keys.

Intended usage: (let [{:keys [L L*]} (cholesky M)] ....)
                (let [{:keys [L*]} (cholesky M {:return [:L*]})] ....)

lu

(lu m)

Computes the LU(P) decomposition of a matrix with partial row pivoting.
Returns a map containing the keys [:L :U :P], such that:

       P.A = L.U
       
Where
     - L is a lower triangular matrix
     - U is an upper triangular matrix
     - P is a permutation matrix

Intended usage: (let [{:keys [L U P]} (lu A)] ....)

svd

(svd m)

Computes the Singular Value decomposition of a matrix.
Returns a map containing the keys [:U :S :V*] such that:
    M = U.S.V*

Where
    - U is an unitary matrix
    - S is a diagonal matrix whose elements are the singular values of the original matrix
    - V* is an unitary matrix

Intended usage: (let [{:keys [U S V*]} (svd M)] ....)

eigen

(eigen m)

(eigen m options)

Computes the Eigen decomposition of a diagonalisable matrix.
Returns a map containing matrices for each of the the keys [:Q :A :Qinv] such that:

      M = Q.A.Qinv

   Where:
     - Q is a matrix where each column is the ith normalised eigenvector of M
     - A is a diagonal matrix whose diagonal elements are the eigenvalues.
     - Qinv is the inverse of Q

If :return parameter is specified in options map, it returns only specified keys.


Intended usage: (let [{:keys [Q A Qinv]} (eigen M)] ....)
                (let [{:keys [A]} (eigen M {:return [:A]})] ....)

solve

(solve A B)

Solves a linear matrix equation, or system of linear scalar equations.

Where:
    - A is a square matrix containing the coefficients of the linear system
    - B is a vector containing the right-hand side of the linear system. 
If B is missing, it is taken as an identity matrix and returns inverse of A

Intended usage: (let [X (solve A B)] ....)

least-squares

(least-squares A B)

Computes least-squares solution to a linear matrix equation.

Intended usage: (let [X (least-squares A B)] ....)