Table Of Contents

Previous topic

profilemode – profiling Theano functions

Next topic

sparse.sandbox – Sparse Op Sandbox

This Page

sparse – Symbolic Sparse Matrices

In the tutorial section, you can find a sparse tutorial.

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

The sparse module provide the same functionalities as the tensor module. The difference lies under the cover because sparse matrices does not store data in a contiguous array. Note that there are no GPU implementations for sparse matrices implemented in Theano. The sparse module has been used in:

  • NLP: Dense linear transformations of sparse vectors.
  • Audio: Filterbank in Fourier domain.

Compressed Sparse Format

This section tries to explain how information is store for the two sparse formats of SciPy supported by Theano. There is more formats that can be used with SciPy and some documentation about them may be found here.

Theano supports two compressed sparse formats csc and csr, respectively based on columns and rows. They have both the same attributes: data, indices, indptr and shape.

  • The data attribute is a one-dimentionnal ndarray which contains all the non-zero elements of the sparse matrix.
  • The indices and indptr attributes are used to store the position of the data in the sparse matrix.
  • The shape attribute is exactly the same as the shape attribute of a dense (i.e. generic) matrix. It can be explicitly specified at the creation of a sparse matrix if it cannot be infered from the first three attributes.

CSC Matrix

In the Compressed Sparse Column format, indices stands for index inside the column vectors of the matrix and indptr tells where the column starts in the data and in the indices attributes. indptr can be tought as giving the slice which must be applied to the other attribute in order to get each column of the matrix. In other words, slice(indptr[i], indptr[i+1]) correspond to the slice needed to find the i-th column of the matrix in the data and in the indices fields.

The following example builds a matrix and returns its columns. It prints the i-th column, i.e. a list of indices in the column and their corresponding value in the second list.

>>> data = np.asarray([7, 8, 9])
>>> indices = np.asarray([0, 1, 2])
>>> indptr = np.asarray([0, 2, 3, 3])
>>> m = sp.csc_matrix((data, indices, indptr), shape=(3, 3))
>>> print m.toarray()
[[7 0 0]
 [8 0 0]
 [0 9 0]]
>>> i = 0
>>> print m.indices[m.indptr[i]:m.indptr[i+1]], m.data[m.indptr[i]:m.indptr[i+1]]
[0, 1] [7, 8]
>>> i = 1
>>> print m.indices[m.indptr[i]:m.indptr[i+1]], m.data[m.indptr[i]:m.indptr[i+1]]
[2] [9]
>>> i = 2
>>> print m.indices[m.indptr[i]:m.indptr[i+1]], m.data[m.indptr[i]:m.indptr[i+1]]
[] []

CSR Matrix

In the Compressed Sparse Row format, indices stands for index inside the row vectors of the matrix and indptr tells where the row starts in the data and in the indices attributes. indptr can be tought as giving the slice which must be applied to the other attribute in order to get each row of the matrix. In other words, slice(indptr[i], indptr[i+1]) correspond to the slice needed to find the i-th row of the matrix in the data and in the indices fields.

The following example builds a matrix and returns its rows. It prints the i-th row, i.e. a list of indices in the row and their corresponding value in the second list.

>>> data = np.asarray([7, 8, 9])
>>> indices = np.asarray([0, 1, 2])
>>> indptr = np.asarray([0, 2, 3, 3])
>>> m = sp.csr_matrix((data, indices, indptr), shape=(3, 3))
>>> print m.toarray()
[[7 8 0]
 [0 0 9]
 [0 0 0]]
>>> i = 0
>>> print m.indices[m.indptr[i]:m.indptr[i+1]], m.data[m.indptr[i]:m.indptr[i+1]]
[0, 1] [7, 8]
>>> i = 1
>>> print m.indices[m.indptr[i]:m.indptr[i+1]], m.data[m.indptr[i]:m.indptr[i+1]]
[2] [9]
>>> i = 2
>>> print m.indices[m.indptr[i]:m.indptr[i+1]], m.data[m.indptr[i]:m.indptr[i+1]]
[] []

List of Implemented Operations

  • Moving from and to sparse
    • DenseFromSparse and dense_from_sparse. Both grad are implemented. Structured by default.
    • SparseFromDense and csr_from_dense, csc_from_dense. The grad implemented is structured.
    • Theano SparseVariable object have a method toarray() that is the same as dense_from_sparse.
  • Construction of Sparses and their Properties
    • CSM and CSC, CSR to construct a matrix. The grad implemented is regular.
    • CSMProperties and csm_properties(x) to get the properties of a sparse matrix. The grad implemented is regular.
    • csm_indices(x), csm_indptr(x), csm_data(x) and csm_shape(x) or x.shape.
    • sp_ones_like. The grad implemented is regular.
    • sp_zeros_like. The grad implemented is regular.
    • SquareDiagonal and square_diagonal. The grad implemented is regular.
    • ConstructSparseFromList and construct_sparse_from_list. The grad implemented is regular.
  • Cast
    • Cast with bcast, wcast, icast, lcast, fcast, dcast, ccast, and zcast. The grad implemented is regular.
  • Transpose
    • Transpose and transpose. The grad implemented is regular.
  • Basic Arithmetic
    • Neg. The grad implemented is regular.
    • add. The grad implemented is regular.
    • sub. The grad implemented is regular.
    • mul. The grad implemented is regular.
    • col_scale to multiply by a vector along the columns. The grad implemented is structured.
    • row_slace to multiply by a vector along the rows. The grad implemented is structured.
  • Monoid (Element-wise operation with only one sparse input).

    They all have a structured grad.

    • structured_sigmoid
    • structured_exp
    • structured_log
    • structured_pow
    • structured_minimum
    • structured_maximum
    • structured_add
    • sin
    • arcsin
    • tan
    • arctan
    • sinh
    • arcsinh
    • tanh
    • arctanh
    • rad2deg
    • deg2rad
    • rint
    • ceil
    • floor
    • trunc
    • sgn
    • log1p
    • expm1
    • sqr
    • sqrt
  • Dot Product
    • Dot and dot.

      • One of the inputs must be sparse, the other sparse or dense.
      • The grad implemented is regular.
      • No C code for perform and no C code for grad.
      • Return a dense for perform and a dense for grad.
    • StructuredDot and structured_dot.

      • The first input is sparse, the second can be sparse or dense.
      • The grad implemented is structured.
      • C code for perform and grad.
      • Return a dense for perforn and a sparse for grad.
    • TrueDot and true_dot.

      • The first input is sparse, the second can be sparse or dense.
      • The grad implemented is regular.
      • No C code for perform and no C code for grad.
      • Return a Sparse for perform and a Sparse for grad.
      • Flags trough constructor can change the output of grad to be dense if the second input of the op is dense.
    • SamplingDot and sampling_dot.

      • Both input must be dense.
      • The grad implemented is structured for p.
      • Sample of the dot and sample of the gradient.
      • C code for perform but not for grad.
      • Return sparse for perform and grad.
    • Usmm and usmm.

      • You shouldn’t insert this op yourself!
        • There is optimization that transform a Dot to Usmm when possible.
      • This op is the equivalent of gemm for sparse dot.

      • There is no grad implemented for this op and this is not needed as you don’t insert it yourself.

      • One of the inputs must be sparse, the other sparse or dense.

      • Return a dense for perform

  • Slice Operations
    • sparse_variable[N, N], return a tensor scalar. There is no grad implemented for this operation.
    • sparse_variable[M:N, O:P], return a sparse matrix There is no grad implemented for this operation.
    • Sparse variable 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.
    • Diag and diag. The grad implemented is regular.
  • Concatenation
    • HStack and hstack. The grad implemented is regular.
    • VStack and vstack. The grad implemented is regular.
  • Probability

    There is no grad implemented for these operations.

    • Poisson and poisson
    • Binomial and csc_fbinomial, csc_dbinomial csr_fbinomial, csr_dbinomial
    • Multinomial and multinomial
  • Internal Representation

    They all have a regular grad implemented.

  • To help testing

sparse – Sparse Op

Classes for handling sparse matrices.

To read about different sparse formats, see http://www-users.cs.umn.edu/~saad/software/SPARSKIT/paper.ps

class theano.sparse.basic.AddSD(inplace=False, *args, **kwargs)

Add a sparse and a dense matrix.

Parameters:
  • x – A sparse matrix.
  • y – A dense matrix
Returns:

x`+`y

Note:

The grad implemented is structured on x.

class theano.sparse.basic.AddSS(use_c_code='g++')

Add tw sparse matrix.

Parameters:
  • x – A sparse matrix.
  • y – A sparse matrix
Returns:

x`+`y

Note:

The grad implemented is regular, i.e. not structured.

class theano.sparse.basic.AddSSData(use_c_code='g++')

Add two sparse matrices assuming they have the same sparsity pattern.

Parameters:
  • x – Sparse matrix.
  • y – Sparse matrix.
Returns:

The sum of the two sparse matrix element wise.

Note:

x and y are assumed to have the same sparsity pattern.

Note:

The grad implemented is structured.

class theano.sparse.basic.CSM(format, kmap=None)

Construct a CSC or CSR matrix from the internal representation.

The format for the sparse array can be specified through the constructor. Also, kmap could be set through to constructor to specified the parts of the parameter data the op should use to construct the sparse matrix. Fancy indexing with numpy.ndarray should be used for this purpose.

Parameters:
  • data – One dimensional tensor representing the data of the sparse to construct.
  • indices – One dimensional tensor of integers representing the indices of the sparse matrix to construct.
  • indptr – One dimensional tensor of integers representing the indice pointer for the sparse matrix to construct.
  • shape – One dimensional tensor of integers representing the shape of the sparse matrix to construct.
Returns:

A sparse matrix having the properties specified by the inputs.

Note:

The grad method returns a dense vector, so it provides a regular grad.

kmap = None

Indexing to speficied what part of the data parameter should be use to construct the sparse matrix.

class theano.sparse.basic.CSMProperties(kmap=None)

Extract all of .data, .indices, .indptr and .shape.

For specific field, csm_data, csm_indices, csm_indptr and csm_shape are provided. Also, kmap could be set through to constructor to specified the parts of the parameter data the op should return.Fancy indexing with numpy.ndarray should be used for this purpose.

Parameters:csm – Sparse matrix in CSR or CSC format.
Returns:(data, indices, indptr, shape), the properties of csm.
Note:The grad implemented is regular, i.e. not structured. infer_shape method is not available for this op.
kmap = None

Indexing to speficied what part of the data parameter should be use to construct the sparse matrix.

class theano.sparse.basic.Cast(out_type)

Cast sparse variable to the desired dtype.

Parameters:x – Sparse matrix.
Returns:Same as x but having out_type as dtype.
Note:The grad implemented is regular, i.e. not structured.
class theano.sparse.basic.ConstructSparseFromList(use_c_code='g++')

Constructs a sparse matrix out of a list of 2-D matrix rows

Note:The grad implemented is regular, i.e. not structured.
make_node(x, values, ilist)
Parameters:
  • x – a dense matrix that specify the output shape.
  • values – a dense matrix with the values to use for output.
  • ilist – a dense vector with the same length as the number of rows of values. It specify where in the output to put the corresponding rows.

This create a sparse matrix with the same shape as x. Its values are the rows of values moved. Pseudo-code:

output = csc_matrix.zeros_like(x, dtype=values.dtype)
for in_idx, out_idx in enumerate(ilist):
    output[out_idx] = values[in_idx]
class theano.sparse.basic.DenseFromSparse(structured=True)

Convert a sparse matrix to a dense one.

Parameters:x – A sparse matrix.
Returns:A dense matrix, the same as x.
Note:The grad implementation can be controlled through the constructor via the structured parameter. True will provide a structured grad while False will provide a regular grad. By default, the grad is structured.
class theano.sparse.basic.Diag(use_c_code='g++')

Extract the diagonal of a square sparse matrix as a dense vector.

Parameters:x – A square sparse matrix in csc format.
Returns:A dense vector representing the diagonal elements.
Note:The grad implemented is regular, i.e. not structured, since the output is a dense vector.
class theano.sparse.basic.Dot(use_c_code='g++')

Operation for efficiently calculating the dot product when one or all operands is sparse. Supported format are CSC and CSR. The output of the operation is dense.

Parameters:
  • x – sparse or dense matrix variable.
  • y – sparse or dense matrix variable.
Returns:

The dot product x.`y` in a dense format.

Note:

The grad implemented is regular, i.e. not structured.

Note:

At least one of x or y must be a sparse matrix.

Note:

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.

class theano.sparse.basic.EnsureSortedIndices(inplace)

Resort indices of a sparse matrix.

CSR column indices are not necessarily sorted. Likewise for CSC row indices. Use ensure_sorted_indices when sorted indices are required (e.g. when passing data to other libraries).

Parameters:x – A sparse matrix.
Returns:The same as x with indices sorted.
Note:The grad implemented is regular, i.e. not structured.
class theano.sparse.basic.GetItem2d(use_c_code='g++')

Implement a subtensor of sparse variable and that return a sparse matrix.

If you want to take only one element of a sparse matrix see GetItemScalar that return a tensor scalar.

Note

Subtensor selection always returns a matrix, so indexing with [a:b, c:d] is forced. If one index is a scalar. For instance, x[a:b, c] and x[a, b:c], generate an error. Use instead x[a:b, c:c+1] and x[a:a+1, b:c].

The above indexing methods are not supported because the return value would be a sparse matrix rather than a sparse vector, which is a deviation from numpy indexing rule. This decision is made largely for keeping the consistency between numpy and theano. Subjected to modification when sparse vector is supported.

Parameters:
  • x – Sparse matrix.
  • index – Tuple of slice object.
Returns:

The slice corresponding in x.

Note:

The grad is not implemented for this op.

class theano.sparse.basic.GetItemScalar(use_c_code='g++')

Implement a subtensor of a sparse variable that take two scalar as index and return a scalar.

If you want to take a slice of a sparse matrix see GetItem2d that return a sparse matrix.

Parameters:
  • x – Sparse matrix.
  • index – Tuple of scalar..
Returns:

The item corresponding in x.

Note:

The grad is not implemented for this op.

class theano.sparse.basic.HStack(format=None, dtype=None)

Stack sparse matrices horizontally (column wise).

Parameters:
  • blocks – Sequence of sparse array of compatible shape.
  • format – String representing the output format. Default is csc.
  • dtype – Output dtype. Must be specified.
Returns:

The concatenation of the sparse arrays column wise.

Note:

The number of line of the sparse matrix must agree.

Note:

The grad implemented is regular, i.e. not structured.

class theano.sparse.basic.MulSD(use_c_code='g++')

Elementwise multiply a sparse and a dense matrix.

Parameters:
  • x – A sparse matrix.
  • y – A dense matrix.
Returns:

x * y

Note:

The grad is regular, i.e. not structured..

class theano.sparse.basic.MulSS(use_c_code='g++')

Elementwise multiply a sparse and a sparse.

Parameters:
  • x – A sparse matrix.
  • y – A sparse matrix.
Returns:

x * y

Note:

At least one of x and y must be a sparse matrix.

Note:

The grad implemented is regular, i.e. not structured.

class theano.sparse.basic.MulSV(use_c_code='g++')

Multiplication of sparse matrix by a broadcasted dense vector element wise.

Parameters:
  • x – Sparse matrix to multiply.
  • y – Tensor broadcastable vector.
Return:

The product x * y element wise.

Note:

The grad implemented is regular, i.e. not structured.

class theano.sparse.basic.Neg(use_c_code='g++')

Return the negation of the sparse matrix.

Parameters:x – Sparse matrix.
Returns:-x.
Note:The grad is regular, i.e. not structured.
class theano.sparse.basic.Remove0(inplace=False, *args, **kwargs)

Remove explicit zeros from a sparse matrix.

Parameters:x – Sparse matrix.
Returns:Exactly x but with a data attribute exempt of zeros.
Note:The grad implemented is regular, i.e. not structured.
class theano.sparse.basic.SamplingDot(use_c_code='g++')

Operand for calculating the dot product dot(x, y.T) = z when you only want to calculate a subset of z.

It is equivalent to p o (x . y.T) where o is the element-wise product, x and y operands of the dot product and p is a matrix that contains 1 when the corresponding element of z should be calculated and 0 when it shouldn’t. Note that SamplingDot has a different interface than dot because SamplingDot requires x to be a m`x`k matrix while y is a n`x`k matrix instead of the usual k`x`n matrix.

Note

It will work if the pattern is not binary value, but if the pattern doesn’t have a high sparsity proportion it will be slower then a more optimized dot followed by a normal elemwise multiplication.

Parameters:
  • x – Tensor matrix.
  • y – Tensor matrix.
  • p – Sparse matrix in csr format.
Returns:

A dense matrix containing the dot product of x by y.T only where p is 1.

Note:

The grad implemented is regular, i.e. not structured.

class theano.sparse.basic.SpSum(axis=None, sparse_grad=True)

Calculate the sum of a sparse matrix along a specify axis.

It operates a reduction along the axis specified. When axis is None, it is apply along all axis.

Parameters:
  • x – Sparse matrix.
  • axis – Axis along the sum is apply. Integers or None.
  • sparse_gradTrue to have a structured grad. Boolean.
Returns:

The sum of x in a dense format.

Note:

The grad implementation is controlled with the sparse_grad parameter. True will provide a structured grad and False will provide a regular grad. For both choice, the grad return a sparse matrix having the same format as x.

Note:

This op does not return a sparse matrix, but a dense tensor matrix.

class theano.sparse.basic.SparseFromDense(format)

Convert a dense matrix to a sparse matrix.

To convert in CSR format, use csr_from_dense and to convert in CSC format, use csc_from_dense.

Parameters:x – A dense matrix.
Returns:The same as x in a sparse matrix format.
Note:The grad implementation is regular, i.e. not structured.
Note:The output sparse format can also be controlled via the format parameter in the constructor.
class theano.sparse.basic.SquareDiagonal(use_c_code='g++')

Return a square sparse (csc) matrix whose diagonal is given by the dense vector argument.

Parameters:x – Dense vector for the diagonal.
Returns:A sparse matrix having x as diagonal.
Note:The grad implemented is regular, i.e. not structured.
class theano.sparse.basic.StructuredAddSV(use_c_code='g++')

Structured addition of a sparse matrix and a dense vector. The elements of the vector are are only added to the corresponding non-zero elements. Therefore, this operation outputs another sparse matrix.

Parameters:
  • x – Sparse matrix.
  • y – Tensor type vector.
Returns:

A sparse matrix containing the addition of the vector to the data of the sparse matrix.

Note:

The grad implemented is structured since the op is structured.

class theano.sparse.basic.StructuredDot(use_c_code='g++')

Structured Dot is like dot, except that only the gradient wrt non-zero elements of the sparse matrix a are calculated and propagated.

The output is presumed to be a dense matrix, and is represented by a TensorType instance.

Parameters:
  • a – A sparse matrix.
  • b – A sparse or dense matrix.
Returns:

The dot product of a and b as a dense matrix.

Note:

The grad implemented is structured.

class theano.sparse.basic.Transpose(use_c_code='g++')

Return the transpose of the sparse matrix.

Parameters:x – Sparse matrix.
Returns:x transposed.
Note:The returned matrix will not be in the same format. csc matrix will be changed in csr matrix and csr matrix in csc matrix.
Note:The grad is regular, i.e. not structured.
class theano.sparse.basic.TrueDot(grad_preserves_dense=True)

Calculate the true dot operation between two matrices.

TrueDot is different of StructuredDot for sparse matrix since the grad of TrueDot is regular, i.e. not structured.

The parameter grad_preserves_dense, controlled by the constructor, is a boolean flags to controls whether gradients with respect to inputs are converted to dense matrices when the corresponding input y is dense (not in a L{SparseVariable} wrapper). This is generally a good idea when L{Dot} is in the middle of a larger graph, because the types of gy will match that of y. This conversion might be inefficient if the gradients are graph outputs though, hence this mask.

Parameters:
  • x – Sparse matrix for the left operand.
  • y – Sparse or dense matrix for the right operand.
Returns:

The dot product x . y in a sparse matrix.

Note:
  • The grad implemented is regular, i.e. not structured.
class theano.sparse.basic.Usmm(use_c_code='g++')

Performs the expression is alpha * x y + z.

Parameters:
  • x – Matrix variable.
  • y – Matrix variable.
  • z – Dense matrix.
  • alpha – A tensor scalar.
Returns:

The dense matrix resulting from alpha * x y + z.

Note:

The grad is not implemented for this op.

Note:

At least one of x or y must be a sparse matrix.

class theano.sparse.basic.VStack(format=None, dtype=None)

Stack sparse matrices vertically (row wise).

Parameters:
  • blocks – Sequence of sparse array of compatible shape.
  • format – String representing the output format. Default is csc.
  • dtype – Output dtype. Must be specified.
Returns:

The concatenation of the sparse arrays row wise.

Note:

The number of column of the sparse matrix must agree.

Note:

The grad implemented is regular, i.e. not structured.

theano.sparse.basic.add(x, y)

Add two matrices, at least one of which is sparse.

This method will provide the right op according to the inputs.

Parameters:
  • x – A matrix variable.
  • y – A matrix variable.
Returns:

x + y

Note:

At least one of x and y must be a sparse matrix.

Note:

The grad will be structured only when one of the variable will be a dense matrix.

theano.sparse.basic.as_sparse(x, name=None)

Wrapper around SparseVariable constructor to construct a Variable with a sparse matrix with the same dtype and format.

Parameters:x – A sparse matrix.
Returns:SparseVariable version of x.
theano.sparse.basic.as_sparse_or_tensor_variable(x, name=None)

Same as as_sparse_variable but If we can’t make a sparse variable, we try to make a tensor variable. format.

Parameters:x – A sparse matrix.
Returns:SparseVariable or TensorVariable version of x.
theano.sparse.basic.as_sparse_variable(x, name=None)

Wrapper around SparseVariable constructor to construct a Variable with a sparse matrix with the same dtype and format.

Parameters:x – A sparse matrix.
Returns:SparseVariable version of x.
theano.sparse.basic.clean(x)

Remove explicit zeros from a sparse matrix, and resort indices.

CSR column indices are not necessarily sorted. Likewise for CSC row indices. Use clean when sorted indices are required (e.g. when passing data to other libraries) and to ensure there is no zeros in the data.

Parameters:x – A sparse matrix.
Returns:The same as x with indices sorted and zeros removed.
Note:The grad implemented is regular, i.e. not structured.
theano.sparse.basic.col_scale(x, s)

Scale each columns of a sparse matrix by the corresponding element of a dense vector

Parameters:
  • x – A sparse matrix.
  • s – A dense vector with length equal to the number of columns of x.
Returns:

A sparse matrix in the same format as x which each column had been multiply by the corresponding element of s.

Note:

The grad implemented is structured.

theano.sparse.basic.csm_data(csm)

return the data field of the sparse variable.

theano.sparse.basic.csm_indices(csm)

return the indices field of the sparse variable.

theano.sparse.basic.csm_indptr(csm)

return the indptr field of the sparse variable.

theano.sparse.basic.csm_properties = <theano.sparse.basic.CSMProperties object at 0x7fa2c7ad4210>

An CSMProperties object instance. It return the fields data, indices, indptr and shape of the sparse varible. Together they specify completly the the sparse variable when we know its format. Example:

the_data, the_indices, the_indptr, the_shape = csm_properties(a_sparse_var)
theano.sparse.basic.csm_shape(csm)

return the shape field of the sparse variable.

theano.sparse.basic.dot(x, y)

Operation for efficiently calculating the dot product when one or all operands is sparse. Supported format are CSC and CSR. The output of the operation is dense.

Parameters:
  • x – Matrix variable.
  • y – Matrix variable.
Returns:

The dot product x.`y` in a dense format.

Note:

The grad implemented is regular, i.e. not structured.

Note:

At least one of x or y must be a sparse matrix.

theano.sparse.basic.hstack(blocks, format=None, dtype=None)

Stack sparse matrices horizontally (column wise).

This wrap the method hstack from scipy.

Parameters:
  • blocks – List of sparse array of compatible shape.
  • format – String representing the output format. Default is csc.
  • dtype – Output dtype.
Returns:

The concatenation of the sparse array column wise.

Note:

The number of line of the sparse matrix must agree.

Note:

The grad implemented is regular, i.e. not structured.

theano.sparse.basic.mul(x, y)

Multiply elementwise two matrices, at least one of which is sparse.

This method will provide the right op according to the inputs.

Parameters:
  • x – A matrix variable.
  • y – A matrix variable.
Returns:

x + y

Note:

At least one of x and y must be a sparse matrix.

Note:

The grad is regular, i.e. not structured.

theano.sparse.basic.row_scale(x, s)

Scale each row of a sparse matrix by the corresponding element of a dense vector

Parameters:
  • x – A sparse matrix.
  • s – A dense vector with length equal to the number of rows of x.
Returns:

A sparse matrix in the same format as x which each row had been multiply by the corresponding element of s.

Note:

The grad implemented is structured.

theano.sparse.basic.sp_ones_like(x)

Construct a sparse matrix of ones with the same sparsity pattern.

Parameters:x – Sparse matrix to take the sparsity pattern.
Returns:The same as x with data changed for ones.
theano.sparse.basic.sp_zeros_like(x)

Construct a sparse matrix of zeros.

Parameters:x – Sparse matrix to take the shape.
Returns:The same as x with zero entries for all element.
theano.sparse.basic.structured_dot(x, y)

Structured Dot is like dot, except that only the gradient wrt non-zero elements of the sparse matrix a are calculated and propagated.

The output is presumed to be a dense matrix, and is represented by a TensorType instance.

Parameters:
  • a – A sparse matrix.
  • b – A sparse or dense matrix.
Returns:

The dot product of a and b.

Note:

The grad implemented is structured.

theano.sparse.basic.sub(x, y)

Substact two matrices, at least one of which is sparse.

This method will provide the right op according to the inputs.

Parameters:
  • x – A matrix variable.
  • y – A matrix variable.
Returns:

x - y

Note:

At least one of x and y must be a sparse matrix.

Note:

The grad will be structured only when one of the variable will be a dense matrix.

theano.sparse.basic.true_dot(x, y, grad_preserves_dense=True)

Operation for efficiently calculating the dot product when one or all operands is sparse. Supported format are CSC and CSR. The output of the operation is sparse.

Parameters:
  • x – Matrix variable.
  • y – Matrix variable.
  • grad_preserves_dense – if True and one on the input is dense, make the output dense.
Returns:

The dot product x.`y` in a sparse format.

theano.sparse.basic.verify_grad_sparse(op, pt, structured=False, *args, **kwargs)

Wrapper for theano.test.unittest_tools.py:verify_grad wich converts sparse variables back and forth.

Parameters:
  • op – Op to check.
  • pt – List of inputs to realize the tests.
  • structured – True to tests with a structured grad, False otherwise.
  • args – Other verify_grad parameters if any.
  • kwargs – Other verify_grad keywords if any.
Returns:

None

theano.sparse.basic.vstack(blocks, format=None, dtype=None)

Stack sparse matrices vertically (row wise).

This wrap the method vstack from scipy.

Parameters:
  • blocks – List of sparse array of compatible shape.
  • format – String representing the output format. Default is csc.
  • dtype – Output dtype.
Returns:

The concatenation of the sparse array row wise.

Note:

The number of column of the sparse matrix must agree.

Note:

The grad implemented is regular, i.e. not structured.

theano.sparse.tests.test_basic.sparse_random_inputs(format, shape, n=1, out_dtype=None, p=0.5, gap=None, explicit_zero=False, unsorted_indices=False)

Return a tuple containing everything needed to perform a test.

If out_dtype is None, theano.config.floatX is used.

Parameters:
  • format – Sparse format.
  • shape – Shape of data.
  • n – Number of variable.
  • out_dtype – dtype of output.
  • p – Sparsity proportion.
  • gap – Tuple for the range of the random sample. When length is 1, it is assumed to be the exclusive max, when gap = (a, b) it provide a sample from [a, b[. If None is used, it provide [0, 1] for float dtypes and [0, 50[ for integer dtypes.
  • explicit_zero – When True, we add explicit zero in the returned sparse matrix
  • unsorted_indices – when True, we make sure there is unsorted indices in the returned sparse matrix.
Returns:

(variable, data) where both variable and data are list.

Note:

explicit_zero and unsorted_indices was added in Theano 0.6rc4