Overview¶

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

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)

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

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

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:

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

The CSRNDArray class¶

The RowSparseNDArray class¶

Array creation routines¶

Array manipulation routines¶

Mathematical functions¶

Neural network¶

API Reference¶

class mxnet.ndarray.sparse.CSRNDArray(handle, writable=True)[source]¶

A sparse representation of 2D NDArray in the Compressed Sparse Row format.

A CSRNDArray represents an NDArray as three separate arrays: data, indptr and indices. It uses the CSR representation where the column indices for row i are stored in indices[indptr[i]:indptr[i+1]] and their corresponding values are stored in data[indptr[i]:indptr[i+1]].

The column indices for a given row are expected to be sorted in ascending order. Duplicate column entries for the same row are not allowed.

Example

>>> a = mx.nd.array([[0, 1, 0], [2, 0, 0], [0, 0, 0], [0, 0, 3]])
>>> a = a.tostype('csr')
>>> a.data.asnumpy()
array([ 1.,  2.,  3.], dtype=float32)
>>> a.indices.asnumpy()
array([1, 0, 2])
>>> a.indptr.asnumpy()
array([0, 1, 2, 2, 3])

See also

csr_matrix

Several ways to construct a CSRNDArray

__getitem__(key)[source]¶

x.__getitem__(i) <=> x[i]

Returns a newly created NDArray based on the indexing key.

Parameters:	key (int or slice) – Indexing key.

Examples

>>> indptr = np.array([0, 2, 3, 6])
>>> indices = np.array([0, 2, 2, 0, 1, 2])
>>> data = np.array([1, 2, 3, 4, 5, 6])
>>> a = mx.nd.sparse.csr_matrix((data, indices, indptr), shape=(3, 3))
>>> a.asnumpy()
array([[ 1.,  0.,  2.],
       [ 0.,  0.,  3.],
       [ 4.,  5.,  6.]], dtype=float32)
>>> a[1:2].asnumpy()
array([[ 0.,  0.,  3.]], dtype=float32)
>>> a[1].asnumpy()
array([[ 0.,  0.,  3.]], dtype=float32)
>>> a[-1].asnumpy()
array([[ 4.,  5.,  6.]], dtype=float32)

__setitem__(key, value)[source]¶

x.__setitem__(i, y) <=> x[i]=y

Set self[key] to value. Only slice key [:] is supported.

Parameters:	key (slice) – The indexing key. value (NDArray or CSRNDArray or numpy.ndarray) – The value to set.

Examples

>>> src = mx.nd.sparse.zeros('csr', (3,3))
>>> src.asnumpy()
array([[ 0.,  0.,  0.],
       [ 0.,  0.,  0.],
       [ 0.,  0.,  0.]], dtype=float32)
>>> # assign CSRNDArray with same storage type
>>> x = mx.nd.ones((3,3)).tostype('csr')
>>> x[:] = src
>>> x.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> # assign NDArray to CSRNDArray
>>> x[:] = mx.nd.ones((3,3)) * 2
>>> x.asnumpy()
array([[ 2.,  2.,  2.],
       [ 2.,  2.,  2.],
       [ 2.,  2.,  2.]], dtype=float32)

indices¶

A deep copy NDArray of the indices array of the CSRNDArray. This generates a deep copy of the column indices of the current csr matrix.

Returns:	This CSRNDArray’s indices array.
Return type:	NDArray

indptr¶

A deep copy NDArray of the indptr array of the CSRNDArray. This generates a deep copy of the indptr of the current csr matrix.

Returns:	This CSRNDArray’s indptr array.
Return type:	NDArray

data¶

A deep copy NDArray of the data array of the CSRNDArray. This generates a deep copy of the data of the current csr matrix.

Returns:	This CSRNDArray’s data array.
Return type:	NDArray

tostype(stype)[source]¶

Return a copy of the array with chosen storage type.

Returns:	A copy of the array with the chosen storage stype
Return type:	NDArray or CSRNDArray

copyto(other)[source]¶

Copies the value of this array to another array.

If other is a NDArray or CSRNDArray object, then other.shape and self.shape should be the same. This function copies the value from self to other.

If other is a context, a new CSRNDArray will be first created on the target context, and the value of self is copied.

Parameters:	other (NDArray or CSRNDArray or Context) – The destination array or context.
Returns:	The copied array. If other is an NDArray or CSRNDArray, then the return value and other will point to the same NDArray or CSRNDArray.
Return type:	NDArray or CSRNDArray

asscipy()[source]¶

Returns a scipy.sparse.csr.csr_matrix object with value copied from this array

Examples

>>> x = mx.nd.sparse.zeros('csr', (2,3))
>>> y = x.asscipy()
>>> type(y)

>>> y
<2x3 sparse matrix of type ''
with 0 stored elements in Compressed Sparse Row format>

__neg__()¶

x.__neg__(y) <=> -x

as_in_context(context)¶

Returns an array on the target device with the same value as this array.

If the target context is the same as self.context, then self is returned. Otherwise, a copy is made.

Parameters:	context (Context) – The target context.
Returns:	The target array.
Return type:	NDArray, CSRNDArray or RowSparseNDArray

Examples

>>> x = mx.nd.ones((2,3))
>>> y = x.as_in_context(mx.cpu())
>>> y is x
True
>>> z = x.as_in_context(mx.gpu(0))
>>> z is x
False

asnumpy()¶

Return a dense numpy.ndarray object with value copied from this array

asscalar()¶

Returns a scalar whose value is copied from this array.

This function is equivalent to self.asnumpy()[0]. This NDArray must have shape (1,).

Examples

>>> x = mx.nd.ones((1,), dtype='int32')
>>> x.asscalar()
1
>>> type(x.asscalar())

astype(dtype, copy=True)¶

Returns a copy of the array after casting to a specified type. :param dtype: The type of the returned array. :type dtype: numpy.dtype or str :param copy: Default True. By default, astype always returns a newly

allocated ndarray on the same context. If this is set to False, and the dtype requested is the same as the ndarray’s dtype, the ndarray is returned instead of a copy.

Examples

>>> x = mx.nd.sparse.zeros('row_sparse', (2,3), dtype='float32')
>>> y = x.astype('int32')
>>> y.dtype

check_format(full_check=True)¶

Check whether the NDArray format is valid.

Parameters:	full_check (bool, optional) – If True, rigorous check, O(N) operations. Otherwise basic check, O(1) operations (default True).

context¶

Device context of the array.

Examples

>>> x = mx.nd.array([1, 2, 3, 4])
>>> x.context
cpu(0)
>>> type(x.context)

>>> y = mx.nd.zeros((2,3), mx.gpu(0))
>>> y.context
gpu(0)

copy()¶

Makes a copy of this NDArray, keeping the same context.

Returns:	The copied array
Return type:	NDArray, CSRNDArray or RowSparseNDArray

Examples

>>> x = mx.nd.ones((2,3))
>>> y = x.copy()
>>> y.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)

dtype¶

Data-type of the array’s elements.

Returns:	This NDArray’s data type.
Return type:	numpy.dtype

Examples

>>> x = mx.nd.zeros((2,3))
>>> x.dtype

>>> y = mx.nd.zeros((2,3), dtype='int32')
>>> y.dtype

mean(*args, **kwargs)¶

Convenience fluent method for mean().

The arguments are the same as for mean(), with this array as data.

norm(*args, **kwargs)¶

Convenience fluent method for norm().

The arguments are the same as for norm(), with this array as data.

shape¶

Tuple of array dimensions.

Examples

>>> x = mx.nd.array([1, 2, 3, 4])
>>> x.shape
(4L,)
>>> y = mx.nd.zeros((2, 3, 4))
>>> y.shape
(2L, 3L, 4L)

slice(*args, **kwargs)¶

Convenience fluent method for slice().

The arguments are the same as for slice(), with this array as data.

square(*args, **kwargs)¶

Convenience fluent method for square().

The arguments are the same as for square(), with this array as data.

stype¶

Storage-type of the array.

sum(*args, **kwargs)¶

Convenience fluent method for sum().

The arguments are the same as for sum(), with this array as data.

wait_to_read()¶

Waits until all previous write operations on the current array are finished.

This method guarantees that all previous write operations that pushed into the backend engine for execution are actually finished.

Examples

>>> import time
>>> tic = time.time()
>>> a = mx.nd.ones((1000,1000))
>>> b = mx.nd.dot(a, a)
>>> print(time.time() - tic) 
0.003854036331176758
>>> b.wait_to_read()
>>> print(time.time() - tic) 
0.0893700122833252

zeros_like(*args, **kwargs)¶

Convenience fluent method for zeros_like().

The arguments are the same as for zeros_like(), with this array as data.

class mxnet.ndarray.sparse.RowSparseNDArray(handle, writable=True)[source]¶

A sparse representation of a set of NDArray row slices at given indices.

A RowSparseNDArray represents a multidimensional NDArray using two separate arrays: data and indices. The number of dimensions has to be at least 2.

• data: an NDArray of any dtype with shape [D0, D1, ..., Dn].
• indices: a 1-D int64 NDArray with shape [D0] with values sorted in ascending order.

The indices stores the indices of the row slices with non-zeros, while the values are stored in data. The corresponding NDArray dense represented by RowSparseNDArray rsp has

dense[rsp.indices[i], :, :, :, ...] = rsp.data[i, :, :, :, ...]

>>> dense.asnumpy()
array([[ 1.,  2., 3.],
       [ 0.,  0., 0.],
       [ 4.,  0., 5.],
       [ 0.,  0., 0.],
       [ 0.,  0., 0.]], dtype=float32)
>>> rsp = dense.tostype('row_sparse')
>>> rsp.indices.asnumpy()
array([0, 2], dtype=int64)
>>> rsp.data.asnumpy()
array([[ 1.,  2., 3.],
       [ 4.,  0., 5.]], dtype=float32)

A RowSparseNDArray is typically used to represent non-zero row slices of a large NDArray of shape [LARGE0, D1, .. , Dn] where LARGE0 >> D0 and most row slices are zeros.

RowSparseNDArray is used principally in the definition of gradients for operations that have sparse gradients (e.g. sparse dot and sparse embedding).

See also

row_sparse_array

Several ways to construct a RowSparseNDArray

__getitem__(key)[source]¶

x.__getitem__(i) <=> x[i]

Returns a sliced view of this array.

Parameters:	key (slice) – Indexing key.

Examples

>>> x = mx.nd.sparse.zeros('row_sparse', (2, 3))
>>> x[:].asnumpy()
array([[ 0.,  0.,  0.],
       [ 0.,  0.,  0.]], dtype=float32)

__setitem__(key, value)[source]¶

x.__setitem__(i, y) <=> x[i]=y

Set self[key] to value. Only slice key [:] is supported.

Parameters:	key (slice) – The indexing key. value (NDArray or numpy.ndarray) – The value to set.

Examples

>>> src = mx.nd.row_sparse([[1, 0, 2], [4, 5, 6]], [0, 2], (3,3))
>>> src.asnumpy()
array([[ 1.,  0.,  2.],
       [ 0.,  0.,  0.],
       [ 4.,  5.,  6.]], dtype=float32)
>>> # assign RowSparseNDArray with same storage type
>>> x = mx.nd.sparse.zeros('row_sparse', (3,3))
>>> x[:] = src
>>> x.asnumpy()
array([[ 1.,  0.,  2.],
       [ 0.,  0.,  0.],
       [ 4.,  5.,  6.]], dtype=float32)
>>> # assign NDArray to RowSparseNDArray
>>> x[:] = mx.nd.ones((3,3))
>>> x.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)

indices¶

A deep copy NDArray of the indices array of the RowSparseNDArray. This generates a deep copy of the row indices of the current row_sparse matrix.

Returns:	This RowSparseNDArray’s indices array.
Return type:	NDArray

data¶

A deep copy NDArray of the data array of the RowSparseNDArray. This generates a deep copy of the data of the current row_sparse matrix.

Returns:	This RowSparseNDArray’s data array.
Return type:	NDArray

tostype(stype)[source]¶

Return a copy of the array with chosen storage type.

Returns:	A copy of the array with the chosen storage stype
Return type:	NDArray or RowSparseNDArray

copyto(other)[source]¶

Copies the value of this array to another array.

If other is a NDArray or RowSparseNDArray object, then other.shape and self.shape should be the same. This function copies the value from self to other.

If other is a context, a new RowSparseNDArray will be first created on the target context, and the value of self is copied.

Parameters:	other (NDArray or RowSparseNDArray or Context) – The destination array or context.
Returns:	The copied array. If other is an NDArray or RowSparseNDArray, then the return value and other will point to the same NDArray or RowSparseNDArray.
Return type:	NDArray or RowSparseNDArray

retain(*args, **kwargs)[source]¶

Convenience fluent method for retain().

The arguments are the same as for retain(), with this array as data.

arcsin(*args, **kwargs)¶

Convenience fluent method for arcsin().

The arguments are the same as for arcsin(), with this array as data.

arcsinh(*args, **kwargs)¶

Convenience fluent method for arcsinh().

The arguments are the same as for arcsinh(), with this array as data.

arctan(*args, **kwargs)¶

Convenience fluent method for arctan().

The arguments are the same as for arctan(), with this array as data.

arctanh(*args, **kwargs)¶

Convenience fluent method for arctanh().

The arguments are the same as for arctanh(), with this array as data.

as_in_context(context)¶

Returns an array on the target device with the same value as this array.

If the target context is the same as self.context, then self is returned. Otherwise, a copy is made.

Parameters:	context (Context) – The target context.
Returns:	The target array.
Return type:	NDArray, CSRNDArray or RowSparseNDArray

Examples

>>> x = mx.nd.ones((2,3))
>>> y = x.as_in_context(mx.cpu())
>>> y is x
True
>>> z = x.as_in_context(mx.gpu(0))
>>> z is x
False

asnumpy()¶

Return a dense numpy.ndarray object with value copied from this array

asscalar()¶

Returns a scalar whose value is copied from this array.

This function is equivalent to self.asnumpy()[0]. This NDArray must have shape (1,).

Examples

>>> x = mx.nd.ones((1,), dtype='int32')
>>> x.asscalar()
1
>>> type(x.asscalar())

astype(dtype, copy=True)¶

Returns a copy of the array after casting to a specified type. :param dtype: The type of the returned array. :type dtype: numpy.dtype or str :param copy: Default True. By default, astype always returns a newly

allocated ndarray on the same context. If this is set to False, and the dtype requested is the same as the ndarray’s dtype, the ndarray is returned instead of a copy.

Examples

>>> x = mx.nd.sparse.zeros('row_sparse', (2,3), dtype='float32')
>>> y = x.astype('int32')
>>> y.dtype

ceil(*args, **kwargs)¶

Convenience fluent method for ceil().

The arguments are the same as for ceil(), with this array as data.

check_format(full_check=True)¶

Check whether the NDArray format is valid.

Parameters:	full_check (bool, optional) – If True, rigorous check, O(N) operations. Otherwise basic check, O(1) operations (default True).

clip(*args, **kwargs)¶

Convenience fluent method for clip().

The arguments are the same as for clip(), with this array as data.

context¶

Device context of the array.

Examples

>>> x = mx.nd.array([1, 2, 3, 4])
>>> x.context
cpu(0)
>>> type(x.context)

>>> y = mx.nd.zeros((2,3), mx.gpu(0))
>>> y.context
gpu(0)

copy()¶

Makes a copy of this NDArray, keeping the same context.

Returns:	The copied array
Return type:	NDArray, CSRNDArray or RowSparseNDArray

Examples

>>> x = mx.nd.ones((2,3))
>>> y = x.copy()
>>> y.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)

degrees(*args, **kwargs)¶

Convenience fluent method for degrees().

The arguments are the same as for degrees(), with this array as data.

dtype¶

Data-type of the array’s elements.

Returns:	This NDArray’s data type.
Return type:	numpy.dtype

Examples

>>> x = mx.nd.zeros((2,3))
>>> x.dtype

>>> y = mx.nd.zeros((2,3), dtype='int32')
>>> y.dtype

expm1(*args, **kwargs)¶

Convenience fluent method for expm1().

The arguments are the same as for expm1(), with this array as data.

fix(*args, **kwargs)¶

Convenience fluent method for fix().

The arguments are the same as for fix(), with this array as data.

floor(*args, **kwargs)¶

Convenience fluent method for floor().

The arguments are the same as for floor(), with this array as data.

log1p(*args, **kwargs)¶

Convenience fluent method for log1p().

The arguments are the same as for log1p(), with this array as data.

norm(*args, **kwargs)¶

Convenience fluent method for norm().

The arguments are the same as for norm(), with this array as data.

radians(*args, **kwargs)¶

Convenience fluent method for radians().

The arguments are the same as for radians(), with this array as data.

rint(*args, **kwargs)¶

Convenience fluent method for rint().

The arguments are the same as for rint(), with this array as data.

round(*args, **kwargs)¶

Convenience fluent method for round().

The arguments are the same as for round(), with this array as data.

shape¶

Tuple of array dimensions.

Examples

>>> x = mx.nd.array([1, 2, 3, 4])
>>> x.shape
(4L,)
>>> y = mx.nd.zeros((2, 3, 4))
>>> y.shape
(2L, 3L, 4L)

sign(*args, **kwargs)¶

Convenience fluent method for sign().

The arguments are the same as for sign(), with this array as data.

sin(*args, **kwargs)¶

Convenience fluent method for sin().

The arguments are the same as for sin(), with this array as data.

sinh(*args, **kwargs)¶

Convenience fluent method for sinh().

The arguments are the same as for sinh(), with this array as data.

sqrt(*args, **kwargs)¶

Convenience fluent method for sqrt().

The arguments are the same as for sqrt(), with this array as data.

square(*args, **kwargs)¶

Convenience fluent method for square().

The arguments are the same as for square(), with this array as data.

stype¶

Storage-type of the array.

tan(*args, **kwargs)¶

Convenience fluent method for tan().

The arguments are the same as for tan(), with this array as data.

tanh(*args, **kwargs)¶

Convenience fluent method for tanh().

The arguments are the same as for tanh(), with this array as data.

trunc(*args, **kwargs)¶

Convenience fluent method for trunc().

The arguments are the same as for trunc(), with this array as data.

wait_to_read()¶

Waits until all previous write operations on the current array are finished.

This method guarantees that all previous write operations that pushed into the backend engine for execution are actually finished.

Examples

>>> import time
>>> tic = time.time()
>>> a = mx.nd.ones((1000,1000))
>>> b = mx.nd.dot(a, a)
>>> print(time.time() - tic) 
0.003854036331176758
>>> b.wait_to_read()
>>> print(time.time() - tic) 
0.0893700122833252

zeros_like(*args, **kwargs)¶

Convenience fluent method for zeros_like().

The arguments are the same as for zeros_like(), with this array as data.

Sparse NDArray API of MXNet.

mxnet.ndarray.sparse.csr_matrix(arg1, shape=None, ctx=None, dtype=None)[source]¶

Creates a CSRNDArray, an 2D array with compressed sparse row (CSR) format.

The CSRNDArray can be instantiated in several ways:

• csr_matrix(D):

  to construct a CSRNDArray with a dense 2D array D

  • D (array_like) - An object exposing the array interface, an object whose __array__ method returns an array, or any (nested) sequence.
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is D.dtype if D is an NDArray or numpy.ndarray, float32 otherwise.

• csr_matrix(S)

  to construct a CSRNDArray with a sparse 2D array S

  • S (CSRNDArray or scipy.sparse.csr.csr_matrix) - A sparse matrix.
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is S.dtype.

• csr_matrix((M, N))

  to construct an empty CSRNDArray with shape (M, N)

  • M (int) - Number of rows in the matrix
  • N (int) - Number of columns in the matrix
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is float32.

• csr_matrix((data, indices, indptr))

  to construct a CSRNDArray based on the definition of compressed sparse row format using three separate arrays, where the column indices for row i are stored in indices[indptr[i]:indptr[i+1]] and their corresponding values are stored in data[indptr[i]:indptr[i+1]]. The column indices for a given row are expected to be sorted in ascending order. Duplicate column entries for the same row are not allowed.

  • data (array_like) - An object exposing the array interface, which holds all the non-zero entries of the matrix in row-major order.
  • indices (array_like) - An object exposing the array interface, which stores the column index for each non-zero element in data.
  • indptr (array_like) - An object exposing the array interface, which stores the offset into data of the first non-zero element number of each row of the matrix.
  • shape (tuple of int, optional) - The shape of the array. The default shape is inferred from the indices and indptr arrays.
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is data.dtype if data is an NDArray or numpy.ndarray, float32 otherwise.

• csr_matrix((data, (row, col)))

  to construct a CSRNDArray based on the COOrdinate format using three seperate arrays, where row[i] is the row index of the element, col[i] is the column index of the element and data[i] is the data corresponding to the element. All the missing elements in the input are taken to be zeroes.

  • data (array_like) - An object exposing the array interface, which holds all the non-zero entries of the matrix in COO format.
  • row (array_like) - An object exposing the array interface, which stores the row index for each non zero element in data.
  • col (array_like) - An object exposing the array interface, which stores the col index for each non zero element in data.
  • shape (tuple of int, optional) - The shape of the array. The default shape is inferred from the row and col arrays.
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is float32.

Parameters:	arg1 (tuple of int, tuple of array_like, array_like, CSRNDArray, scipy.sparse.csr_matrix, scipy.sparse.coo_matrix, tuple of int or tuple of array_like) – The argument to help instantiate the csr matrix. See above for further details. shape (tuple of int, optional) – The shape of the csr matrix. ctx (Context, optional) – Device context (default is the current default context). dtype (str or numpy.dtype, optional) – The data type of the output array.
Returns:	A CSRNDArray with the csr storage representation.
Return type:	CSRNDArray

Example

>>> a = mx.nd.sparse.csr_matrix(([1, 2, 3], [1, 0, 2], [0, 1, 2, 2, 3]), shape=(4, 3))
>>> a.asnumpy()
array([[ 0.,  1.,  0.],
       [ 2.,  0.,  0.],
       [ 0.,  0.,  0.],
       [ 0.,  0.,  3.]], dtype=float32)

See also

CSRNDArray()

MXNet NDArray in compressed sparse row format.

mxnet.ndarray.sparse.row_sparse_array(arg1, shape=None, ctx=None, dtype=None)[source]¶

Creates a RowSparseNDArray, a multidimensional row sparse array with a set of tensor slices at given indices.

The RowSparseNDArray can be instantiated in several ways:

• row_sparse_array(D):

  to construct a RowSparseNDArray with a dense ndarray D

  • D (array_like) - An object exposing the array interface, an object whose __array__ method returns an array, or any (nested) sequence.
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is D.dtype if D is an NDArray or numpy.ndarray, float32 otherwise.

• row_sparse_array(S)

  to construct a RowSparseNDArray with a sparse ndarray S

  • S (RowSparseNDArray) - A sparse ndarray.
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is S.dtype.

• row_sparse_array((D0, D1 .. Dn))

  to construct an empty RowSparseNDArray with shape (D0, D1, ... Dn)

  • D0, D1 .. Dn (int) - The shape of the ndarray
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is float32.

• row_sparse_array((data, indices))

  to construct a RowSparseNDArray based on the definition of row sparse format using two separate arrays, where the indices stores the indices of the row slices with non-zeros, while the values are stored in data. The corresponding NDArray dense represented by RowSparseNDArray rsp has dense[rsp.indices[i], :, :, :, ...] = rsp.data[i, :, :, :, ...] The row indices for are expected to be sorted in ascending order. - data (array_like) - An object exposing the array interface, which holds all the non-zero row slices of the array.

  • indices (array_like) - An object exposing the array interface, which stores the row index for each row slice with non-zero elements.
  • shape (tuple of int, optional) - The shape of the array. The default shape is inferred from the indices and indptr arrays.
  • ctx (Context, optional) - Device context (default is the current default context).
  • dtype (str or numpy.dtype, optional) - The data type of the output array. The default dtype is float32.

Parameters:	arg1 (NDArray, numpy.ndarray, RowSparseNDArray, tuple of int or tuple of array_like) – The argument to help instantiate the row sparse ndarray. See above for further details. shape (tuple of int, optional) – The shape of the row sparse ndarray. ctx (Context, optional) – Device context (default is the current default context). dtype (str or numpy.dtype, optional) – The data type of the output array.
Returns:	An RowSparseNDArray with the row_sparse storage representation.
Return type:	RowSparseNDArray

Example

>>> a = mx.nd.sparse.row_sparse_array(([[1, 2], [3, 4]], [1, 4]), shape=(6, 2))
>>> a.asnumpy()
array([[ 0.,  0.],
       [ 1.,  2.],
       [ 0.,  0.],
       [ 0.,  0.],
       [ 3.,  4.],
       [ 0.,  0.]], dtype=float32)

See also

RowSparseNDArray()

MXNet NDArray in row sparse format.

mxnet.ndarray.sparse.add(lhs, rhs)[source]¶

Returns element-wise sum of the input arrays with broadcasting.

Equivalent to lhs + rhs, mx.nd.broadcast_add(lhs, rhs) and mx.nd.broadcast_plus(lhs, rhs) when shapes of lhs and rhs do not match. If lhs.shape == rhs.shape, this is equivalent to mx.nd.elemwise_add(lhs, rhs)

Note

If the corresponding dimensions of two arrays have the same size or one of them has size 1, then the arrays are broadcastable to a common shape.abs

Parameters:	lhs (scalar or array) – First array to be added. rhs (scalar or array) – Second array to be added. If lhs.shape != rhs.shape, they must be broadcastable to a common shape.
Returns:	The element-wise sum of the input arrays.
Return type:	NDArray

Examples

>>> a = mx.nd.ones((2,3)).tostype('csr')
>>> b = mx.nd.ones((2,3)).tostype('csr')
>>> a.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> b.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> (a+b).asnumpy()
array([[ 2.,  2.,  2.],
       [ 2.,  2.,  2.]], dtype=float32)
>>> c = mx.nd.ones((2,3)).tostype('row_sparse')
>>> d = mx.nd.ones((2,3)).tostype('row_sparse')
>>> c.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> d.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> (c+d).asnumpy()
array([[ 2.,  2.,  2.],
       [ 2.,  2.,  2.]], dtype=float32)

mxnet.ndarray.sparse.subtract(lhs, rhs)[source]¶

Returns element-wise difference of the input arrays with broadcasting.

Equivalent to lhs - rhs, mx.nd.broadcast_sub(lhs, rhs) and mx.nd.broadcast_minus(lhs, rhs) when shapes of lhs and rhs do not match. If lhs.shape == rhs.shape, this is equivalent to mx.nd.elemwise_sub(lhs, rhs)

Note

If the corresponding dimensions of two arrays have the same size or one of them has size 1, then the arrays are broadcastable to a common shape.

Parameters:	lhs (scalar or array) – First array to be subtracted. rhs (scalar or array) – Second array to be subtracted. If lhs.shape != rhs.shape, they must be broadcastable to a common shape.__spec__
Returns:	The element-wise difference of the input arrays.
Return type:	NDArray

Examples

>>> a = mx.nd.ones((2,3)).tostype('csr')
>>> b = mx.nd.ones((2,3)).tostype('csr')
>>> a.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> b.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> (a-b).asnumpy()
array([[ 0.,  0.,  0.],
       [ 0.,  0.,  0.]], dtype=float32)
>>> c = mx.nd.ones((2,3)).tostype('row_sparse')
>>> d = mx.nd.ones((2,3)).tostype('row_sparse')
>>> c.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> d.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> (c-d).asnumpy()
array([[ 0.,  0.,  0.],
       [ 0.,  0.,  0.]], dtype=float32)

mxnet.ndarray.sparse.multiply(lhs, rhs)[source]¶

Returns element-wise product of the input arrays with broadcasting.

Equivalent to lhs * rhs and mx.nd.broadcast_mul(lhs, rhs) when shapes of lhs and rhs do not match. If lhs.shape == rhs.shape, this is equivalent to mx.nd.elemwise_mul(lhs, rhs)

Note

If the corresponding dimensions of two arrays have the same size or one of them has size 1, then the arrays are broadcastable to a common shape.

Parameters:	lhs (scalar or array) – First array to be multiplied. rhs (scalar or array) – Second array to be multiplied. If lhs.shape != rhs.shape, they must be broadcastable to a common shape.
Returns:	The element-wise multiplication of the input arrays.
Return type:	NDArray

Examples

>>> x = mx.nd.ones((2,3)).tostype('csr')
>>> y = mx.nd.arange(2).reshape((2,1))
>>> z = mx.nd.arange(3)
>>> x.asnumpy()
array([[ 1.,  1.,  1.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> y.asnumpy()
array([[ 0.],
       [ 1.]], dtype=float32)
>>> z.asnumpy()
array([ 0.,  1.,  2.], dtype=float32)
>>> (x*2).asnumpy()
array([[ 2.,  2.,  2.],
       [ 2.,  2.,  2.]], dtype=float32)
>>> (x*y).asnumpy()
array([[ 0.,  0.,  0.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> mx.nd.sparse.multiply(x, y).asnumpy()
array([[ 0.,  0.,  0.],
       [ 1.,  1.,  1.]], dtype=float32)
>>> (x*z).asnumpy()
array([[ 0.,  1.,  2.],
       [ 0.,  1.,  2.]], dtype=float32)
>>> mx.nd.sparse.multiply(x, z).asnumpy()
array([[ 0.,  1.,  2.],
       [ 0.,  1.,  2.]], dtype=float32)
>>> z = z.reshape((1, 3))
>>> z.asnumpy()
array([[ 0.,  1.,  2.]], dtype=float32)
>>> (x*z).asnumpy()
array([[ 0.,  1.,  2.],
       [ 0.,  1.,  2.]], dtype=float32)
>>> mx.nd.sparse.multiply(x, z).asnumpy()
array([[ 0.,  1.,  2.],
       [ 0.,  1.,  2.]], dtype=float32)

mxnet.ndarray.sparse.ElementWiseSum(*args, **kwargs)¶

Adds all input arguments element-wise.

\[add\_n(a_1, a_2, ..., a_n) = a_1 + a_2 + ... + a_n\]

add_n is potentially more efficient than calling add by n times.

The storage type of add_n output depends on storage types of inputs

• add_n(row_sparse, row_sparse, ..) = row_sparse
• otherwise, add_n generates output with default storage

Defined in src/operator/tensor/elemwise_sum.cc:L150

Parameters:	args (NDArray[]) – Positional input arguments out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.FullyConnected(data=None, weight=None, bias=None, num_hidden=_Null, no_bias=_Null, flatten=_Null, out=None, name=None, **kwargs)¶

Applies a linear transformation: \(Y = XW^T + b\).

If flatten is set to be true, then the shapes are:

• data: (batch_size, x1, x2, ..., xn)
• weight: (num_hidden, x1 * x2 * ... * xn)
• bias: (num_hidden,)
• out: (batch_size, num_hidden)

If flatten is set to be false, then the shapes are:

• data: (x1, x2, ..., xn, input_dim)
• weight: (num_hidden, input_dim)
• bias: (num_hidden,)
• out: (x1, x2, ..., xn, num_hidden)

The learnable parameters include both weight and bias.

If no_bias is set to be true, then the bias term is ignored.

Note that the operator also supports forward computation with row_sparse weight and bias, where the length of weight.indices and bias.indices must be equal to num_hidden. This could be used for model inference with row_sparse weights trained with SparseEmbedding.

Defined in src/operator/nn/fully_connected.cc:L254

Parameters:	data (NDArray) – Input data. weight (NDArray) – Weight matrix. bias (NDArray) – Bias parameter. num_hidden (int, required) – Number of hidden nodes of the output. no_bias (boolean, optional, default=0) – Whether to disable bias parameter. flatten (boolean, optional, default=1) – Whether to collapse all but the first axis of the input data tensor. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.LinearRegressionOutput(data=None, label=None, grad_scale=_Null, out=None, name=None, **kwargs)¶

Computes and optimizes for squared loss during backward propagation. Just outputs data during forward propagation.

If \(\hat{y}_i\) is the predicted value of the i-th sample, and \(y_i\) is the corresponding target value, then the squared loss estimated over \(n\) samples is defined as

\(\text{SquaredLoss}(\textbf{Y}, \hat{\textbf{Y}} ) = \frac{1}{n} \sum_{i=0}^{n-1} \lVert \textbf{y}_i - \hat{\textbf{y}}_i \rVert_2\)

Note

Use the LinearRegressionOutput as the final output layer of a net.

The storage type of label can be default or csr

• LinearRegressionOutput(default, default) = default
• LinearRegressionOutput(default, csr) = default

By default, gradients of this loss function are scaled by factor 1/m, where m is the number of regression outputs of a training example. The parameter grad_scale can be used to change this scale to grad_scale/m.

Defined in src/operator/regression_output.cc:L92

Parameters:	data (NDArray) – Input data to the function. label (NDArray) – Input label to the function. grad_scale (float, optional, default=1) – Scale the gradient by a float factor out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.LogisticRegressionOutput(data=None, label=None, grad_scale=_Null, out=None, name=None, **kwargs)¶

Applies a logistic function to the input.

The logistic function, also known as the sigmoid function, is computed as \(\frac{1}{1+exp(-\textbf{x})}\).

Commonly, the sigmoid is used to squash the real-valued output of a linear model \(wTx+b\) into the [0,1] range so that it can be interpreted as a probability. It is suitable for binary classification or probability prediction tasks.

Note

Use the LogisticRegressionOutput as the final output layer of a net.

The storage type of label can be default or csr

• LogisticRegressionOutput(default, default) = default
• LogisticRegressionOutput(default, csr) = default

By default, gradients of this loss function are scaled by factor 1/m, where m is the number of regression outputs of a training example. The parameter grad_scale can be used to change this scale to grad_scale/m.

Defined in src/operator/regression_output.cc:L148

Parameters:	data (NDArray) – Input data to the function. label (NDArray) – Input label to the function. grad_scale (float, optional, default=1) – Scale the gradient by a float factor out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.MAERegressionOutput(data=None, label=None, grad_scale=_Null, out=None, name=None, **kwargs)¶

Computes mean absolute error of the input.

MAE is a risk metric corresponding to the expected value of the absolute error.

If \(\hat{y}_i\) is the predicted value of the i-th sample, and \(y_i\) is the corresponding target value, then the mean absolute error (MAE) estimated over \(n\) samples is defined as

\(\text{MAE}(\textbf{Y}, \hat{\textbf{Y}} ) = \frac{1}{n} \sum_{i=0}^{n-1} \lVert \textbf{y}_i - \hat{\textbf{y}}_i \rVert_1\)

Note

Use the MAERegressionOutput as the final output layer of a net.

The storage type of label can be default or csr

• MAERegressionOutput(default, default) = default
• MAERegressionOutput(default, csr) = default

By default, gradients of this loss function are scaled by factor 1/m, where m is the number of regression outputs of a training example. The parameter grad_scale can be used to change this scale to grad_scale/m.

Defined in src/operator/regression_output.cc:L120

Parameters:	data (NDArray) – Input data to the function. label (NDArray) – Input label to the function. grad_scale (float, optional, default=1) – Scale the gradient by a float factor out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.abs(data=None, out=None, name=None, **kwargs)¶

Returns element-wise absolute value of the input.

Example:

abs([-2, 0, 3]) = [2, 0, 3]

The storage type of abs output depends upon the input storage type:

• abs(default) = default
• abs(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_basic.cc:L460

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.adagrad_update(weight=None, grad=None, history=None, lr=_Null, epsilon=_Null, wd=_Null, rescale_grad=_Null, clip_gradient=_Null, out=None, name=None, **kwargs)¶

Update function for AdaGrad optimizer.

Referenced from Adaptive Subgradient Methods for Online Learning and Stochastic Optimization, and available at http://www.jmlr.org/papers/volume12/duchi11a/duchi11a.pdf.

Updates are applied by:

rescaled_grad = clip(grad * rescale_grad, clip_gradient)
history = history + square(rescaled_grad)
w = w - learning_rate * rescaled_grad / sqrt(history + epsilon)

Note that non-zero values for the weight decay option are not supported.

Defined in src/operator/optimizer_op.cc:L624

Parameters:	weight (NDArray) – Weight grad (NDArray) – Gradient history (NDArray) – History lr (float, required) – Learning rate epsilon (float, optional, default=1e-07) – epsilon wd (float, optional, default=0) – weight decay rescale_grad (float, optional, default=1) – Rescale gradient to grad = rescale_grad*grad. clip_gradient (float, optional, default=-1) – Clip gradient to the range of [-clip_gradient, clip_gradient] If clip_gradient <= 0, gradient clipping is turned off. grad = max(min(grad, clip_gradient), -clip_gradient). out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.adam_update(weight=None, grad=None, mean=None, var=None, lr=_Null, beta1=_Null, beta2=_Null, epsilon=_Null, wd=_Null, rescale_grad=_Null, clip_gradient=_Null, out=None, name=None, **kwargs)¶

Update function for Adam optimizer. Adam is seen as a generalization of AdaGrad.

Adam update consists of the following steps, where g represents gradient and m, v are 1st and 2nd order moment estimates (mean and variance).

\[\begin{split}g_t = \nabla J(W_{t-1})\\ m_t = \beta_1 m_{t-1} + (1 - \beta_1) g_t\\ v_t = \beta_2 v_{t-1} + (1 - \beta_2) g_t^2\\ W_t = W_{t-1} - \alpha \frac{ m_t }{ \sqrt{ v_t } + \epsilon }\end{split}\]

It updates the weights using:

m = beta1*m + (1-beta1)*grad
v = beta2*v + (1-beta2)*(grad**2)
w += - learning_rate * m / (sqrt(v) + epsilon)

If w, m and v are all of row_sparse storage type, only the row slices whose indices appear in grad.indices are updated (for w, m and v):

for row in grad.indices:
    m[row] = beta1*m[row] + (1-beta1)*grad[row]
    v[row] = beta2*v[row] + (1-beta2)*(grad[row]**2)
    w[row] += - learning_rate * m[row] / (sqrt(v[row]) + epsilon)

Defined in src/operator/optimizer_op.cc:L454

Parameters:	weight (NDArray) – Weight grad (NDArray) – Gradient mean (NDArray) – Moving mean var (NDArray) – Moving variance lr (float, required) – Learning rate beta1 (float, optional, default=0.9) – The decay rate for the 1st moment estimates. beta2 (float, optional, default=0.999) – The decay rate for the 2nd moment estimates. epsilon (float, optional, default=1e-08) – A small constant for numerical stability. wd (float, optional, default=0) – Weight decay augments the objective function with a regularization term that penalizes large weights. The penalty scales with the square of the magnitude of each weight. rescale_grad (float, optional, default=1) – Rescale gradient to grad = rescale_grad*grad. clip_gradient (float, optional, default=-1) – Clip gradient to the range of [-clip_gradient, clip_gradient] If clip_gradient <= 0, gradient clipping is turned off. grad = max(min(grad, clip_gradient), -clip_gradient). out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.add_n(*args, **kwargs)¶

Adds all input arguments element-wise.

\[add\_n(a_1, a_2, ..., a_n) = a_1 + a_2 + ... + a_n\]

add_n is potentially more efficient than calling add by n times.

The storage type of add_n output depends on storage types of inputs

• add_n(row_sparse, row_sparse, ..) = row_sparse
• otherwise, add_n generates output with default storage

Defined in src/operator/tensor/elemwise_sum.cc:L150

Parameters:	args (NDArray[]) – Positional input arguments out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.arccos(data=None, out=None, name=None, **kwargs)¶

Returns element-wise inverse cosine of the input array.

The input should be in range [-1, 1]. The output is in the closed interval \([0, \pi]\)

\[arccos([-1, -.707, 0, .707, 1]) = [\pi, 3\pi/4, \pi/2, \pi/4, 0]\]

The storage type of arccos output is always dense

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L123

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.arccosh(data=None, out=None, name=None, **kwargs)¶

Returns the element-wise inverse hyperbolic cosine of the input array, computed element-wise.

The storage type of arccosh output is always dense

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L264

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.arcsin(data=None, out=None, name=None, **kwargs)¶

Returns element-wise inverse sine of the input array.

The input should be in the range [-1, 1]. The output is in the closed interval of [\(-\pi/2\), \(\pi/2\)].

\[arcsin([-1, -.707, 0, .707, 1]) = [-\pi/2, -\pi/4, 0, \pi/4, \pi/2]\]

The storage type of arcsin output depends upon the input storage type:

• arcsin(default) = default
• arcsin(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L104

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.arcsinh(data=None, out=None, name=None, **kwargs)¶

Returns the element-wise inverse hyperbolic sine of the input array, computed element-wise.

The storage type of arcsinh output depends upon the input storage type:

• arcsinh(default) = default
• arcsinh(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L250

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.arctan(data=None, out=None, name=None, **kwargs)¶

Returns element-wise inverse tangent of the input array.

The output is in the closed interval \([-\pi/2, \pi/2]\)

\[arctan([-1, 0, 1]) = [-\pi/4, 0, \pi/4]\]

The storage type of arctan output depends upon the input storage type:

• arctan(default) = default
• arctan(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L144

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.arctanh(data=None, out=None, name=None, **kwargs)¶

Returns the element-wise inverse hyperbolic tangent of the input array, computed element-wise.

The storage type of arctanh output depends upon the input storage type:

• arctanh(default) = default
• arctanh(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L281

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.cast_storage(data=None, stype=_Null, out=None, name=None, **kwargs)¶

Casts tensor storage type to the new type.

When an NDArray with default storage type is cast to csr or row_sparse storage, the result is compact, which means:

• for csr, zero values will not be retained
• for row_sparse, row slices of all zeros will not be retained

The storage type of cast_storage output depends on stype parameter:

• cast_storage(csr, ‘default’) = default
• cast_storage(row_sparse, ‘default’) = default
• cast_storage(default, ‘csr’) = csr
• cast_storage(default, ‘row_sparse’) = row_sparse
• cast_storage(csr, ‘csr’) = csr
• cast_storage(row_sparse, ‘row_sparse’) = row_sparse

Example:

dense = [[ 0.,  1.,  0.],
         [ 2.,  0.,  3.],
         [ 0.,  0.,  0.],
         [ 0.,  0.,  0.]]

# cast to row_sparse storage type
rsp = cast_storage(dense, 'row_sparse')
rsp.indices = [0, 1]
rsp.values = [[ 0.,  1.,  0.],
              [ 2.,  0.,  3.]]

# cast to csr storage type
csr = cast_storage(dense, 'csr')
csr.indices = [1, 0, 2]
csr.values = [ 1.,  2.,  3.]
csr.indptr = [0, 1, 3, 3, 3]

Defined in src/operator/tensor/cast_storage.cc:L71

Parameters:	data (NDArray) – The input. stype ({'csr', 'default', 'row_sparse'}, required) – Output storage type. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.ceil(data=None, out=None, name=None, **kwargs)¶

Returns element-wise ceiling of the input.

The ceil of the scalar x is the smallest integer i, such that i >= x.

Example:

ceil([-2.1, -1.9, 1.5, 1.9, 2.1]) = [-2., -1.,  2.,  2.,  3.]

The storage type of ceil output depends upon the input storage type:

• ceil(default) = default
• ceil(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_basic.cc:L538

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.clip(data=None, a_min=_Null, a_max=_Null, out=None, name=None, **kwargs)¶

Clips (limits) the values in an array.

Given an interval, values outside the interval are clipped to the interval edges. Clipping x between a_min and a_x would be:

clip(x, a_min, a_max) = max(min(x, a_max), a_min))

Example:

x = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

clip(x,1,8) = [ 1.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.,  8.]

The storage type of clip output depends on storage types of inputs and the a_min, a_max parameter values:

• clip(default) = default
• clip(row_sparse, a_min <= 0, a_max >= 0) = row_sparse
• clip(csr, a_min <= 0, a_max >= 0) = csr
• clip(row_sparse, a_min < 0, a_max < 0) = default
• clip(row_sparse, a_min > 0, a_max > 0) = default
• clip(csr, a_min < 0, a_max < 0) = csr
• clip(csr, a_min > 0, a_max > 0) = csr

Defined in src/operator/tensor/matrix_op.cc:L617

Parameters:	data (NDArray) – Input array. a_min (float, required) – Minimum value a_max (float, required) – Maximum value out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.cos(data=None, out=None, name=None, **kwargs)¶

Computes the element-wise cosine of the input array.

The input should be in radians (\(2\pi\) rad equals 360 degrees).

\[cos([0, \pi/4, \pi/2]) = [1, 0.707, 0]\]

The storage type of cos output is always dense

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L63

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.cosh(data=None, out=None, name=None, **kwargs)¶

Returns the hyperbolic cosine of the input array, computed element-wise.

\[cosh(x) = 0.5\times(exp(x) + exp(-x))\]

The storage type of cosh output is always dense

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L216

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.degrees(data=None, out=None, name=None, **kwargs)¶

Converts each element of the input array from radians to degrees.

\[degrees([0, \pi/2, \pi, 3\pi/2, 2\pi]) = [0, 90, 180, 270, 360]\]

The storage type of degrees output depends upon the input storage type:

• degrees(default) = default
• degrees(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_trig.cc:L163

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.dot(lhs=None, rhs=None, transpose_a=_Null, transpose_b=_Null, out=None, name=None, **kwargs)¶

Dot product of two arrays.

dot‘s behavior depends on the input array dimensions:

• 1-D arrays: inner product of vectors

• 2-D arrays: matrix multiplication

• N-D arrays: a sum product over the last axis of the first input and the first axis of the second input

  For example, given 3-D x with shape (n,m,k) and y with shape (k,r,s), the result array will have shape (n,m,r,s). It is computed by:

  dot(x,y)[i,j,a,b] = sum(x[i,j,:]*y[:,a,b])
  

  Example:

  x = reshape([0,1,2,3,4,5,6,7], shape=(2,2,2))
  y = reshape([7,6,5,4,3,2,1,0], shape=(2,2,2))
  dot(x,y)[0,0,1,1] = 0
  sum(x[0,0,:]*y[:,1,1]) = 0
  

The storage type of dot output depends on storage types of inputs and transpose options:

• dot(csr, default) = default
• dot(csr.T, default) = row_sparse
• dot(csr, row_sparse) = default
• dot(default, csr) = csr
• otherwise, dot generates output with default storage

Defined in src/operator/tensor/dot.cc:L62

Parameters:	lhs (NDArray) – The first input rhs (NDArray) – The second input transpose_a (boolean, optional, default=0) – If true then transpose the first input before dot. transpose_b (boolean, optional, default=0) – If true then transpose the second input before dot. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.elemwise_add(lhs=None, rhs=None, out=None, name=None, **kwargs)¶

Adds arguments element-wise.

The storage type of elemwise_add output depends on storage types of inputs

• elemwise_add(row_sparse, row_sparse) = row_sparse
• elemwise_add(csr, csr) = csr
• otherwise, elemwise_add generates output with default storage

Parameters:	lhs (NDArray) – first input rhs (NDArray) – second input out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.elemwise_div(lhs=None, rhs=None, out=None, name=None, **kwargs)¶

Divides arguments element-wise.

The storage type of elemwise_div output is always dense

Parameters:	lhs (NDArray) – first input rhs (NDArray) – second input out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.elemwise_mul(lhs=None, rhs=None, out=None, name=None, **kwargs)¶

Multiplies arguments element-wise.

The storage type of elemwise_mul output depends on storage types of inputs

• elemwise_mul(default, default) = default
• elemwise_mul(row_sparse, row_sparse) = row_sparse
• elemwise_mul(default, row_sparse) = default
• elemwise_mul(row_sparse, default) = default
• elemwise_mul(csr, csr) = csr
• otherwise, elemwise_mul generates output with default storage

Parameters:	lhs (NDArray) – first input rhs (NDArray) – second input out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.elemwise_sub(lhs=None, rhs=None, out=None, name=None, **kwargs)¶

Subtracts arguments element-wise.

The storage type of elemwise_sub output depends on storage types of inputs

• elemwise_sub(row_sparse, row_sparse) = row_sparse
• elemwise_sub(csr, csr) = csr
• otherwise, elemwise_sub generates output with default storage

Parameters:	lhs (NDArray) – first input rhs (NDArray) – second input out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.exp(data=None, out=None, name=None, **kwargs)¶

Returns element-wise exponential value of the input.

\[exp(x) = e^x \approx 2.718^x\]

Example:

exp([0, 1, 2]) = [1., 2.71828175, 7.38905621]

The storage type of exp output is always dense

Defined in src/operator/tensor/elemwise_unary_op_basic.cc:L716

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.expm1(data=None, out=None, name=None, **kwargs)¶

Returns exp(x) - 1 computed element-wise on the input.

This function provides greater precision than exp(x) - 1 for small values of x.

The storage type of expm1 output depends upon the input storage type:

• expm1(default) = default
• expm1(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_basic.cc:L795

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.fix(data=None, out=None, name=None, **kwargs)¶

Returns element-wise rounded value to the nearest integer towards zero of the input.

Example:

fix([-2.1, -1.9, 1.9, 2.1]) = [-2., -1.,  1., 2.]

The storage type of fix output depends upon the input storage type:

• fix(default) = default
• fix(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_basic.cc:L595

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.floor(data=None, out=None, name=None, **kwargs)¶

Returns element-wise floor of the input.

The floor of the scalar x is the largest integer i, such that i <= x.

Example:

floor([-2.1, -1.9, 1.5, 1.9, 2.1]) = [-3., -2.,  1.,  1.,  2.]

The storage type of floor output depends upon the input storage type:

• floor(default) = default
• floor(row_sparse) = row_sparse

Defined in src/operator/tensor/elemwise_unary_op_basic.cc:L557

Parameters:	data (NDArray) – The input array. out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays

mxnet.ndarray.sparse.ftrl_update(weight=None, grad=None, z=None, n=None, lr=_Null, lamda1=_Null, beta=_Null, wd=_Null, rescale_grad=_Null, clip_gradient=_Null, out=None, name=None, **kwargs)¶

Update function for Ftrl optimizer. Referenced from Ad Click Prediction: a View from the Trenches, available at http://dl.acm.org/citation.cfm?id=2488200.

It updates the weights using:

rescaled_grad = clip(grad * rescale_grad, clip_gradient)
z += rescaled_grad - (sqrt(n + rescaled_grad**2) - sqrt(n)) * weight / learning_rate
n += rescaled_grad**2
w = (sign(z) * lamda1 - z) / ((beta + sqrt(n)) / learning_rate + wd) * (abs(z) > lamda1)

If w, z and n are all of row_sparse storage type, only the row slices whose indices appear in grad.indices are updated (for w, z and n):

for row in grad.indices:
    rescaled_grad[row] = clip(grad[row] * rescale_grad, clip_gradient)
    z[row] += rescaled_grad[row] - (sqrt(n[row] + rescaled_grad[row]**2) - sqrt(n[row])) * weight[row] / learning_rate
    n[row] += rescaled_grad[row]**2
    w[row] = (sign(z[row]) * lamda1 - z[row]) / ((beta + sqrt(n[row])) / learning_rate + wd) * (abs(z[row]) > lamda1)

Defined in src/operator/optimizer_op.cc:L591

Parameters:	weight (NDArray) – Weight grad (NDArray) – Gradient z (NDArray) – z n (NDArray) – Square of grad lr (float, required) – Learning rate lamda1 (float, optional, default=0.01) – The L1 regularization coefficient. beta (float, optional, default=1) – Per-Coordinate Learning Rate beta. wd (float, optional, default=0) – Weight decay augments the objective function with a regularization term that penalizes large weights. The penalty scales with the square of the magnitude of each weight. rescale_grad (float, optional, default=1) – Rescale gradient to grad = rescale_grad*grad. clip_gradient (float, optional, default=-1) – Clip gradient to the range of [-clip_gradient, clip_gradient] If clip_gradient <= 0, gradient clipping is turned off. grad = max(min(grad, clip_gradient), -clip_gradient). out (NDArray, optional) – The output NDArray to hold the result.
Returns:	out – The output of this function.
Return type:	NDArray or list of NDArrays