@c Copyright (C) 1996-2012 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Linear Algebra
@chapter Linear Algebra

This chapter documents the linear algebra functions of Octave.
Reference material for many of these functions may be found in
Golub and Van Loan, @cite{Matrix Computations, 2nd Ed.}, Johns Hopkins,
1989, and in the @cite{@sc{lapack} Users' Guide}, SIAM, 1992.

@menu
* Techniques Used for Linear Algebra::
* Basic Matrix Functions::
* Matrix Factorizations::
* Functions of a Matrix::
* Specialized Solvers::
@end menu

@node Techniques Used for Linear Algebra
@section Techniques Used for Linear Algebra

Octave includes a polymorphic solver, that selects an appropriate
matrix factorization depending on the properties of the matrix itself. 
Generally, the cost of determining the matrix type is small relative to 
the cost of factorizing the matrix itself, but in any case the matrix 
type is cached once it is calculated, so that it is not re-determined 
each time it is used in a linear equation.

The selection tree for how the linear equation is solve or a matrix
inverse is form is given by

@enumerate 1
@item If the matrix is upper or lower triangular sparse a forward or
backward substitution using the @sc{lapack} xTRTRS function, and goto 4.

@c Permuted triangular matrices currently disabled in the code
@c
@c @item If the matrix is a upper triangular matrix with column permutations
@c or lower triangular matrix with row permutations, perform a forward or
@c backward substitution, and goto 5.

@item If the matrix is square, Hermitian with a real positive diagonal,
attempt Cholesky@tie{}factorization using the @sc{lapack} xPOTRF function.

@item If the Cholesky@tie{}factorization failed or the matrix is not
Hermitian with a real positive diagonal, and the matrix is square, factorize 
using the @sc{lapack} xGETRF function.

@item If the matrix is not square, or any of the previous solvers flags
a singular or near singular matrix, find a least squares solution using
the @sc{lapack} xGELSD function.
@end enumerate

The user can force the type of the matrix with the @code{matrix_type}
function.  This overcomes the cost of discovering the type of the matrix.
However, it should be noted that identifying the type of the matrix incorrectly
will lead to unpredictable results, and so @code{matrix_type} should be
used with care.

It should be noted that the test for whether a matrix is a candidate for
Cholesky@tie{}factorization, performed above and by the @code{matrix_type}
function, does not give a certainty that the matrix is
Hermitian.  However, the attempt to factorize the matrix will quickly
flag a non-Hermitian matrix.

@node Basic Matrix Functions
@section Basic Matrix Functions

@DOCSTRING(balance)

@DOCSTRING(cond)

@DOCSTRING(det)

@DOCSTRING(eig)

@DOCSTRING(givens)

@DOCSTRING(planerot)

@DOCSTRING(inv)

@DOCSTRING(linsolve)

@DOCSTRING(matrix_type)

@DOCSTRING(norm)

@DOCSTRING(null)

@DOCSTRING(orth)

@DOCSTRING(mgorth)

@DOCSTRING(pinv)

@DOCSTRING(rank)

@DOCSTRING(rcond)

@DOCSTRING(trace)

@DOCSTRING(rref)

@node Matrix Factorizations
@section Matrix Factorizations

@DOCSTRING(chol)

@DOCSTRING(cholinv)

@DOCSTRING(chol2inv)

@DOCSTRING(cholupdate)

@DOCSTRING(cholinsert)

@DOCSTRING(choldelete)

@DOCSTRING(cholshift)

@DOCSTRING(hess)

@DOCSTRING(lu)

@DOCSTRING(luupdate)

@DOCSTRING(qr)

@DOCSTRING(qrupdate)

@DOCSTRING(qrinsert)

@DOCSTRING(qrdelete)

@DOCSTRING(qrshift)

@DOCSTRING(qz)

@DOCSTRING(qzhess)

@DOCSTRING(schur)

@DOCSTRING(rsf2csf)

@DOCSTRING(subspace)

@DOCSTRING(svd)

@DOCSTRING(svd_driver)

@c FIXME -- should there be a new section here?

@DOCSTRING(housh)

@DOCSTRING(krylov)

@node Functions of a Matrix
@section Functions of a Matrix

@DOCSTRING(expm)

@DOCSTRING(logm)

@DOCSTRING(sqrtm)

@DOCSTRING(kron)

@DOCSTRING(blkmm)

@DOCSTRING(syl)

@node Specialized Solvers
@section Specialized Solvers

@DOCSTRING(bicg)

@DOCSTRING(bicgstab)

@DOCSTRING(cgs)

@DOCSTRING(gmres)