#acl Patrick Brosi:read,write Björn Buchhold:read,write Claudius Korzen:read,write Axel Lehmann:read,write Raghu Rajan: read,write Johanna Goetz:read,write Natalie Prange:read,write Hannah Bast:read,write All:read

= numpy cheat sheet =

== General ==

TODO (?)

== Matrix construction ==

TODO (Hannah): for dense matrices (matrix vs. array) as well as sparse matrices (csr_matrix((data, indices, indptr)))

== Accessing elements ==

TODO (Hannah): crazy element access magic, single elements, entire rows, sub-matrices

== Matrix operations ==

TODO (Raghu): examples of dot product (dense * dense, dense * sparse, sparse * sparse), usage of both matrix.dot() and * (and how it behaves in different contexts), constant factor adding / multiplication

TODO (Claudius): Element-wise operations like taking log, sqrt. Multiplying two m*n matrices element-wise (for example, to square the entries in a matrix etc...)

== Row- or column-wise operations ==

TODO (Claudius): summing of rows or columns, sorting rows / columns etc

== Useful methods ==

TODO (Natalie): numpy.where, numpy.argsort, numpy.min, numpy.argmin, numpy.round (useful for tests), ...
== Special matrices ==

=== Diagonal matrix ===

Matrix (usually square) in which all entries are zero, except on the main diagonal. Use [[https://docs.scipy.org/doc/numpy-1.10.0/reference/generated/numpy.diag.html | numpy.diag]] to either create a diagonal matrix from a given main diagonal, or extract the diagonal matrix from a given matrix.

{{{
>>> numpy.diag([1,2,3])
array([[1, 0, 0],
       [0, 2, 0],
       [0, 0, 3]])
}}}
{{{
>>> numpy.diag([[1, 5, 4],
                [7, 2, 4],
                [4, 7, 3]])
array([1, 2, 3])
}}}

For a sparse matrix, use [[https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.spdiags.html#scipy.sparse.spdiags|scipy.spare.spdiags]].

=== Identity matrix ===

Special diagonal ''m''*''m'' matrix where all elements on the main diagonal are 1. Read as the '1' of matrix world. For example, a ''n''*''m'' matrix ''A'' multiplied with an ''m''*''m'' identity matrix yields ''A'' again. Use [[https://docs.scipy.org/doc/numpy/reference/generated/numpy.identity.html|numpy.identity(k)]] to create a ''k''*''k'' identity matrix.

{{{
>>> numpy.identity(4)
array([[ 1.,  0.,  0.,  0.],
       [ 0.,  1.,  0.,  0.],
       [ 0.,  0.,  1.,  0.],
       [ 0.,  0.,  0.,  1.]])
}}}

{{{
>>> numpy.array([[1, 2, 3],
                 [3, 4, 3]]).dot(numpy.identity(3))
array([[ 1.,  2.,  3.],
       [ 3.,  4.,  3.]])
}}}

For a sparse matrix, use [[https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.identity.html|scipy.sparse.identity]].

=== Triangular matrix ===

A (square) matrix where all elements below (upper triangle) or above (lower triangle) the main diagonal are zero. 
[[https://docs.scipy.org/doc/numpy/reference/generated/numpy.triu.html|numpy.triu]] creates the upper ({{{u}}}), [[https://docs.scipy.org/doc/numpy/reference/generated/numpy.tril.html|numpy.tril]] the lower ({{{l}}}) triangular matrix from a given matrix.

{{{
>>> numpy.triu([[1, 5, 4],
                [7, 2, 4],
                [4, 7, 3]])
array([[1, 5, 4],
       [0, 2, 4],
       [0, 0, 3]])
}}}


{{{
>>> numpy.tril([[1, 5, 4],
                [7, 2, 4],
                [4, 7, 3]])
array([[1, 0, 0],
       [7, 2, 0],
       [4, 7, 3]])
}}}

For a sparse matrix, use [[https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.triu.html|scipy.sparse.triu]] and [[https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.tril.html|scipy.sparse.tril]].


== Matrix decomposition ==

=== Singular Value Decompostion (SVD) ===

Factorize a matrix ''A'' (''m''*''n'') into three matrices ''U'' (''m'' * ''r''), ''S'' (''r'' * ''r'') and ''V'' (''r'' * ''n'') such that ''A'' = ''U'' * ''S'' * ''V''. Here ''r'' is the [[https://en.wikipedia.org/wiki/Rank_(linear_algebra)| rank]] of ''A''.

Use [[https://docs.scipy.org/doc/numpy/reference/generated/numpy.linalg.svd.html|numpy.linalg.svd]] to do a singular value decomposition for a dense matrix. Use [[https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.svds.html|scipy.sparse.linalg.svds]] for sparse matrices (computes the largest ''k'' singular values for a sparse matrix).

{{{
>>> Uk, Sk, Vk = svds(csr_matrix([[1, 2, 3], [3, 4, 5], [5, 6, 4]], dtype=float), 2)
>>> print("Uk:\n", Uk, "\nSk:\n", Sk, "\nVk:\n", Vk)
U:
 [[ 0.56475636 -0.30288472]
 [ 0.51457155 -0.59799935]
 [-0.64518709 -0.74206309]] 
S:
 [  2.13530566  11.67829513] 
V:
 [[-0.52332762 -0.32001209  0.78975975]
 [-0.49726421 -0.63794803 -0.58800563]]
}}}