\chapter{The LAPACK Interface (\module{cvxopt.lapack})}
\label{chap:lapack}

The module \module{cvxopt.lapack} includes functions for 
solving dense sets of linear equations, for the corresponding matrix 
factorizations (LU, Cholesky, $\mathrm{LDL^T}$),
for solving least-squares and least-norm problems, for QR 
factorization, for symmetric eigenvalue problems and for singular 
value decomposition.  

In this chapter we briefly describe the Python calling sequences.
For further details on the underlying LAPACK functions we refer to the 
LAPACK Users' Guide and manual pages.  

The BLAS conventional storage scheme of section~\ref{s-conventions} is 
used. As in the previous chapter, we omit from the function definitions
less important arguments that are useful for selecting submatrices. 
The complete definitions are documented in the docstrings in the 
source code.

\textbf{See also:}
\seelink{http://www.netlib.org/lapack/lug/lapack_lug.html}{LAPACK 
Users' Guide, Third Edition, SIAM, 1999}{}.


\section{General Linear Equations}
\begin{funcdesc}{gesv}{A, B\optional{, ipiv=None}}
Solves
\[ 
   A X = B,
\]
where \tm{A} and \tm{B} are real or complex matrices, with \tm{A}
square and nonsingular.  On exit, \var{B} is replaced by the solution.  
The arguments \var{A} and \var{B} must have the same type (\dtc\ or
\ztc).  
The optional argument \var{ipiv} is an integer matrix of length at 
least \tm{n}.  
If \var{ipiv} is provided, then \function{gesv()} solves the system, 
replaces \var{A} with its triangular factors, and returns the 
permutation matrix in \var{ipiv}.
If \var{ipiv} is not specified, then \function{gesv()} solves the
system but does not return the LU factorization and does not 
modify \var{A}.  
For example,
\begin{verbatim}
>>> gesv(A, B)
\end{verbatim}
solves the system without modifying \var{A} and returns the solution 
in \var{B}.
\begin{verbatim}
>>> gesv(A, B, ipiv)
\end{verbatim}
returns the solution in \var{B} and also returns the details of the 
LU factorization in \var{A} and \var{ipiv}.

Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{getrf}{A, ipiv}
LU factorization of a general, possibly rectangular, real or
complex matrix,  
\[
  A = PLU 
\]
where \tm{A} is \tm{m} by \tm{n}.
The argument \var{ipiv} is an integer matrix of length at least
\tm{\min\{m, n\}}.
On exit, the lower triangular part of \var{A} is replaced by \tm{L},
the upper triangular part by \tm{U}, and the permutation matrix is 
returned in \var{ipiv}.
Raises an \code{ArithmeticError} if the matrix is not full rank.
\end{funcdesc}

\begin{funcdesc}{getrs}{A, ipiv, B\optional{, trans='N'}}
Solves a general set of linear equations
\[
 AX=B \quad (\mathrm{trans} = \mathrm{'N'}), \qquad
 A^TX=B \quad (\mathrm{trans} = \mathrm{'T'}), \qquad 
 A^HX=B \quad (\mathrm{trans} = \mathrm{'C'}), 
\]
given the LU factorization computed by \function{gesv()} or 
\function{getrf()}.
On entry, \var{A} and \var{ipiv} must contain the factorization
as computed by \function{gesv()} or \function{getrf()}.  
On exit, \var{B} is overwritten with the solution. 
\var{B} must have the same type as \var{A}.
\end{funcdesc}

\begin{funcdesc}{getri}{A, ipiv}
Computes the inverse of a matrix.
On entry, \var{A} and \var{ipiv} must contain the factorization
as computed by \function{gesv()} or \function{getrf()}.  On exit, 
\var{A} contains the inverse.
\end{funcdesc}

In the following example we compute
\[
 x = (A^{-1} + A^{-T})b
\]
for randomly generated problem data, factoring the coefficient matrix 
once.
\begin{verbatim}
>>> from cvxopt.base import matrix, normal
>>> from cvxopt.lapack import gesv, getrs
>>> n = 10
>>> A = normal(n,n)
>>> b = normal(n)
>>> ipiv = matrix(0, (n,1))
>>> x = +b
>>> gesv(A, x, ipiv)               # x = A^{-1}*b 
>>> x2 = +b
>>> getrs(A, ipiv, x2, trans='T')  # x2 = A^{-T}*b
>>> x += x2
\end{verbatim}

Separate functions are provided for equations with band matrices.
\begin{funcdesc}{gbsv}{A, kl, B\optional{, ipiv=None}}
Solves
\[ 
   A X = B,
\]
where \tm{A} and \tm{B} are real or complex matrices, with \tm{A}
\tm{n} by \tm{n} and banded with \tm{\s{k}{l}} subdiagonals.  
The arguments \var{A} and \var{B} must have the same type (\dtc\ or
\ztc).  

The optional argument \var{ipiv} is an integer matrix of length at 
least \tm{n}.
If \var{ipiv} is provided, then \var{A} must have 
\tm{2\s{k}{l} + \s{k}{u} + 1} rows.  On entry the diagonals of \tm{A} are
stored in rows \tm{\s{k}{l} + 1} to 
\tm{2\s{k}{l} + \s{k}{u} +1} of the \var{A}, using
the BLAS format for general band matrices 
(see section~\ref{s-conventions}).
On exit, the factorization is returned in {\var A} and \var{ipiv}.

If \var{ipiv} is not provided, then \var{A} must have 
\tm{\s{k}{l} + \s{k}{u} + 1} rows.  
On entry the diagonals of \tm{A} are stored in the 
rows of \var{A}, following the standard format for general band matrices. 
In this case, \function{gbsv()} does not modify \var{A} on exit and does
not return the factorization.

On exit, \var{B} is replaced by the solution \tm{X}.  
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{gbtrf}{A, m, kl, ipiv}
LU factorization of a general \tm{m} by \tm{n} real or complex band 
matrix with \tm{\s{k}{l}} subdiagonals.
The matrix is stored using the BLAS format for general band matrices
(see section~\ref{s-conventions}), by providing the 
diagonals (stored as rows of a \tm{\s{k}{u} + \s{k}{l} + 1} by 
\tm{n} matrix),
the number of rows \tm{m}, and the number of subdiagonals \tm{\s{k}{l}}.
The argument \var{ipiv} is an integer matrix of length at least
\tm{\min\{m, n\}}.
On exit, \var{A} and \var{ipiv} contain the details of the factorization.
Raises an \code{ArithmeticError} if the matrix is not full rank.
\end{funcdesc}

\begin{funcdesc}{gbtrs}{A, kl, ipiv, B\optional{, trans='N'}}
Solves a set of linear equations 
\[
 AX=B \quad (\mathrm{trans} = \mathrm{'N'}), \qquad
 A^TX=B \quad (\mathrm{trans} = \mathrm{'T'}), \qquad 
 A^HX=B \quad (\mathrm{trans} = \mathrm{'C'}), 
\]
with \tm{A} a general band matrix with \tm{\s{k}{l}} subdiagonals, 
given the LU factorization computed by 
\function{gbsv()} or \function{gbtrf()}.
On entry, \var{A} and \var{ipiv} must contain the factorization
as computed by \function{gbsv()} or \function{gbtrf()}.  
On exit, \var{B} is overwritten with the solution. 
\var{B} must have the same type as \var{A}.
\end{funcdesc}

As an example, we solve a linear equation with
\[
 A = \left[ \begin{array}{cccc}
 1 & 2 & 0 & 0 \\
 3 & 4 & 5 & 0 \\
 6 & 7 & 8 & 9 \\
 0 & 10 & 11 & 12 
 \end{array}\right], \qquad  x = \left[\begin{array}{c} 1 \\ 1 \\ 1 \\ 1
 \end{array}\right].
\]
\begin{verbatim}
>>> from cvxopt.base import matrix
>>> from cvxopt.lapack import gbsv, gbtrf, gbtrs
>>> n, kl, ku = 4, 2, 1
>>> A = matrix([[0., 1., 3., 6.], [2., 4., 7., 10.], [5., 8., 11., 0.], [9., 12., 0., 0.]])
>>> x = matrix(1.0, (4,1))
>>> gbsv(A, kl, x)
>>> print x
[ 7.14e-02]
[ 4.64e-01]
[-2.14e-01]
[-1.07e-01]
\end{verbatim}
The code below illustrates how one can reuse the factorization returned
by \function{gbsv()}. 
\begin{verbatim}
>>> Ac = matrix(0.0, (2*kl+ku+1,n))
>>> Ac[kl:,:] = A
>>> ipiv = matrix(0, (n,1))
>>> x = matrix(1.0, (4,1))
>>> gbsv(Ac, kl, x, ipiv)                 # solves A*x = 1
>>> print x
[ 7.14e-02]
[ 4.64e-01]
[-2.14e-01]
[-1.07e-01]
>>> x = matrix(1.0, (4,1))
>>> gbtrs(Ac, kl, ipiv, x, trans='T')     # solve A^T*x = 1
>>> print x
[ 7.14e-02]
[ 2.38e-02]
[ 1.43e-01]
[-2.38e-02]
\end{verbatim}
An alternative method uses \function{gbtrf()} for the factorization.
\begin{verbatim}
>>> Ac[kl:,:] = A
>>> gbtrf(Ac, n, kl, ipiv)                 
>>> x = matrix(1.0, (4,1))
>>> gbtrs(Ac, kl, ipiv, x)                # solve A^T*x = 1
>>> print x                 
[ 7.14e-02]
[ 4.64e-01]
[-2.14e-01]
[-1.07e-01]
>>> x = matrix(1.0, (4,1))
>>> gbtrs(Ac, kl, ipiv, x, trans='T')     # solve A^T*x = 1
>>> print x
[ 7.14e-02]
[ 2.38e-02]
[ 1.43e-01]
[-2.38e-02]
\end{verbatim}

The following functions can be used for tridiagonal matrices. They use a 
simpler matrix format, that stores the diagonals in three separate 
vectors.

\begin{funcdesc}{gtsv}{dl, d, du, B)}
Solves
\[ 
   A X = B,
\]
where \tm{A} is an \tm{n} by \tm{n} tridiagonal matrix, 
with subdiagonal stored as a matrix \var{dl} of length \tm{n-1}, 
diagonal stored as a matrix \var{d} of length \tm{n}, and superdiagonal 
stored as a matrix \var{du} of length \tm{n-1}.  
The four arguments must have the same type (\dtc\ or \ztc).
On exit \var{dl}, \var{d}, \var{du} are overwritten with the details of 
the LU factorization of \tm{A}, and \var{B} is overwritten with the solution 
\tm{X}.  
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{gttrf}{dl, d, du, du2, ipiv}
LU factorization of an \tm{n} by \tm{n} tridiagonal matrix with
subdiagonal \tm{\s{d}{l}}, diagonal \tm{d} and superdiagonal \tm{\s{d}{u}}.
\var{dl}, \var{d} and \var{du} must have the same type.
\var{du2} is a matrix of length \tm{n-2}, and of the same type as 
\var{dl}.
\var{ipiv} is an \itc\ matrix of length \tm{n}.
On exit, the five arguments contain the details of the factorization.
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{pttrs}{dl, d, du, du2, ipiv, B\optional{, trans='N'}}
Solves a set of linear equations 
\[
 AX=B \quad (\mathrm{trans} = \mathrm{'N'}), \qquad
 A^TX=B \quad (\mathrm{trans} = \mathrm{'T'}), \qquad 
 A^HX=B \quad (\mathrm{trans} = \mathrm{'C'}), 
\]
where \tm{A} is an \tm{n} by \tm{n} tridiagonal matrix.
The arguments \var{dl}, \var{d}, \var{du}, \var{du2} and \var{ipiv}
contain the details of the LU factorization as returned by 
\function{gttrf()}.
On exit, \var{B} is overwritten with the solution \tm{X}. 
\var{B} must have the same type as \var{dl}.
\end{funcdesc}


\section{Positive Definite Linear Equations}
\begin{funcdesc}{posv}{A, B\optional{, uplo='L'}}
Solves
\[ 
   A X = B,
\]
where \tm{A} is a real symmetric or complex Hermitian positive 
definite matrix.
On exit, \var{B} is replaced by the solution, and \var{A} is 
overwritten with the Cholesky factor.
The matrices \var{A} and \var{B} must have the same type (\dtc\ or 
\ztc).
Raises an \code{ArithmeticError} if the matrix is not positive definite.
\end{funcdesc}

\begin{funcdesc}{potrf}{A\optional{, uplo='L'}}
Cholesky factorization 
\[
 A = LL^T \qquad \mbox{or} \qquad A = LL^H
\]
of a positive definite real symmetric or complex Hermitian matrix \tm{A}.  
On exit, the lower triangular part of \var{A} 
(if \var{uplo} is \code{'L'}) or the upper triangular part 
(if \var{uplo} is \code{'U'}) is overwritten with the Cholesky factor 
or its (conjugate) transpose.
Raises an \code{ArithmeticError} if the matrix is not positive definite.
\end{funcdesc}

\begin{funcdesc}{potrs}{A, B\optional{, uplo='L'}}
Solves a set of linear equations
\[
 AX=B
\]
with a positive definite real symmetric or complex Hermitian matrix,
given the Cholesky factorization computed by 
\function{posv()} or \function{potrf()}.
On entry, \var{A} contains the triangular factor, as computed by
\function{posv()} or \function{potrf()}.  On exit, \var{B} is replaced 
by the solution.
\var{B} must have the same type as \var{A}.
\end{funcdesc}

\begin{funcdesc}{potri}{A\optional{, uplo='L'}} 
Computes the inverse of a positive definite matrix.
On entry, \var{A} contains the Cholesky factorization computed 
by \function{potrf()} or \function{posv()}. On exit, it contains
the inverse.
\end{funcdesc}

As an example, we use \function{posv()} to solve the linear system
\BEQ \label{e-kkt-example}
 \left[ \begin{array}{cc}
 -\diag(d)^2  & A \\
 A^T  & 0 \end{array} \right]
 \left[ \begin{array}{c} x_1 \\ x_2 \end{array} \right]
 = \left[ \begin{array}{c} b_1 \\ b_2 \end{array} \right]
\EEQ
by block-elimination. 
We first pick a random problem.
\begin{verbatim}
>>> from cvxopt.base import matrix, div, normal, uniform
>>> from cvxopt.blas import syrk, gemv
>>> from cvxopt.lapack import posv
>>> m, n = 100, 50  
>>> A = normal(m,n)
>>> b1, b2 = normal(m), normal(n)
>>> d = uniform(m)
\end{verbatim}
We then solve the equations 
\[
 A^T \diag(d)^{-2}A x_2 = b_2 + A^T \diag(d)^{-2} b_1, \qquad
 \diag(d)^2 x_1 = Ax_2 - b_1.
\]
\begin{verbatim}
>>> Asc = div(A, d[:, n*[0]])                # Asc := diag(d)^{-1}*A
>>> B = matrix(0.0, (n,n))
>>> syrk(Asc, B, trans='T')                  # B := Asc^T * Asc = A^T * diag(d)^{-2} * A
>>> x1 = div(b1, d)                          # x1 := diag(d)^{-1}*b1
>>> x2 = +b2
>>> gemv(Asc, x1, x2, trans='T', beta=1.0)   # x2 := x2 + Asc^T*x1 = b2 + A^T*diag(d)^{-2}*b1 
>>> posv(B, x2)                              # x2 := B^{-1}*x2 = B^{-1}*(b2 + A^T*diag(d)^{-2}*b1)
>>> gemv(Asc, x2, x1, beta=-1.0)             # x1 := Asc*x2 - x1 = diag(d)^{-1} * (A*x2 - b1)
>>> x1 = div(x1, d)                          # x1 := diag(d)^{-1}*x1 = diag(d)^{-2} * (A*x2 - b1)
\end{verbatim}

There are separate routines for equations with positive definite band 
matrices.
\begin{funcdesc}{pbsv}{A, B\optional{, uplo='L'}}
Solves
\[
 AX=B
\]
where \tm{A} is a real symmetric or complex Hermitian positive definite
band matrix.  On entry, the diagonals of \tm{A} are stored in \var{A}, 
using the BLAS format for symmetric or Hermitian band matrices
(see section~\ref{s-conventions}).  On exit, \var{B} is replaced by the
solution, and \var{A} is overwritten with the Cholesky factor (in the
BLAS format for triangular band matrices).  The matrices \var{A} and 
\var{B} must have the same type (\dtc\ or \ztc).
Raises an \code{ArithmeticError} if the matrix is not positive definite.
\end{funcdesc}

\begin{funcdesc}{pbtrf}{A\optional{, uplo='L'}}
Cholesky factorization 
\[
 A = LL^T \qquad \mbox{or} \qquad A = LL^H
\]
of a positive definite real symmetric or complex Hermitian band matrix
\tm{A}.  On entry, the diagonals of \tm{A} are stored in \var{A}, 
using the BLAS format for symmetric or Hermitian band matrices.
On exit, \var{A} contains the Cholesky factor, in the BLAS format
for triangular band matrices.
Raises an \code{ArithmeticError} if the matrix is not positive definite.
\end{funcdesc}

\begin{funcdesc}{pbtrs}{A, B\optional{, uplo='L'}}
Solves a set of linear equations
\[
 AX=B
\]
with a positive definite real symmetric or complex Hermitian band matrix,
given the Cholesky factorization computed by \function{pbsv()} or 
\function{pbtrf()}.
On entry, \var{A} contains the triangular factor, as computed by
\function{pbsv()} or \function{pbtrf()}.  On exit, \var{B} is replaced 
by the solution.  \var{B} must have the same type as \var{A}.
\end{funcdesc}

The following functions are useful for tridiagonal systems.

\begin{funcdesc}{ptsv}{d, e, B}
Solves
\[ 
   A X = B,
\]
where \tm{A} is an \tm{n} by \tm{n} positive definite real symmetric 
or complex Hermitian tridiagonal matrix.  Its diagonal 
is stored as a \dtc\ matrix \var{d} of length \tm{n} and 
its subdiagonal as a \dtc\ or \ztc\ matrix \var{e} of length \tm{n-1}.
The arguments \var{e} and \var{B} must have the same type.  
On exit \var{d} contains the diagonal elements of \tm{D} in 
the $\mathrm{LDL^T}$ or $\mathrm{LDL^H}$ factorization 
of \tm{A}, and \var{e} contains the subdiagonal elements of the unit 
lower bidiagonal matrix \tm{L}.  
\var{B} is overwritten with the solution \tm{X}.  
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{pttrf}{d, e}
$\mathrm{LDL^T}$ or $\mathrm{LDL^H}$ factorization of an \tm{n} by 
\tm{n} positive definite real symmetric or complex Hermitian tridiagonal 
matrix \tm{A}.
On entry, the argument \var{d} is a \dtc\ matrix with the diagonal elements
of \tm{A}.  The argument \var{e} is \dtc\ or \ztc\ matrix with
the subdiagonal elements of \tm{A}.
On exit \var{d} contains the diagonal elements of \tm{D}, and \var{e} 
contains the subdiagonal elements of the unit lower bidiagonal matrix 
\tm{L}.  Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{gttrs}{d, e, B\optional{, uplo='L'}}
Solves a set of linear equations 
\[
 AX=B 
\]
where \tm{A} is an \tm{n} by \tm{n} positive definite real symmetric 
or complex Hermitian tridiagonal matrix, given its $\mathrm{LDL^T}$ or 
$\mathrm{LDL^H}$ factorization.
The argument \var{d} is the diagonal of the diagonal matrix \tm{D}.
The argument \var{uplo} only matters for complex matrices.
If \var{uplo} is \code{'L'}, then on exit \var{e} contains the subdiagonal 
elements of the unit bidiagonal matrix \tm{L}.
If \var{uplo} is \code{'U'}, then \var{e} contains the complex
conjugates of the elements of the unit bidiagonal matrix \tm{L}.
On exit, \var{B} is overwritten with the solution \tm{X}. 
\var{B} must have the same type as \var{e}.
\end{funcdesc}


\section{Symmetric and Hermitian Linear Equations}
\begin{funcdesc}{sysv}{A, B\optional{, ipiv=None\optional{, uplo='L'}}}
Solves
\[
 AX=B
\] 
where \tm{A} is a real or complex symmetric matrix  of order \tm{n}.
On exit, \var{B} is replaced by the solution.  
The matrices \var{A} and \var{B} must have the same type (\dtc\ or 
\ztc).
The optional argument \var{ipiv} is an integer matrix of length at 
least equal to \tm{n}.
If \var{ipiv} is provided, \function{sysv()} solves the system and 
returns the factorization in \var{A} and \var{ipiv}.
If \var{ipiv} is not specified, \function{sysv()} solves the
system but does not return the factorization and does not modify 
\var{A}.
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{sytrf}{A, ipiv\optional{, uplo='L'}}
$\mathrm{LDL^T}$ factorization 
\[
 PAP^T = LDL^T
\]
of a real or complex symmetric matrix \tm{A} of order \tm{n}.
\var{ipiv} is an \itc\ matrix of length at least \tm{n}.
On exit, \var{A} and \var{ipiv} contain the factorization.
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{sytrs}{A, ipiv, B\optional{, uplo='L'}}
Solves 
\[
  A X = B
\]
given the $\mathrm{LDL^T}$ factorization computed by 
\function{sytrf()} or \function{sysv()}. \var{B} must have the same
type as \var{A}.
\end{funcdesc}

\begin{funcdesc}{sytri}{A, ipiv\optional{, uplo='L'}}
Computes the inverse of a real or complex symmetric matrix.
On entry, \var{A} and \var{ipiv} contain the $\mathrm{LDL^T}$ 
factorization computed by \function{sytrf()} or \function{sysv()}. 
On exit, \var{A} contains the inverse.
\end{funcdesc}

\begin{funcdesc}{hesv}{A, B\optional{, ipiv=\None\optional{, uplo='L'}}}
Solves
\[
 A X = B
\]
where \tm{A} is a real symmetric or complex Hermitian of order \tm{n}.
On exit, \var{B} is replaced by the solution.
The matrices \var{A} and \var{B} must have the same type (\dtc\ or 
\ztc).
The optional argument \var{ipiv} is an integer matrix of length at 
least \tm{n}.  
If \var{ipiv} is provided, then \function{hesv()} solves the system and 
returns the factorization in \var{A} and \var{ipiv}.
If \var{ipiv} is not specified, then \function{hesv()} solves the
system but does not return the factorization and does not modify 
\var{A}.
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{hetrf}{A, ipiv\optional{, uplo='L'}}
$\mathrm{LDL^H}$ factorization 
\[
 PAP^T = LDL^H
\]
of a real symmetric or complex Hermitian matrix of order \tm{n}.
\var{ipiv} is an \itc\ matrix of length at least \tm{n}.
On exit, \var{A} and \var{ipiv} contain the factorization.
Raises an \code{ArithmeticError} if the matrix is singular.
\end{funcdesc}

\begin{funcdesc}{hetrs}{A, ipiv, B\optional{, uplo='L'}}
Solves 
\[
 A X = B
\]
given the $\mathrm{LDL^H}$ factorization computed by 
\function{hetrf()} or \function{hesv()}.
\end{funcdesc}

\begin{funcdesc}{hetri}{A, ipiv\optional{, uplo='L'}}
Computes the inverse of a real symmetric or complex Hermitian  matrix.
On entry, \var{A} and \var{ipiv} contain the $\mathrm{LDL^H}$ 
factorization computed by \function{hetrf()} or \function{hesv()}. 
On exit, \var{A} contains the inverse.
\end{funcdesc}

As an example we solve the KKT system~(\ref{e-kkt-example}).
\begin{verbatim}
>>> from cvxopt.lapack import sysv
>>> K = matrix(0.0, (m+n,m+n))
>>> K[: (m+n)*m : m+n+1] = -d**2
>>> K[:m, m:] = A
>>> x = matrix(0.0, (m+n,1))
>>> x[:m], x[m:] = b1, b2
>>> sysv(K, x, uplo='U')   
\end{verbatim}

\section{Triangular Linear Equations}

\begin{funcdesc}{trtrs}{A, B\optional{, uplo='L'\optional{, 
trans='N'\optional{, diag='N'}}}}
Solves a triangular set of equations
\[
 AX=B \quad (\mathrm{trans} = \mathrm{'N'}), \qquad
 A^TX=B \quad (\mathrm{trans} = \mathrm{'T'}), \qquad 
 A^HX=B \quad (\mathrm{trans} = \mathrm{'C'}), 
\]
where \tm{A} is real or complex and triangular of order \tm{n}, 
and \var{B} is a matrix with \tm{n} rows.
\var{A} and \var{B} are matrices with the same type (\dtc\ or \ztc).
\function{trtrs()} is similar to \function{blas.trsm()}, except
that it raises an \code{ArithmeticError} if a diagonal element of 
\var{A} is zero (whereas \function{blas.trsm()} returns \code{inf}
values).
\end{funcdesc}

\begin{funcdesc}{trtri}{A\optional{, uplo='L'\optional{, diag='N'}}}
Computes the inverse of a real or complex triangular matrix \tm{A}.  
On exit, \var{A} contains the inverse.
\end{funcdesc}

\begin{funcdesc}{tbtrs}{A, B\optional{, uplo='L'\optional{, 
trans='T'\optional{,diag='N'}}}}
Solves a triangular set of equations
\[
 AX=B \quad (\mathrm{trans} = \mathrm{'N'}), \qquad
 A^TX=B \quad (\mathrm{trans} = \mathrm{'T'}), \qquad 
 A^HX=B \quad (\mathrm{trans} = \mathrm{'C'}), 
\]
where \tm{A} is real or complex triangular band matrix of order \tm{n}, 
and \var{B} is a matrix with \tm{n} rows.
The diagonals of \tm{A} are stored in \var{A} using the BLAS conventions 
for triangular band matrices. 
\var{A} and \var{B} are matrices with the same type (\dtc\ or \ztc).
On exit, \var{B} is replaced by the solution \tm{X}.
\end{funcdesc}

\section{Least-Squares and Least-Norm Problems}
\begin{funcdesc}{gels}{A, B\optional{, trans='N'}}
Solves least-squares and least-norm problems with a full rank 
\tm{m} by \tm{n} matrix \tm{A}.

\begin{enumerate}
\item \var{trans} is \code{'N'}.  If \tm{m} is greater than or equal
to \tm{n}, \function{gels()} solves the least-squares problem
\[
 \begin{array}{ll} 
 \mbox{minimize} & \|AX-B\|_F.
 \end{array} 
\]
If \tm{m} is less than or equal to \tm{n}, \function{gels()} solves 
the least-norm problem
\[
 \begin{array}{ll} 
 \mbox{minimize} & \|X\|_F \\
 \mbox{subject to} & AX = B.
 \end{array}
\]

\item \var{trans} is \code{'T'} or \code{'C'} and \var{A} and \var{B}
are real.  If \tm{m} is greater than or equal to \tm{n},
\function{gels()} solves the least-norm problem
\[
 \begin{array}{ll} 
 \mbox{minimize} & \|X\|_F \\
 \mbox{subject to} & A^TX=B.
 \end{array}
\]
If \tm{m} is less than or equal to \tm{n}, \function{gels()} solves 
the least-squares problem
\[
 \begin{array}{ll} 
 \mbox{minimize} & \|A^TX-B\|_F.
 \end{array}
\]

\item \var{trans} is \code{'C'} and \var{A} and \var{B}
are complex. If \tm{m} is greater than or equal to \tm{n}, 
\function{gels()} solves the least-norm problem
\[
 \begin{array}{ll} 
 \mbox{minimize} & \|X\|_F \\
 \mbox{subject to} & A^HX=B.
 \end{array}
\]
If \tm{m} is less than or equal to \tm{n}, \function{gels()} solves 
the least-squares problem
\[
 \begin{array}{ll} 
 \mbox{minimize} & \|A^HX-B\|_F.
 \end{array}
\]
\end{enumerate}
\var{A} and \var{B} must have the same typecode (\dtc\ or \ztc).
\var{trans} = \code{'T'} is not allowed if \var{A} is complex.
On exit, the solution \tm{X} is stored as the leading submatrix 
of \var{B}.
The array \var{A} is overwritten with details of the QR or the LQ 
factorization of \tm{A}.
Note that \function{gels()} does not check whether \tm{A} is full rank.
\end{funcdesc}

\begin{funcdesc}{geqrf}{A, tau}
QR factorization of a real or complex matrix \var{A}:
\[
  A = Q R.
\]
If \var{A} is \tm{m} by \tm{n}, then \tm{Q} is \tm{m} by \tm{m} 
and orthogonal/unitary, and \var{R} is \tm{m} by \tm{n}
and upper triangular (if \tm{m} is greater than or equal to \tm{n}), 
or upper trapezoidal (if \tm{m} is less than or equal to \tm{n}).  
\var{tau}  is a matrix of the same type as {\var A} and of length at 
least \tm{\min\{m, n\}}.
On exit, \tm{R} is stored in the upper triangular part of \var{A}.
The matrix \tm{Q} is stored as a product of \tm{\min\{m, n\}}
elementary reflectors in the first \tm{\min\{m,n\}} columns 
of \var{A} and in \var{tau}.
\end{funcdesc}

\begin{funcdesc}{ormqr}{A, tau, C\optional{, side='L'\optional{, 
trans='N'}}}
Product with a real orthogonal matrix:
\[
 C := \op(Q)C \quad (\mathrm{side} = \mathrm{'L'}), \qquad 
 C := C\op(Q) \quad (\mathrm{side} = \mathrm{'R'}), \qquad 
 \op(Q) =  \left\{ \begin{array}{ll}
 Q & \mathrm{trans} = \mathrm{'N'} \\
 Q^T & \mathrm{trans} = \mathrm{'T'},
\end{array}\right.
\]
where \tm{Q} is square and orthogonal.  
\tm{Q} is stored in \var{A} and \var{tau} as a product 
of min\{\var{A}.\member{size}[0], \var{A}.\member{size}[1]\} 
elementary reflectors, as computed by \function{geqrf()}.
\end{funcdesc}

\begin{funcdesc}{unmqr}{A, tau, C\optional{, side='L'\optional{, 
trans='N'}}}
Product with a real orthogonal or complex unitary matrix:
\[
 C := \op(Q)C \quad (\mathrm{side} = \mathrm{'L'}), \qquad 
 C := C\op(Q) \quad (\mathrm{side} = \mathrm{'R'}), \qquad 
 \op(Q) =  \left\{ \begin{array}{ll}
 Q & \mathrm{trans} = \mathrm{'N'} \\
 Q^T & \mathrm{trans} = \mathrm{'T'} \\
 Q^H & \mathrm{trans} = \mathrm{'C'},
\end{array}\right.
\]
\tm{Q} is square and orthogonal or unitary.  
\tm{Q} is stored in \var{A} and \var{tau} as a product of 
min\{\var{A}.\member{size}[0], \var{A}.\member{size}[1]\} 
elementary reflectors, as computed by \function{geqrf()}.
The arrays \var{A}, \var{tau} and \var{C} must have the same type.
\code{\var{trans} = 'T'} is only allowed if the typecode is \dtc.
\end{funcdesc}


In the following example, we solve a least-squares problem 
by a direct call to \function{gels()}, and by separate calls to 
\function{geqrf()}, \function{ormqr()}, and \function{trtrs()}.
\begin{verbatim}
>>> from cvxopt import random, blas, lapack
>>> from cvxopt.base import matrix
>>> m, n = 10, 5
>>> A, b = random.normal(m,n), random.normal(m,1)
>>> x1 = +b
>>> lapack.gels(+A, x1)                  # x1[:n] minimizes ||A*x1[:n] - b||_2
>>> tau = matrix(0.0, (n,1)) 
>>> lapack.geqrf(A, tau)                 # A = [Q1, Q2] * [R1; 0]
>>> x2 = +b
>>> lapack.ormqr(A, tau, x2, trans='T')  # x2 := [Q1, Q2]' * b
>>> lapack.trtrs(A[:n,:], x2, uplo='U')  # x2[:n] := R1^{-1}*x2[:n]
>>> blas.nrm2(x1[:n] - x2[:n])
3.0050798580569307e-16
\end{verbatim}


\section{Symmetric and Hermitian Eigenvalue Decomposition}
The first four routines compute all or selected  eigenvalues and 
eigenvectors of a real symmetric matrix \tm{A}:
\[
 A = V\diag(\lambda)V^T,\qquad  V^TV = I.
\]

\begin{funcdesc}{syev}{A, W\optional{, jobz='N'\optional{, uplo='L'}}}
Eigenvalue decomposition of a real symmetric matrix of order \tm{n}.
\var{W} is a real matrix of length at least \tm{n}.
On exit, \var{W} contains the eigenvalues in ascending order.
If \var{jobz} is \code{'V'}, the eigenvectors are also computed
and returned in \var{A}.
If \var{jobz} is \code{'N'}, the eigenvectors are not returned and the 
contents of \var{A} are destroyed.
Raises an \code{ArithmeticError} if the eigenvalue decomposition fails.
\end{funcdesc}

\begin{funcdesc}{syevd}{A, W\optional{, jobz='N'\optional{, uplo='L'}}}
This is an alternative to \function{syev()}, based on a different
algorithm.  It is faster on large problems, but also uses more memory.
\end{funcdesc}

\begin{funcdesc}{syevx}{A, W\optional{, jobz='N'\optional{, 
range='A'\optional{, uplo='L'\optional{, vl=0.0, vu=0.0\optional{, 
il=1, iu=1\optional{, Z=\None}}}}}}}
Computes selected eigenvalues and eigenvectors of a real symmetric 
matrix \var{A} of order \tm{n}.

\var{W} is a real matrix of length at least \tm{n}.
On exit, \var{W} contains the eigenvalues in ascending order.
If \var{range} is \code{'A'}, all the eigenvalues are computed.
If \var{range} is \code{'I'}, eigenvalues \tm{\s{i}{l}} through 
\tm{\s{i}{u}}
are computed, where $1 \leq i_l \leq i_u \leq n$. 
If \var{range} is \code{'V'}, the eigenvalues in the interval 
\tm{(\s{v}{l},\s{v}{u}]} are computed. 

If \var{jobz} is \code{'V'}, the (normalized) eigenvectors are 
computed, and returned in \var{Z}.  If \var{jobz} is \code{'N'}, the 
eigenvectors are not computed.  In both cases, the contents of \var{A} 
are destroyed on exit.
\var{Z} is optional (and not referenced) if \var{jobz} is \code{'N'}.
It is required if \var{jobz} is \code{'V'} and must have at least
\tm{n} columns if \var{range} is \code{'A'} or \code{'V'} and  at
least \tm{\s{i}{u}-\s{i}{l}+1} columns if \var{range} is \code{'I'}.

\function{syevx()} returns the number of computed eigenvalues.
\end{funcdesc}

\begin{funcdesc}{syevr}{A, W\optional{, jobz='N'\optional{, 
range='A'\optional{, uplo='L'\optional{, vl=0.0, vu=0.0\optional{, 
il=1, iu=n\optional{, Z=\None}}}}}}}
This is an alternative to \function{syevx()}. 
\function{syevr()} is the most recent LAPACK routine for symmetric 
eigenvalue problems, and expected to supersede the three other 
routines in future releases.
\end{funcdesc}

The next four routines can be used to compute eigenvalues and 
eigenvectors for complex Hermitian matrices:
\[
 A = V\diag(\lambda)V^H,\qquad  V^HV = I.
\]
For real symmetric matrices they are identical to the corresponding
\function{syev\_()} routines.

\begin{funcdesc}{heev}{A, W\optional{, jobz='N'\optional{, uplo='L'}}}
Eigenvalue decomposition of a real symmetric or complex Hermitian
matrix of order \tm{n}.
The calling sequence is identical to \function{syev()}, except that 
\var{A} can be real or complex.
\end{funcdesc}

\begin{funcdesc}{heevd}{A, W\optional{, jobz='N'\optional{, uplo='L'}}}
This is an alternative to \function{heev()}. 
\end{funcdesc}

\begin{funcdesc}{heevx}{A, W\optional{, jobz='N'\optional{, 
range='A'\optional{, uplo='L'\optional{, vl=0.0, vu=0.0 \optional{, 
il=1, iu=n\optional{, Z=\None}}}}}}}
Computes selected eigenvalues and eigenvectors of a real symmetric 
or complex Hermitian matrix of order \tm{n}.
The calling sequence is identical to \function{syevx()},
except that \var{A} can be real or complex.
\var{Z} must have the same type as \var{A}.
\end{funcdesc}

\begin{funcdesc}{heevr}{A, W\optional{, jobz='N'\optional{, 
range='A'\optional{, uplo='L'\optional{, vl=0.0, vu=0.0\optional{, 
il=1, iu=n\optional{, Z=\None}}}}}}}
This is an alternative to \function{heevx()}. 
\end{funcdesc}

\section{Generalized Symmetric Definite Eigenproblems}
Three types of generalized eigenvalue problems can be solved:
\BEQ \label{e-gevd}
 AZ = BZ\diag(\lambda)\quad \mbox{(type 1)}, \qquad 
 ABZ = Z\diag(\lambda) \quad \mbox{(type 2)}, \qquad 
 BAZ = Z\diag(\lambda) \quad \mbox{(type 3)}, 
\EEQ
with \tm{A} and \tm{B} real symmetric or complex Hermitian, and \tm{B} positive 
definite.
The matrix of eigenvectors is normalized as follows:
\[
 Z^H BZ = I \quad \mbox{(types 1 and 2)}, \qquad 
 Z^H B^{-1}Z = I \quad \mbox{(type 3)}.
\]

\begin{funcdesc}{sygv}{A, B, W\optional{, itype=1\optional{, 
jobz='N'\optional{, uplo='L'}}}}
Solves the generalized eigenproblem~(\ref{e-gevd}) for real symmetric 
matrices of order \tm{n}, stored in real matrices \var{A} and \var{B}.
\var{itype} is an integer with possible values 1, 2, 3, and specifies
the type of eigenproblem.
\var{W} is a real matrix of length at least \tm{n}.
On exit, it contains the eigenvalues in ascending order.
On exit, \var{B} contains the Cholesky factor of \tm{B}.
If \var{jobz} is \code{'V'}, the eigenvectors are computed
and returned in \var{A}.
If \var{jobz} is \code{'N'}, the eigenvectors are not returned and the 
contents of \var{A} are destroyed.
\end{funcdesc}

\begin{funcdesc}{hegv}{A, B, W\optional{, itype=1\optional{, 
jobz='N'\optional{, uplo='L'}}}}
Generalized eigenvalue problem~(\ref{e-gevd}) of real symmetric or 
complex Hermitian matrix of order \tm{n}.
The calling sequence is identical to \function{sygv()},
except that \var{A} and \var{B} can be real or complex.
\end{funcdesc}


\section{Singular Value Decomposition}

\begin{funcdesc}{gesvd}{A, S\optional{, jobu='N'\optional{, 
jobvt='N'\optional{, U=\None\optional{, Vt=\None}}}}}
Singular value decomposition 
\[
 A = U \Sigma V^T, \qquad A = U \Sigma V^H
\]
of a real or complex \tm{m} by \tm{n} matrix \var{A}.

\var{S} is a real matrix of length at least \tm{\min\{m, n\}}.
On exit, its first  \tm{\min\{m, n\}} elements are the 
singular values in descending order.

The argument \var{jobu} controls how many left singular vectors are
computed.  The possible values are \code{'N'}, \code{'A'}, \code{'S'} 
and \code{'O'}. 
If \var{jobu} is \code{'N'}, no left singular vectors are 
computed.
If \var{jobu} is \code{'A'}, all left singular vectors are computed 
and returned as columns of \var{U}.
If \var{jobu} is \code{'S'}, the first \tm{\min\{m, n\}} left 
singular vectors are computed and returned as columns of \var{U}.
If \var{jobu} is \code{'O'}, the first \tm{\min\{m, n\}} left 
singular vectors are computed and returned as columns of \var{A}.
The argument \var{U} is \None\ (if \var{jobu} is \code{'N'}
or \code{'A'}) or a matrix of the same type as \var{A}.

The argument \var{jobvt} controls how many right singular vectors are
computed.  The possible values are \code{'N'}, \code{'A'}, \code{'S'} 
and \code{'O'}. 
If \var{jobvt} is \code{'N'}, no right singular vectors are 
computed.  If \var{jobvt} is \code{'A'}, all right singular vectors 
are computed and returned as rows of \var{Vt}.
If \var{jobvt} is \code{'S'}, the first \tm{\min\{m, n\}} right 
singular vectors are computed and their (conjugate) transposes are
returned as rows of \var{Vt}.
If \var{jobvt} is \code{'O'}, the first \tm{\min\{m, n\}} right 
singular vectors are computed and their (conjugate) transposes 
are returned as rows of \var{A}.
Note that the (conjugate) transposes of the right singular vectors 
(\ie, the matrix $V^H$) are returned in \var{Vt} or \var{A}.
The argument \var{Vt} can be \None\ (if \var{jobvt} is \code{'N'}
or \code{'A'}) or a matrix of the same type as \var{A}.

On exit, the contents of \var{A} are destroyed.
\end{funcdesc}

\begin{funcdesc}{gesdd}{A, S\optional{, jobz='N'\optional{, 
U=\None\optional{, Vt=\None}}}} 
Singular value decomposition of a real or complex \tm{m} by \tm{n} 
matrix \var{A}.  This function is based on a divide-and-conquer 
algorithm and is faster than \function{gesvd()}.

\var{S} is a real matrix of length at least \tm{\min\{m, n\}}.
On exit, its first \tm{\min\{m, n\}} elements are the 
singular values in descending order.

The argument \var{jobz} controls how many singular vectors are
computed.  The possible values are \code{'N'}, \code{'A'}, \code{'S'} 
and \code{'O'}. 
If \var{jobz} is \code{'N'}, no singular vectors are computed.
If \var{jobz} is \code{'A'}, all \tm{m} left singular vectors are 
computed and returned as columns of \var{U} and all \tm{n} right 
singular vectors are computed and returned as rows of \var{Vt}.
If \var{jobz} is \code{'S'}, the first \tm{\min\{m, n\}} left 
and right singular vectors are computed and returned as columns of 
\var{U} and rows of \var{Vt}.
If \var{jobz} is \code{'O'} and \tm{m} is greater than or equal
to \tm{n}, the first \tm{n} left singular vectors are returned as
columns of \var{A} and the \tm{n} right singular vectors are returned
as rows of \var{Vt}.  If \var{jobz} is \code{'O'} and \tm{m} is less 
than \tm{n}, the \tm{m} left singular vectors are returned as columns
of \var{U} and the first \tm{m} right singular vectors are returned 
as rows of \var{A}.  
Note that the (conjugate) transposes of the right singular vectors 
are returned in \var{Vt} or \var{A}.

The argument \var{U} can be \None\ (if \var{jobz} is \code{'N'}
or \code{'A'} of \var{jobz} is \code{'O'} and \tm{m} is greater than
or equal to  \tm{n})  or a matrix of the same type as \var{A}.
The argument \var{Vt} can be \None\ (if \var{jobz} is \code{'N'}
or \code{'A'} or \var{jobz} is \code{'O'} and \tm{m} is less than
\tm{n}) or a matrix of the same type as \var{A}.

On exit, the contents of \var{A} are destroyed.
\end{funcdesc}

\section{Example: Analytic Centering}
The analytic centering problem is defined as
\[
 \begin{array}{ll}
  \mbox{minimize} & -\sum_{i=1}^m \log(b_i-a_i^Tx).
 \end{array}
\]
In the code below we solve the problem using Newton's method.
At each iteration the Newton direction is computed by solving 
a positive definite set of linear equations
\[
 A^T \diag(b-Ax)^{-2} A v = -\diag(b-Ax)^{-1}\ones
\]
(where \tm{A} has rows $a_i^T$), and a suitable step size is determined 
by a backtracking line search.

We use the level-3 BLAS function \function{syrk()} to form the Hessian 
matrix and the LAPACK function \function{posv()} to solving the Newton
system.   The code can be further optimized by replacing the 
matrix-vector products with the level-2 BLAS function \function{gemv()}.

\begin{verbatim}
from cvxopt.base import matrix, log, mul, div
from cvxopt import blas, lapack, random
from math import sqrt

def acent(A,b):
    """  
    Returns the analytic center of A*x <= b.
    We assume that b > 0 and the feasible set is bounded.
    """

    MAXITERS = 100
    ALPHA = 0.01
    BETA = 0.5
    TOL = 1e-8

    m, n = A.size
    x = matrix(0.0, (n,1))
    H = matrix(0.0, (n,n))

    for iter in xrange(MAXITERS):
        
        # Gradient is g = A^T * (1./(b-A*x)).
        d = (b-A*x)**-1
        g = A.T * d

        # Hessian is H = A^T * diag(d)^2 * A.
        Asc = mul( d[:,n*[0]], A )
        blas.syrk(Asc, H, trans='T')

        # Newton step is v = -H^-1 * g.
        v = -g
        lapack.posv(H, v)

        # Terminate if Newton decrement is less than TOL.
        lam = blas.dot(g, v)
        if sqrt(-lam) < TOL: return x

        # Backtracking line search.
        y = mul(A*v, d)
        step = 1.0
        while 1-step*max(y) < 0: step *= BETA 
        while True:
            if -sum(log(1-step*y)) < ALPHA*step*lam: break
            step *= BETA
        x += step*v
\end{verbatim}
