
.. _libdoc_sparse:

===========================================================
:mod:`sparse` -- Symbolic Sparse Matrices [doc TODO]
===========================================================

The sparse module has been used in:

- NLP: Dense linear transformations of sparse vectors.

- Audio: Filterbank in Fourier domain.

The sparse module is less mature than the tensor module.
This documentation is also not mature.

The sparse submodule is not loaded when we import theano. You must import theano.sparse to enable it.

The sparse module provides two kinds of sparse tensors are supported: CSC matrices and CSR matrices.
Operations that are implemented:

grad?

- conversion from sparse <-> dense 
    - theano.sparse.{dense_from_sparse,dense_from_sparse}
    - 

- [un]packing of sparse matrices from indexlists and nonzero elements.
    - packing: theano.sparse.{CRC,CSR}
    - unpacking: theano.sparse.csm_properties

- transpose
    - theano.sparse.transpose

- negation
    - neg

- addition/multiplication (elemwise)
    - theano.sparse.{add,mul}
    - sparse + sparse, sparse + dense, dense + sparse
    - sparse * sparse, sparse * dense, dense * sparse

- StructuredDot
    - with gradient defined such that sparsity pattern is
      constant.  This function is called "structured_dot"
    - theano.sparse.structured_dot and its grad (structured_dot_grad)
    - theano.dot call it.
    - dot(sparse, dense) and dot(dense, sparse), dot(sparse, sparse)

- Dot
    - performs the true dot without special semantics.
    - dot(sparse, dense), dot(dense, sparse), dot(sparse, sparse)
    - When the operation has the form dot(csr_matrix, dense) the gradient of
      this operation can be performed inplace by UsmmCscDense. This leads to
      significant speed-ups.
- Subtensor
    - sparse_variable[N, N], return a tensor scalar
    - sparse_variable[M:N, O:P], return a sparse matrix
    - Don't support [M, N:O] and [M:N, O] as we don't support sparse vector
      and returning a sparse matrix would break the numpy interface.
      Use [M:M+1, N:O] and [M:N, O:O+1] instead.

There are no GPU implementations for sparse matrices implemented in Theano.

Some documentation for sparse has been written
`here <http://deeplearning.net/software/theano/sandbox/sparse.html>`_.


===================================================================
:mod:`sparse` --  Sparse Op
===================================================================

.. module:: sparse
   :platform: Unix, Windows
   :synopsis: Sparse Op
.. moduleauthor:: LISA

.. automodule:: theano.sparse.basic
    :members:

