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-decomposition

(qr-decomposition m)

(qr-decomposition m r)

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 keys are passed in r parameter, returns only specified keys

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

cholesky-decomposition

(cholesky-decomposition m)

(cholesky-decomposition m r)

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 keys are passed in r parameter, returns only specified keys

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

lu-decomposition

(lu-decomposition 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-decomposition A)] ....)

sv-decomposition

(sv-decomposition 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*]} (sv-decomposition M)] ....)

eigen-decomposition

(eigen-decomposition m)

(eigen-decomposition m r)

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 keys are passed in r parameter, returns only specified keys


Intended usage: (let [{:keys [Q A Qinv]} (eigen-decomposition M)] ....)
                (let [{:keys [A]} (eigen-decomposition M [: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)] ....)