sparse

The sparse module defines a dtype for numpy that represents sparse data in n-dimensional coo-format. That is, every array element contains an index into a larger sparse object, and a value, which can be of any numpy supported data type including integers, floating point values and complex data. Additionally, the dtype carries the shape of the sparse object as metadata, which makes the numpy array into an entirely self contained sparse object.

In addition to the dtype, the sparse module provides a range of methods for manipulation of sparse data, such as deduplication of indices, pruning of zeros, sparse addition, and conversion to other sparse or dense data formats.

nutils.sparse.dtype(shape, vtype=<class 'numpy.float64'>)

Numpy data dtype for sparse data.

Returns a structured dtype with fields ‘index’ and ‘value’, where index is again structured with fields ‘i0’, ‘i1’, etc, and value is of type vtype. The indices are of the smallest unsigned integer type that can encode all indices within shape, and carry the shape as metadata.

Parameters
  • shape (tuple of integers.) – Shape of the sparse object.

  • vtype (numpy.dtype or str) – Data dype of the sparse object (i.e. the nonzero values).

Returns

dtype – The sparse dtype.

Return type

numpy.dtype

nutils.sparse.ndim(data)

Dimension of the sparse object.

nutils.sparse.shape(data)

Shape of the sparse object.

nutils.sparse.indices(data)

Tuple of indices of the nonzero values of the sparse object.

nutils.sparse.values(data)

Nonzero values of the sparse object.

nutils.sparse.extract(data)

Tuple of indices, values, and shape of the sparse object.

nutils.sparse.empty(shape, vtype=<class 'numpy.float64'>)

Completely sparse array of given shape and data type.

nutils.sparse.result_type(dtype0, *dtypes)

Sparse analogue of numpy.result_type().

nutils.sparse.dedup(data, inplace=False)

Deduplicate indices.

Dedup sorts data in lexicographical order and sums all values with matching indices such that the returned array has at most one value per sparse index. The sorting happens in place, which means that dedup changes the order of the input argument. Additionally, if inplace is true, the deduplication step reuses the input array’s memory. This may affect the size of the array, which should no longer be used after deduplication in place. In case the input has no duplicates the input array is returned.

>>> from nutils.sparse import dtype, dedup
>>> from numpy import array
>>> A = array([((0,1),.1), ((1,0),.2), ((0,1),.3)], dtype=dtype([2,2]))
>>> dedup(A)
array([((0, 1),  0.4), ((1, 0),  0.2)],
      dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])
nutils.sparse.prune(data, inplace=False)

Prune zero values.

Prune returns a sparse object with all zero values removed. If inplace is true the returned object reuses the input array’s memory. This may affect the size of the array, which should no longer be used after pruning in place. In case the input has no zeros the input array is returned.

>>> from nutils.sparse import dtype, prune
>>> from numpy import array
>>> A = array([((0,1),.1), ((1,0),0), ((0,1),.3)], dtype=dtype([2,2]))
>>> prune(A)
array([((0, 1),  0.1), ((0, 1),  0.3)],
      dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])
nutils.sparse.add(datas)

Add sparse objects.

Returns the sum of a list of sparse objects by concatenating the sparse entries. The returned array is of the data type mandated by Numpy’s promotion rules. In case datas contains only one item of nonzero length and this item has the correct data type, then this array is returned as-is.

>>> from nutils.sparse import dtype, add
>>> from numpy import array
>>> A = array([((0,1),.1), ((1,0),.2)], dtype=dtype([2,2]))
>>> B = array([((0,1),.3)], dtype=dtype([2,2]))
>>> add([A, B])
array([((0, 1),  0.1), ((1, 0),  0.2), ((0, 1),  0.3)],
      dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])
nutils.sparse.toarray(data)

Convert sparse object to a dense array.

>>> from nutils.sparse import dtype, toarray
>>> from numpy import array
>>> A = array([((0,1),.1), ((1,0),.2), ((0,1),.3)], dtype=dtype([2,2]))
>>> toarray(A)
array([[ 0. ,  0.4],
       [ 0.2,  0. ]])
nutils.sparse.fromarray(data)

Convert dense array to sparse object.

>>> from nutils.sparse import dtype, fromarray
>>> from numpy import array
>>> A = array([[0, .4], [.2, 0]])
>>> fromarray(A)
array([((0, 0),  0. ), ((0, 1),  0.4), ((1, 0),  0.2), ((1, 1),  0. )],
      dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])