
.. _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 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), dot(dense, sparse), dot(sparse, sparse)

Subtensor selection (aka. square-bracket notation, aka indexing) is not implemented, but the
CSR and CSC datastructures support effecient implementations.

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>`_.

