Linear algebra API proposal

Namespace: clojure.core.matrix.linear

norm

(norm x)

(norm x p)

Computes norm of matrix or vector X. p argument specifies p norm.
By default calculates 2 norm for vector and Frobenius norm for matrix.

Special cases of p argument:
Double/POSITIVE_INFINITY - Infinity norm

Intended usage: (let [n (norm v 1)] ....)
                (let [n (norm v Double/POSITIVE_INFINITY)] ....)
                (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.
If :compact parameter is specified in options map, compact versions of matrices are returned.

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) (svd m options)

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 vector whose elements are the singular values of the original matrix
    - V* is an unitary matrix

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

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

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 :rA :iA] such that:

      M = Q.A.Q⁻¹

   Where:
     - Q is a matrix where each column is the ith normalised eigenvector of M
     - rA is a vector whose elements are the real numbers of eigenvalues.
     - iA is a vector whose elements are the imaginary units of eigenvalues.
     - Q⁻¹ is the inverse of Q

If :return parameter is specified in options map, it returns only specified keys.
if :symmetric parameter is true in options map, symmetric eigenvalue decomposition will be performed.

Intended usage: (let [{:keys [Q rA iA]} (eigen M)] ....)
                (let [{:keys [Q rA iA]} (eigen M {:symmetric true)] ....)
                (let [{:keys [Q rA]} (eigen M {:return [:Q :rA]})] ....)

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)] ....)