\chapter{Dense Matrices (\module{cvxopt.base})}\label{chap:matrix}

The \module{cvxopt.base} module defines two new Python types: 
\mtrx\ objects, used for dense matrix computations, and 
\spmtrx\ objects, used for sparse matrix computations.
In this chapter we describe the dense \mtrx\ object.
Sparse matrices are discussed in chapter~\ref{chap:spmatrix}.

\section{Creating Matrices}\label{s-creating-matrices}
A \mtrx\ object is created by calling the function \function{matrix()}. 
The arguments specify the values of the coefficients, the
dimensions, and the type (integer, double or complex) of the matrix.

\begin{funcdesc}{matrix}{x\optional{, size\optional{, tc}}}
\var{size} is a tuple of length two with the matrix dimensions.
The number of rows and/or the number of columns can be zero.

\var{tc} stands for typecode. The possible values are \itc, \dtc\ and 
\ztc, for integer, real (double) and complex matrices, respectively.  

\var{x} can be a number, a sequence of numbers, a dense or sparse 
matrix, a one- or two-dimensional \program{NumPy} array, or a list of
lists of matrices and numbers.  
\BIT
\item If \var{x} is a number (Python \intgr, \flt\ or \cmplx), a matrix
is created with the dimensions specified by \var{size} and with all the 
coefficients equal to \var{x}.  
The default value of \var{size} is \tm{(1,1)}, and the default value
of \var{tc} is the type of \var{x}.
If necessary, the type of \var{x} is converted (from integer to double
when used to create a matrix of type \dtc, and from integer or
double to complex when used to create a matrix of type \ztc).

\begin{verbatim}
>>> from cvxopt.base import matrix
>>> A = matrix(1, (1,4))   
>>> print A
[ 1  1  1  1]
>>> A = matrix(1.0, (1,4))   
>>> print A
[ 1.00e+00  1.00e+00  1.00e+00  1.00e+00]
>>> A = matrix(1+1j)     
>>> print A
[ 1.00e+00+j1.00e+00]
\end{verbatim}

\item If \var{x} is a sequence of numbers (list, tuple, \module{array}
array, xrange object, one-dimensional \program{NumPy} array, \ldots),
then the numbers are interpreted as the coefficients of a matrix in 
column-major order.  The length of \var{x} must be equal to the product 
of \code{size[0]} and \code{size[1]}.
If \var{size} is not specified, a matrix with one column is created. 
If \var{tc} is not specified, it is determined from the elements of 
\var{x} (and if that is impossible, for example because \var{x} is
an empty list, a value \itc\ is used).  
Type conversion takes place as for scalar \var{x}.

The following example shows several ways to define the same integer 
matrix.
\begin{verbatim}
>>> A = matrix([0, 1, 2, 3], (2,2))  
>>> A = matrix((0, 1, 2, 3), (2,2))  
>>> A = matrix(xrange(4), (2,2))
>>> from array import array
>>> A = matrix(array('i', [0,1,2,3]), (2,2))
>>> print A
[ 0  2]
[ 1  3]
\end{verbatim}

\item If \var{x} is a dense or sparse matrix (a \mtrx\ or a \spmtrx\ 
object), or a two-dimensional \program{NumPy} array of type \itc, 
\dtc\ or \ztc, then the  coefficients of \var{x} are copied, in 
column-major order, to a new matrix of the given size.  
The total number of elements in the new matrix (the product of 
\code{size[0]} and \code{size[1]}) must be the same as the product of  
the dimensions of \var{x}.  If \var{size} is not specified, the 
dimensions of \var{x} are used.  
The default value of \var{tc} is the type of \var{x}. 
Type conversion takes place when the type of \var{x} differs from 
\var{tc}, in a similar way as for scalar \var{x}.  

\begin{verbatim}
>>> A = matrix([1., 2., 3., 4., 5., 6.], (2,3))  
>>> print A
[ 1.00e+00  3.00e+00  5.00e+00]
[ 2.00e+00  4.00e+00  6.00e+00]
>>> B = matrix(A, (3,2))  
>>> print B
[ 1.00e+00  4.00e+00]
[ 2.00e+00  5.00e+00]
[ 3.00e+00  6.00e+00]
>>> C = matrix(B, tc='z')      
>>> print C
[ 1.00e+00-j0.00e+00  4.00e+00-j0.00e+00]
[ 2.00e+00-j0.00e+00  5.00e+00-j0.00e+00]
[ 3.00e+00-j0.00e+00  6.00e+00-j0.00e+00]
>>> from numpy import array
>>> x = array([[1., 2., 3.], [4., 5., 6.]])
>>> x
array([[ 1.  2.  3.]
       [ 4.  5.  6.]])
>>> print matrix(x)
[ 1.00e+00  2.00e+00  3.00e+00]
[ 4.00e+00  5.00e+00  6.00e+00]
\end{verbatim}

\item If \var{x} is a list of lists of matrices 
(\mtrx\ or \spmtrx\ objects) or numbers (Python \intgr, \flt\ or 
\cmplx), then each element of \var{x} is interpreted as a 
block-column stored in column-major order. 
If \var{size} is not specified, the block-columns are juxtaposed
to obtain a matrix with \code{len(\var{x})} block-columns.
If \var{size} is specified, then the matrix with \code{len(\var{x})}
block-columns is resized by copying its elements in column-major order 
into a matrix of the dimensions given by \var{size}.  
If \var{tc} is not specified, it is determined from the elements of 
\var{x} (and if that is impossible, for example because \var{x} is
a list of empty lists, a value \itc\ is used).  
The same rules for type conversion apply as for scalar \var{x}.

\begin{verbatim}
>>> print matrix([[1., 2.], [3., 4.], [5., 6.]])
[ 1.00e+00  3.00e+00  5.00e+00]
[ 2.00e+00  4.00e+00  6.00e+00]
>>> A1 = matrix([1, 2], (2,1))
>>> B1 = matrix([6, 7, 8, 9, 10, 11], (2,3))
>>> B2 = matrix([12, 13, 14, 15, 16, 17], (2,3))
>>> B3 = matrix([18, 19, 20], (1,3))
>>> C = matrix([[A1, 3.0, 4.0, 5.0], [B1, B2, B3]])
>>> print C
[ 1.00e+00  6.00e+00  8.00e+00  1.00e+01]
[ 2.00e+00  7.00e+00  9.00e+00  1.10e+01]
[ 3.00e+00  1.20e+01  1.40e+01  1.60e+01]
[ 4.00e+00  1.30e+01  1.50e+01  1.70e+01]
[ 5.00e+00  1.80e+01  1.90e+01  2.00e+01]
\end{verbatim}

A matrix with a single block-column can be represented by a single 
list (\ie, when the length of \var{x} is one, it can be replaced with
\code{\var{x}[0]}).
\begin{verbatim}
>>> D = matrix([B1, B2, B3])
>>> print D
[  6   8  10]
[  7   9  11]
[ 12  14  16]
[ 13  15  17]
[ 18  19  20]
\end{verbatim}
\EIT
\end{funcdesc}

\section{Attributes and Methods} 
A \mtrx\ has the following attributes.

\begin{memberdesc}{size}
A tuple with the dimensions of the matrix. This is a read-only 
attribute; operations that change the size of a matrix are not 
permitted.
\end{memberdesc} 

\begin{memberdesc}{typecode}
A \ctype{char}, either \itc, \dtc, or \ztc, for integer, real
and complex matrices, respectively.  A read-only attribute.
\end{memberdesc} 

\begin{methoddesc}{trans}
Returns the transpose of the matrix as a new matrix.
One can also use \code{A.T} instead of \code{A.trans()}.
\end{methoddesc}

\begin{methoddesc}{ctrans}
Returns the conjugate transpose of the matrix as a new matrix.
One can also use \code{A.H} instead of \code{A.ctrans()}.
\end{methoddesc}

\begin{methoddesc}{real}
For complex matrices, returns the real part as a real matrix.
For integer and real matrices, returns a copy of the matrix.
\end{methoddesc}

\begin{methoddesc}{imag}
For complex matrices, returns the imaginary part as a real matrix.
For integer and real matrices, returns an integer or real zero matrix.
\end{methoddesc}

\begin{memberdesc}{\_\_array\_struct\_\_}
A PyCObject implementing the \program{NumPy} array interface  
(see section~\ref{s-array-interface} for details).
\end{memberdesc} 

\begin{funcdesc}{tofile}{f}
Writes the elements of the matrix in column-major order to a binary 
file \var{f}. 
\end{funcdesc}

\begin{funcdesc}{fromfile}{f}
Reads the contents of a binary file \var{f} into the matrix object.
\end{funcdesc}

The last two methods are illustrated in the following example.
\begin{verbatim}
>>> from cvxopt.base import matrix
>>> A = matrix([[1.,2.,3.], [4.,5.,6.]])  
>>> print A
[ 1.00e+00  4.00e+00]
[ 2.00e+00  5.00e+00]
[ 3.00e+00  6.00e+00]
>>> f = open('mat.bin','w')
>>> A.tofile(f)
>>> f.close()
>>> B = matrix(0.0, (2,3))
>>> f = open('mat.bin','r')
>>> B.fromfile(f)
>>> f.close()
>>> print B
[ 1.00e+00  3.00e+00  5.00e+00]
[ 2.00e+00  4.00e+00  6.00e+00]
\end{verbatim}

Matrices can also be written to or read from files using the 
\function{dump()} and \function{load()} functions in the 
\module{pickle} module. 


\section{Arithmetic Operations} \label{s-arithmetic}
The following table lists the arithmetic operations defined for 
dense matrices.  In this table \var{A} and \var{B} are dense matrices 
with compatible dimensions, \var{c} is a scalar (a Python number 
or a dense 1 by 1 matrix), and \var{d} is a Python number.

\begin{center}
\begin{tabular}{l|l}
\hline
Unary plus/minus & \code{+\var{A}}, \code{-\var{A}} \\ \hline 
Addition & \code{\var{A}+\var{B}}, \code{\var{A}+\var{c}}, 
    \code{\var{c}+\var{A}}\\ \hline 
Subtraction & \code{\var{A}-\var{B}}, \code{\var{A}-\var{c}}, 
    \code{\var{c}-\var{A}}\\ \hline 
Matrix multiplication & \code{{\var{A}*\var{B}}} \\ \hline
Scalar multiplication and division & \code{\var{c}*\var{A}}, 
    \code{\var{A}*\var{c}}, \code{\var{A}/\var{c}} \\ \hline 
Remainder after division & \code{\var{A}\%\var{c}} \\ \hline 
Elementwise exponentiation  & \code{\var{A}**\var{d}} \\ \hline 
\end{tabular}
\end{center}

If \var{c} in the expressions \code{\var{A}+\var{c}}, 
\code{\var{c}+\var{A}}, \code{\var{A}-\var{c}}, 
\code{\var{c}-\var{A}} is a number, then it is interpreted as a 
matrix with the same dimensions as \var{A}, type given by the type 
of \var{c}, and all entries equal to \var{c}.
If \var{c}  is a 1 by 1 matrix and \var{A} is not 1 by 1, then \var{c} 
is interpreted as a matrix with the same size of \var{A} and all 
entries equal to \code{\var{c}[0]}.

Postmultiplying a matrix with a number \var{c} means the same as 
premultiplying, \ie, scalar multiplication.  Dividing a matrix by 
\var{c} means dividing all entries by \var{c}.  
If \var{c} is a 1 by 1 matrix and the product
\code{\var{c}*\var{A}} or \code{\var{A}*\var{c}} cannot be 
interpreted as a matrix-matrix product, then it is interpreted as 
\code{\var{c}[0]*\var{A}}. 
The division \code{\var{A}/\var{c}} and remainder 
\code{\var{A}\%\var{c}} with \var{c} a 1 by 1 matrix are always 
interpreted as \code{\var{A}/\var{c}[0]}, resp.,
\code{\var{A}\%\var{c}[0]}.

If one of the operands in the arithmetic operations is integer 
(a scalar \intgr\ or a matrix of type \itc) and the other operand 
is double (a scalar \flt\ or a matrix of type \dtc), then the 
integer operand is converted to double, and the result is a matrix of 
type \dtc.
If one of the operands is integer or double, and the other operand is 
complex (a scalar \cmplx\ or a matrix of type \ztc), 
then the first operand is converted to complex, and the result is 
a matrix of type \ztc.  

The result of \code{\var{A}**\var{d}} is a complex matrix
if \var{A} or \var{d} are complex, and real otherwise.

Note that Python rounds the result of an integer division towards minus 
infinity.

The following in-place operations are also defined, but only if 
they do not change the type or the size of the matrix \var{A}: 
\begin{center}\begin{tabular}{l|l} \hline
 In-place addition & 
    \code{\var{A}+=\var{B}}, \code{\var{A}+=\var{c}} \\ \hline
 In-place subtraction & 
    \code{\var{A}-=\var{B}}, \code{\var{A}-=\var{c}} \\ \hline   
 In-place scalar multiplication and division & 
    \code{\var{A}*=\var{c}}, \code{\var{A}/=\var{c}} \\ \hline
 In-place remainder & \code{\var{A}\%=\var{c}} \\ \hline
\end{tabular}\end{center}

For example, if \var{A} has type \itc, then \code{\var{A}+=\var{B}} 
is allowed if \var{B} has type \itc.
It is not allowed if \var{B} has type \dtc or \ztc because the 
addition \code{\var{A}+\var{B}} results in a matrix of 
type \dtc or \ztc and therefore cannot be assigned to \var{A} 
without changing its type.

In-place matrix-matrix products are not allowed.  (Except when
\var{c} is a 1 by 1 matrix, in which case \code{\var{A}*=\var{c}} is 
interpreted as the scalar product \code{\var{A}*=\var{c}[0]}.)

It is important to know when a matrix operation creates
a new object.  The following rules apply.
\begin{itemize}
\item A simple assignment (\samp{A = B}) is given the standard 
Python interpretation, \ie, it assigns to the variable \var{A} a 
reference (or pointer) to the object referenced by \var{B}.
\begin{verbatim}
>>> B = matrix([[1.,2.], [3.,4.]])  
>>> print B
[ 1.00e+00  3.00e+00]
[ 2.00e+00  4.00e+00]
>>> A = B
>>> A[0,0] = -1 
>>> print B   # modifying A[0,0] also modified B[0,0]
[-1.00e+00  3.00e+00]
[ 2.00e+00  4.00e+00]
\end{verbatim}

\item The regular (\ie, not in-place) arithmetic operations always 
return new objects.   Hence \samp{A = +B} is equivalent to 
\samp{A = matrix(B)}.
\begin{verbatim}
>>> B = matrix([[1.,2.], [3.,4.]])  
>>> A = +B
>>> A[0,0] = -1 
>>> print B   # modifying A[0,0] does not modify B[0,0]
[ 1.00e+00  3.00e+00]
[ 2.00e+00  4.00e+00]
\end{verbatim}

\item  The in-place operations directly modify the coefficients of the 
 existing matrix object and do not create a new object. 
\begin{verbatim}
>>> B = matrix([[1.,2.], [3.,4.]])  
>>> A = B
>>> A *= 2
>>> print B   # in-place operation also changed B
[ 2.00e+00  6.00e+00]
[ 4.00e+00  8.00e+00]
>>> A = 2*A
>>> print B   # regular operation creates a new A, so does not change B
[ 2.00e+00  6.00e+00]
[ 4.00e+00  8.00e+00]
\end{verbatim}
\end{itemize}

The restrictions on in-place operations follow the principle that once 
a matrix object is created, its size and type cannot be modified.  
The only matrix attributes that can be changed are the values of the 
elements.  The values can be changed by in-place operations or by an 
indexed assignment, as explained in the next section. 

\section{Indexing and Slicing} \label{s-indexing}

Matrices can be indexed using one or two arguments.  In single-argument
indexing of a matrix \var{A}, the index runs from 
\code{-len(\var{A})} to \code{len(\var{A})-1}, and is interpreted as an
index in the one-dimensional array of coefficients of \var{A} 
in column-major order.   Negative indices have the standard Python 
interpretation: for negative \var{k}, \code{\var{A}[\var{k}]} is the 
same element as  \code{\var{A}[len(\var{A})+\var{k}]}.

Four different types of one-argument indexing are implemented.
\begin{enumerate}
\item The index can be a single integer.  This returns a 
number, \eg, \code{\var{A}[0]} is the first element of \var{A}.

\item The index can be an integer matrix.  This returns a 
column matrix: the command \samp{A[matrix([0,1,2,3])]} 
returns the 4 by 1 matrix consisting of the first four elements of
\var{A}.   The size of the index matrix is ignored: 
\samp{A[matrix([0,1,2,3], (2,2))]} returns the same 4 by 1 matrix.

\item The index can be a list of integers.  This returns a column 
matrix, \eg, \code{\var{A}[[0,1,2,3]]} is the 4 by 1 matrix consisting 
of elements 0, 1, 2, 3 of \var{A}.   

\item The index can be a Python slice.  This returns a matrix with one 
column (possibly 0 by 1, or 1 by 1).  For example, \code{\var{A}[::2]} 
is the column matrix defined by taking every other element of \var{A}, 
stored in column-major order.  
\code{\var{A}[0:0]} is a matrix with size (0,1).
\end{enumerate}
Thus, single-argument indexing returns a scalar (if the index is an 
integer), or a matrix with one column.  This is consistent with the 
interpretation that single-argument indexing accesses the matrix in 
column-major order.

Note that an index list or an index matrix are equivalent,
but they are both useful, especially when we perform operations on 
index sets.  For example, if \var{I} and \var{J} are lists then 
\code{\var{I}+\var{J}} is the concatenated list, and \code{2*\var{I}} 
is \var{I} repeated twice.  If they are matrices, these operations are 
interpreted as arithmetic operations.
For large index sets, indexing with integer matrices is also faster 
than indexing with lists. 

The following example illustrates one-argument indexing.
\begin{verbatim}
>>> from cvxopt.base import matrix 
>>> A = matrix(range(16), (4,4), 'd')
>>> print A
[ 0.00e+00  4.00e+00  8.00e+00  1.20e+01]
[ 1.00e+00  5.00e+00  9.00e+00  1.30e+01]
[ 2.00e+00  6.00e+00  1.00e+01  1.40e+01]
[ 3.00e+00  7.00e+00  1.10e+01  1.50e+01]
>>> A[4]
4.0
>>> I = matrix([0, 5, 10, 15])
>>> print A[I]      # the diagonal
[ 0.00e+00]
[ 5.00e+00]
[ 1.00e+01]
[ 1.50e+01]
>>> I = [0,2];  J = [1,3]
>>> print A[2*I+J]  # duplicate I and append J
[ 0.00e+00]
[ 2.00e+00]
[ 0.00e+00]
[ 2.00e+00]
[ 1.00e+00]
[ 3.00e+00]
>>> I = matrix([0, 2]);  J =  matrix([1, 3])
>>> print A[2*I+J]  # multiply I by 2 and add J
[ 1.00e+00]
[ 7.00e+00]
>>> print A[4::4]   # get every fourth element skipping the first four  
[ 4.00e+00]
[ 8.00e+00]
[ 1.20e+01]
\end{verbatim}

In two-argument indexing the arguments can be any combinations of the
four types listed above.  The first argument indexes the rows of 
the matrix and the second argument indexes the columns.  If both 
indices are scalars, then a scalar is returned.  In all other cases, 
a matrix is returned.  We continue the example.
\begin{verbatim}
>>> print A[:,1]
[ 4.00e+00]
[ 5.00e+00]
[ 6.00e+00]
[ 7.00e+00]
>>> J = matrix([0, 2])
>>> print A[J,J]
[ 0.00e+00  8.00e+00]
[ 2.00e+00  1.00e+01]
>>> print A[:2, -2:]   
[ 8.00e+00  1.20e+01]
[ 9.00e+00  1.30e+01]
\end{verbatim}

Expressions of the form \code{\var{A}[\var{I}]} or 
\code{\var{A}[\var{I},\var{J}]} can also appear on the lefthand side 
of an assignment.   
The righthand side must be a scalar (\ie, a number or a 1 by 1 dense
matrix), a sequence of numbers, or a dense or sparse matrix. 
If the righthand side is a scalar, it is interpreted as a 
matrix with identical entries and the dimensions of the lefthand side.
If the righthand side is a sequence of numbers (list, tuple, 
\module{array} array, xrange object, \ldots) its values are 
interpreted as the coefficients of the lefthand side in column-major 
order.  If the righthand side is a matrix (\mtrx\ or \spmtrx), it must 
have the same size as the lefthand side.  Sparse matrices are 
converted to dense in the assignment.

Indexed assignments are only allowed if they do not change the type of 
the matrix.  For example, if \var{A} is a matrix with type \dtc, then 
\code{\var{A}[\var{I}] = \var{B}} is only permitted if \var{B} is 
an \intgr, a \flt, or a matrix of type \itc\ or \dtc.
If \var{A} is an integer matrix, then \code{\var{A}[\var{I}] = \var{B}} 
is only permitted if \var{B} is an \intgr\  or an integer matrix.

The following example illlustrates indexed assignment.
\begin{verbatim}
>>> A = matrix(range(16), (4,4))
>>> A[::2,::2] = matrix([[-1, -2], [-3, -4]])
>>> print A
[ -1   4  -3  12]
[  1   5   9  13]
[ -2   6  -4  14]
[  3   7  11  15]
>>> A[::5] += 1
>>> print A
[  0   4  -3  12]
[  1   6   9  13]
[ -2   6  -3  14]
[  3   7  11  16]
>>> A[0,:] = -1, 1, -1, 1
>>> print A
[ -1   1  -1   1]
[  1   6   9  13]
[ -2   6  -3  14]
[  3   7  11  16]
>>> A[2:,2:] = xrange(4)
>>> print A
[ -1   1  -1   1]
[  1   6   9  13]
[ -2   6   0   2]
[  3   7   1   3]
\end{verbatim}

\section{Built-in Functions} \label{s-builtinfuncs}
Many Python built-in functions and operations can be used with matrix 
arguments.  We list some useful examples.

\begin{funcdesc}{len}{x}
Returns the product of the number of rows and the number of columns. 
\end{funcdesc}

\begin{funcdesc}{bool}{\optional{x}}
Returns \False\ if \var{x} is empty (\ie, \code{len(\var{x})} is zero) 
and \True\ otherwise.
\end{funcdesc}

\begin{funcdesc}{max}{x}
Returns the maximum element of \var{x}.
\end{funcdesc}

\begin{funcdesc}{min}{x}
Returns the minimum element of \var{x}.
\end{funcdesc}

\begin{funcdesc}{abs}{x}
Returns a matrix with the absolute values of the elements of \var{x}.
\end{funcdesc}

\begin{funcdesc}{sum}{x\optional{, start=0.0}}
Returns the sum of \var{start} and the elements of \var{x}.
\end{funcdesc}

Matrices can be used as  arguments to the \function{list()}, 
\function{tuple()}, \function{zip()}, \function{map()}, and 
\function{filter()} functions described in section 2.1 of the Python 
Library Reference.  \code{list(\var{A})} and \code{tuple(\var{A})} 
construct a list, respectively a tuple, from the elements of \var{A}.
\code{zip(\var{A},\var{B},\ldots)} returns a list of tuples, 
with the {\it i}th tuple containing the {\it i}th elements of \var{A}, 
\var{B}, \ldots.

\begin{verbatim}
>>> from cvxopt.base import matrix
>>> A = matrix([[-11., -5., -20.], [-6., -0., 7.]])
>>> B = matrix(range(6), (3,2))
>>> list(A)
[-11.0, -5.0, -20.0, -6.0, 0.0, 7.0]
>>> tuple(B)
(0, 1, 2, 3, 4, 5)
>>> zip(A,B)
[(-11.0, 0), (-5.0, 1), (-20.0, 2), (-6.0, 3), (0.0, 4), (7.0, 5)]
\end{verbatim}

\code{map(\var{f},\var{A})}, where \var{f} is a function and \var{A} 
is a matrix, returns a list constructed by applying \var{f} to each 
element of \var{A}.  Multiple arguments can be provided, for example, 
as in \code{map(\var{f},\var{A},\var{B})}, if \var{f} is a function 
with two arguments.
\begin{verbatim}
>>> A = matrix([[5, -4, 10, -7], [-1, -5, -6, 2], [6, 1, 5, 2],  [-1, 2, -3, -7]])
>>> B = matrix([[4,-15, 9, -14], [-4, -12, 1, -22], [-10, -9, 9, 12], [-9, -7,-11, -6]])
>>> print matrix(map(max, A, B), (4,4))   # takes componentwise maximum
[  5  -1   6  -1]
[ -4  -5   1   2]
[ 10   1   9  -3]
[ -7   2  12  -6]
\end{verbatim}

\code{filter(\var{f},\var{A})}, where \var{f} is a function and 
\var{A} is a matrix, returns a list containing the elements of \var{A} 
for which \var{f} is true.
\begin{verbatim}
>>> filter(lambda x: x%2, A)         # list of odd elements in A
[5, -7, -1, -5, 1, 5, -1, -3, -7]
>>> filter(lambda x: -2 < x < 3, A)  # list of elements between -2 and 3
[-1, 2, 1, 2, -1, 2]
\end{verbatim}

It is also possible to iterate over matrix elements, as illustrated in
the following example.
\begin{verbatim}
>>> A = matrix([[5, -3], [9, 11]])
>>> for x in A: print max(x,0)
...
5
0
9
11
>>> [max(x,0) for x in A]
[5, 0, 9, 11]
\end{verbatim}

The expression \samp{\var{x} in \var{A}} returns \True\ if an element 
of \var{A} is equal to \var{x} and \False\ otherwise.

\section{Other Matrix Functions} \label{s-otherfuncs}
The following functions of dense matrices can be imported from 
\module{cvxopt.base}.
\begin{funcdesc}{sqrt}{x}
The elementwise square root of \var{x}.  The result is returned 
as a real matrix if \var{x} is an integer or real matrix and 
as a complex matrix if \var{x} is a complex matrix.  Raises an 
exception when \var{x} is an integer or real matrix with negative 
elements.
\end{funcdesc}

\begin{funcdesc}{sin}{x}
The sine function applied elementwise to \var{x}.  
The result is returned as a real matrix if \var{x} is an integer
or real matrix and as a complex matrix otherwise.  
\end{funcdesc}

\begin{funcdesc}{cos}{x}
The cosine function applied elementwise to \var{x}.  
The result is returned as a real matrix if \var{x} is an integer
or real matrix and as a complex matrix otherwise.  
\end{funcdesc}

\begin{funcdesc}{exp}{x}
The exponential function applied elementwise to \var{x}.  
The result is returned as a real matrix if \var{x} is an integer 
or real matrix and as a complex matrix otherwise.  
\end{funcdesc}

\begin{funcdesc}{log}{x}
The natural logarithm applied elementwise to \var{x}.  
The result is returned as a real matrix if \var{x} is an integer
or real matrix and as a complex matrix otherwise.  
Raises an exception when \var{x} is an integer or real matrix with 
nonnegative elements, or a complex matrix with zero elements.
\end{funcdesc}

\begin{funcdesc}{mul}{x, y}
The elementwise product of \var{x} and \var{y}.  
The two matrices must have the same size and type.
\end{funcdesc}

\begin{funcdesc}{div}{x, y}
The elementwise division of \var{x} by \var{y}.  
The two matrices must have the same size and type.
\end{funcdesc}


\section{Randomly Generated Matrices} 
\label{s-random}
The \module{cvxopt.base} module provides two functions \function{normal()} 
and \function{uniform()} for generating
randomly distributed matrices.  The default installation relies on
the pseudo-random number generators in the Python standard 
library \module{random}.  Alternatively, the random number generators in 
the \ulink{GNU Scientific Library (GSL)}{http://www.gnu.org/software/gsl}
can be used, if this option is selected during the installation of CVXOPT.
The random matrix functions based on GSL are faster than the default 
functions based on the \module{random} module.

\begin{funcdesc}{normal}{nrows\optional{, ncols\optional{, 
 mean\optional{, std}}}}
Returns a type \dtc\ matrix of size \var{nrows} by 
\var{ncols} with elements chosen from a normal distribution 
with mean \var{mean} and standard deviation \var{std}.
The default values for the optional arguments are 
\var{ncols}=1, \var{mean}=0.0, \var{std}=1.0.
\end{funcdesc}

\begin{funcdesc}{uniform}{nrows\optional{, ncols\optional{, 
  a\optional{, b}}}}
Returns a type \dtc\ matrix of size \var{nrows} by 
\var{ncols} matrix with elements uniformly distributed 
between \var{a} and \var{b}.
The default values for the optional arguments are 
\var{ncols}=1, \var{a}=0.0, \var{b}=1.0.
\end{funcdesc}

\begin{funcdesc}{setseed}{\optional{value}}
Sets the state of the random number generator.  \var{value} must be an 
integer.  If \var{value} is absent or equal to zero, the value is taken 
from the system clock.  
If the Python random number generators are used, this is equivalent
to \function{random.seed(value)}.
\end{funcdesc}

\begin{funcdesc}{getseed}{}
Returns the current state of the random number generator.  
This function is only available if the GSL random number generators are 
installed.   
(The state of the random number generators in the Python \module{random} 
module can be managed via the functions \function{random.getstate()} and 
\function{random.setstate()}.)
\end{funcdesc}


\section{The NumPy Array Interface} \label{s-array-interface}

The CVXOPT \mtrx\ object is compatible with the \program{NumPy} Array 
Interface, 
which allows Python objects that represent multidimensional 
arrays to exchange data using information stored in the 
attribute \code{\_\_array\_struct\_\_}.  

\textbf{See also:}
\BIT
\item \seelink{http://numpy.scipy.org/array_interface.shtml}
{NumPy Array Interface Specification}{}
\item \seelink{http://numpy.scipy.org}{NumPy home page}{}
\EIT

As already mentioned in section~\ref{s-creating-matrices},
a two-dimensional array object (for example, a \program{NumPy} matrix or
two-dimensional array) can be converted to a CVXOPT \mtrx\ object by using 
the \function{matrix()} constructor.
Conversely, CVXOPT matrices can be used as array-like objects
in \program{NumPy}.  The following example illustrates the 
compatibility of CVXOPT matrices and \program{NumPy} arrays. 
\begin{verbatim}
>>> from cvxopt.base import matrix
>>> a = matrix(range(6), (2,3), 'd')
>>> print a
[ 0.00e+00  2.00e+00  4.00e+00]
[ 1.00e+00  3.00e+00  5.00e+00]
>>> from numpy import array
>>> b = array(a)
>>> b
array([[ 0.  2.  4.]
       [ 1.  3.  5.]])
>>> a*b
array([[  0.   4.  16.]
       [  1.   9.  25.]])
>>> from numpy import mat
>>> c = mat(a)
>>> c
matrix([[ 0.  2.  4.]
        [ 1.  3.  5.]])
>>> a.T * c 
matrix([[  1.,   3.,   5.],
        [  3.,  13.,  23.],
        [  5.,  23.,  41.]])
\end{verbatim}
In the first product, \code{a*b} is interpreted as \program{NumPy} array 
multiplication, \ie, componentwise multiplication.
The second product \code{a.T*c} is interpreted as \program{NumPy} matrix 
multiplication, \ie, standard matrix multiplication.
