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.

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`` 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 efficient sparse implementations in ``mxnet.ndarray.sparse``.
   - If an operator do not occur in the ``mxnet.ndarray.sparse`` namespace, that means the operator does not have an efficient sparse implementation yet. If sparse inputs are passed to such an operator, it will convert inputs to the dense format and fallback to the already available dense implementation.
   - 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.

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

Array rounding

.. autosummary::
    :nosignatures:

    CSRNDArray.round
    CSRNDArray.rint
    CSRNDArray.fix
    CSRNDArray.floor
    CSRNDArray.ceil
    CSRNDArray.trunc

Trigonometric functions

.. autosummary::
    :nosignatures:

    CSRNDArray.sin
    CSRNDArray.tan
    CSRNDArray.arcsin
    CSRNDArray.arctan
    CSRNDArray.degrees
    CSRNDArray.radians

Hyperbolic functions

.. autosummary::
    :nosignatures:

    CSRNDArray.sinh
    CSRNDArray.tanh
    CSRNDArray.arcsinh
    CSRNDArray.arctanh

Exponents and logarithms

.. autosummary::
    :nosignatures:

    CSRNDArray.expm1
    CSRNDArray.log1p

Powers

.. autosummary::
    :nosignatures:

    CSRNDArray.sqrt
    CSRNDArray.square

Joining arrays

.. autosummary::
    :nosignatures:

    concat

Indexing

.. autosummary::
    :nosignatures:

    CSRNDArray.__getitem__
    CSRNDArray.__setitem__
    CSRNDArray.slice

Miscellaneous

.. autosummary::
    :nosignatures:

    CSRNDArray.abs
    CSRNDArray.clip
    CSRNDArray.sign

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.abs
    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
    broadcast_add
    broadcast_sub
    broadcast_mul
    broadcast_div
    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
    adagrad_update

More

.. autosummary::
    :nosignatures:

    make_loss
    stop_gradient
    Embedding
    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, round, rint, fix, floor, ceil, trunc, sin, tan, arcsin, arctan, degrees, radians, sinh, tanh, arcsinh, arctanh, expm1, log1p, sqrt, square, __neg__, sum, mean, norm, square, __getitem__, __setitem__, check_format, abs, clip, sign

.. 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, norm, __getitem__, __setitem__, check_format, retain, abs, clip, sign

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

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

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