Sparse NDArray API

.. currentmodule:: mxnet.ndarray.sparse

Overview

This document lists the routines of the n-dimensional sparse array package:

.. autosummary::
    :nosignatures:

    mxnet.ndarray.sparse

The CSRNDArray and RowSparseNDArray API, defined in the ndarray.sparse package, provides imperative sparse tensor operations on CPU.

An CSRNDArray inherits from NDArray, and represents a two-dimensional, fixed-size array in compressed sparse row format.

>>> x = mx.nd.array([[1, 0], [0, 0], [2, 3]])
>>> csr = x.tostype('csr')
>>> type(csr)
<class 'mxnet.ndarray.sparse.CSRNDArray'>
>>> csr.shape
(3, 2)
>>> csr.data.asnumpy()
array([ 1.  2.  3.], dtype=float32)
>>> csr.indices.asnumpy()
array([0, 0, 1])
>>> csr.indptr.asnumpy()
array([0, 1, 1, 3])
>>> csr.stype
'csr'

A detailed tutorial is available at CSRNDArray - NDArray in Compressed Sparse Row Storage Format.

An RowSparseNDArray inherits from NDArray, and represents a multi-dimensional, fixed-size array in row sparse format.

>>> x = mx.nd.array([[1, 0], [0, 0], [2, 3]])
>>> row_sparse = x.tostype('row_sparse')
>>> type(row_sparse)
<class 'mxnet.ndarray.sparse.RowSparseNDArray'>
>>> row_sparse.data.asnumpy()
array([[ 1.  0.],
       [ 2.  3.]], dtype=float32)
>>> row_sparse.indices.asnumpy()
array([0, 2])
>>> row_sparse.stype
'row_sparse'

A detailed tutorial is available at RowSparseNDArray - NDArray for Sparse Gradient Updates.


.. note:: ``mxnet.ndarray.sparse.RowSparseNDArray`` and ``mxnet.ndarray.sparse.CSRNDArray`` DO NOT support the ``mxnet.gluon`` high-level interface yet.

.. note:: ``mxnet.ndarray.sparse`` is similar to ``mxnet.ndarray`` in some aspects. But the differences are not negligible. For instance:

   - Only a subset of operators in ``mxnet.ndarray`` have specialized implementations in ``mxnet.ndarray.sparse``.
     Operators such as Convolution and broadcasting do not have sparse implementations yet.
   - The storage types (``stype``) of sparse operators' outputs depend on the storage types of inputs.
     By default the operators not available in ``mxnet.ndarray.sparse`` infer "default" (dense) storage type for outputs.
     Please refer to the [API Reference](#api-reference) section for further details on specific operators.
   - GPU support for ``mxnet.ndarray.sparse`` is experimental. Only a few sparse operators are supported on GPU such as ``sparse.dot``.

.. note:: ``mxnet.ndarray.sparse.CSRNDArray`` is similar to ``scipy.sparse.csr_matrix`` in some aspects. But they differ in a few aspects:

   - In MXNet the column indices (``CSRNDArray.indices``) for a given row are expected to be **sorted in ascending order**.
     Duplicate column entries for the same row are not allowed.
   - ``CSRNDArray.data``, ``CSRNDArray.indices`` and ``CSRNDArray.indptr`` always create deep copies, while it's not the case in ``scipy.sparse.csr_matrix``.

In the rest of this document, we first overview the methods provided by the ndarray.sparse.CSRNDArray class and the ndarray.sparse.RowSparseNDArray class, and then list other routines provided by the ndarray.sparse package.

The ndarray.sparse package provides several classes:

.. autosummary::
    :nosignatures:

    CSRNDArray
    RowSparseNDArray

We summarize the interface for each class in the following sections.

The `CSRNDArray` class

Array attributes

.. autosummary::
    :nosignatures:

    CSRNDArray.shape
    CSRNDArray.context
    CSRNDArray.dtype
    CSRNDArray.stype
    CSRNDArray.data
    CSRNDArray.indices
    CSRNDArray.indptr

Array conversion

.. autosummary::
    :nosignatures:

    CSRNDArray.copy
    CSRNDArray.copyto
    CSRNDArray.as_in_context
    CSRNDArray.asscipy
    CSRNDArray.asnumpy
    CSRNDArray.asscalar
    CSRNDArray.astype
    CSRNDArray.tostype

Array inspection

.. autosummary::
    :nosignatures:

    CSRNDArray.check_format

Array creation

.. autosummary::
    :nosignatures:

    CSRNDArray.zeros_like

Array reduction

.. autosummary::
    :nosignatures:

    CSRNDArray.sum
    CSRNDArray.mean
    CSRNDArray.norm

Powers

.. autosummary::
    :nosignatures:

    CSRNDArray.square

Indexing

.. autosummary::
    :nosignatures:

    CSRNDArray.__getitem__
    CSRNDArray.__setitem__
    CSRNDArray.slice

Lazy evaluation

.. autosummary::
    :nosignatures:

    CSRNDArray.wait_to_read

The `RowSparseNDArray` class

Array attributes

.. autosummary::
    :nosignatures:

    RowSparseNDArray.shape
    RowSparseNDArray.context
    RowSparseNDArray.dtype
    RowSparseNDArray.stype
    RowSparseNDArray.data
    RowSparseNDArray.indices

Array conversion

.. autosummary::
    :nosignatures:

    RowSparseNDArray.copy
    RowSparseNDArray.copyto
    RowSparseNDArray.as_in_context
    RowSparseNDArray.asnumpy
    RowSparseNDArray.asscalar
    RowSparseNDArray.astype
    RowSparseNDArray.tostype

Array inspection

.. autosummary::
    :nosignatures:

    RowSparseNDArray.check_format

Array creation

.. autosummary::
    :nosignatures:

    RowSparseNDArray.zeros_like

Array reduction

.. autosummary::
    :nosignatures:

    RowSparseNDArray.norm

Array rounding

.. autosummary::
    :nosignatures:

    RowSparseNDArray.round
    RowSparseNDArray.rint
    RowSparseNDArray.fix
    RowSparseNDArray.floor
    RowSparseNDArray.ceil
    RowSparseNDArray.trunc

Trigonometric functions

.. autosummary::
    :nosignatures:

    RowSparseNDArray.sin
    RowSparseNDArray.tan
    RowSparseNDArray.arcsin
    RowSparseNDArray.arctan
    RowSparseNDArray.degrees
    RowSparseNDArray.radians

Hyperbolic functions

.. autosummary::
    :nosignatures:

    RowSparseNDArray.sinh
    RowSparseNDArray.tanh
    RowSparseNDArray.arcsinh
    RowSparseNDArray.arctanh

Exponents and logarithms

.. autosummary::
    :nosignatures:

    RowSparseNDArray.expm1
    RowSparseNDArray.log1p

Powers

.. autosummary::
    :nosignatures:

    RowSparseNDArray.sqrt
    RowSparseNDArray.square

Indexing

.. autosummary::
    :nosignatures:

    RowSparseNDArray.__getitem__
    RowSparseNDArray.__setitem__
    RowSparseNDArray.retain

Lazy evaluation

.. autosummary::
    :nosignatures:

    RowSparseNDArray.wait_to_read

Miscellaneous

.. autosummary::
    :nosignatures:

    RowSparseNDArray.clip
    RowSparseNDArray.sign

Array creation routines

.. autosummary::
    :nosignatures:

    array
    empty
    zeros
    zeros_like
    csr_matrix
    row_sparse_array
    mxnet.ndarray.load
    mxnet.ndarray.save

Array manipulation routines

Changing array storage type

.. autosummary::
    :nosignatures:

    cast_storage

Indexing routines

.. autosummary::
    :nosignatures:

    slice
    retain
    where

Mathematical functions

Arithmetic operations

.. autosummary::
    :nosignatures:

    elemwise_add
    elemwise_sub
    elemwise_mul
    negative
    dot
    add_n

Trigonometric functions

.. autosummary::
    :nosignatures:

    sin
    tan
    arcsin
    arctan
    degrees
    radians

Hyperbolic functions

.. autosummary::
    :nosignatures:

    sinh
    tanh
    arcsinh
    arctanh

Reduce functions

.. autosummary::
    :nosignatures:

    sum
    mean
    norm

Rounding

.. autosummary::
    :nosignatures:

    round
    rint
    fix
    floor
    ceil
    trunc

Exponents and logarithms

.. autosummary::
    :nosignatures:

    expm1
    log1p

Powers

.. autosummary::
    :nosignatures:

    sqrt
    square

Miscellaneous

.. autosummary::
    :nosignatures:

    abs
    sign

Neural network

Updater

.. autosummary::
    :nosignatures:

    sgd_update
    sgd_mom_update
    adam_update
    ftrl_update
    adagrad_update

.. autosummary::
    :nosignatures:

    make_loss
    stop_gradient
    mxnet.ndarray.contrib.SparseEmbedding
    LinearRegressionOutput
    LogisticRegressionOutput

API Reference


.. autoclass:: mxnet.ndarray.sparse.CSRNDArray
    :members: shape, context, dtype, stype, data, indices, indptr, copy, copyto, as_in_context, asscipy, asnumpy, asscalar, astype, tostype, slice, wait_to_read, zeros_like, __neg__, sum, mean, norm, square, __getitem__, __setitem__, check_format

.. autoclass:: mxnet.ndarray.sparse.RowSparseNDArray
    :members: shape, context, dtype, stype, data, indices, copy, copyto, as_in_context, asnumpy, asscalar, astype, tostype, wait_to_read, zeros_like, round, rint, fix, floor, ceil, trunc, sin, tan, arcsin, arctan, degrees, radians, sinh, tanh, arcsinh, arctanh, expm1, log1p, sqrt, square, __negative__, norm, __getitem__, __setitem__, check_format, retain, clip, sign

.. automodule:: mxnet.ndarray.sparse
    :members:
    :special-members:
    :exclude-members: BaseSparseNDArray, RowSparseNDArray, CSRNDArray

.. automodule:: mxnet.ndarray.sparse
    :members: array, zeros, empty

.. automodule:: mxnet.ndarray
    :members: load, save

Sparse NDArray API

Overview

The CSRNDArray class

Array attributes

Array conversion

Array inspection

Array creation

Array reduction

Powers

Indexing

Lazy evaluation

The RowSparseNDArray class

Array attributes

Array conversion

Array inspection

Array creation

Array reduction

Array rounding

Trigonometric functions

Hyperbolic functions

Exponents and logarithms

Powers

Indexing

Lazy evaluation

Miscellaneous

Array creation routines

Array manipulation routines

Changing array storage type

Indexing routines

Mathematical functions

Arithmetic operations

Trigonometric functions

Hyperbolic functions

Reduce functions

Rounding

Exponents and logarithms

Powers

Miscellaneous

Neural network

Updater

More

API Reference

The `CSRNDArray` class

The `RowSparseNDArray` class