@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@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 @cite{@sc{Lapack} Users' Guide}, SIAM, 1992.

@menu
* Techniques used for Linear Algebra::
* Basic Matrix Functions::      
* Matrix Factorizations::       
* Functions of a Matrix::       
@end menu

@node Techniques used for Linear Algebra
@section Techniques used for Linear Algebra

Octave includes a poly-morphic 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 substition 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 factorization using the @sc{Lapack} xPOTRF function.

@item If the Cholesky 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} xGELSS 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 incorrectly identifying the type of the matrix
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 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(dmult)

@DOCSTRING(dot)

@DOCSTRING(eig)

@DOCSTRING(givens)

@DOCSTRING(inv)

@DOCSTRING(matrix_type)

@DOCSTRING(norm)

@DOCSTRING(null)

@DOCSTRING(orth)

@DOCSTRING(pinv)

@DOCSTRING(rank)

@DOCSTRING(trace)

@DOCSTRING(rref)

@node Matrix Factorizations
@section Matrix Factorizations

@DOCSTRING(chol)

@DOCSTRING(cholinv)

@DOCSTRING(chol2inv)

@DOCSTRING(hess)

@DOCSTRING(lu)

@DOCSTRING(qr)

@DOCSTRING(qz)

@DOCSTRING(qzhess)

@DOCSTRING(schur)

@DOCSTRING(svd)

@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(syl)