NAME
AI::MXNet::NDArray::Sparse - Sparse NDArray API of MXNet
DESCRIPTION
The base class of an NDArray stored in a sparse storage format.
See AI::MXNet::NDArray::CSR and AI::MXNet::NDArray::RowSparse for more details.
aspdl
Return a dense PDL object with value copied from this array
astype
Returns a copy of the array after casting to a specified type.
Parameters
----------
dtype : Dtype
The type of the returned array.
Examples
--------
>>> $x = mx->nd->sparse->zeros('row_sparse', [2,3], dtype=>'float32')
>>> $y = $x->astype('int32')
>>> $y->dtype
<type 'int32'>
copyto
Copies the value of this array to another array.
Parameters
----------
other : NDArray or NDArray::CSR or NDArray::RowSparse or Context
The destination array or context.
Returns
-------
NDArray or CSRNDArray::CSR or NDArray::RowSparse
The copied array.
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).
_data
A deep copy NDArray of the data array associated with the BaseSparseNDArray.
This function blocks. Do not use it in performance critical code.
_aux_data
Get a deep copy NDArray of the i-th aux data array associated with the
AI::MXNet::NDArray::Sparse
This function blocks. Do not use it in performance critical code.
NAME
AI::MXNet::NDArray::CSR - A sparse representation of 2D NDArray in the Compressed Sparse Row format.
DESCRIPTION
A AI::MXNet::NDArray::CSR represents an AI::MXNet::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->aspdl;
[ 1 2 3]
>>> $a->indices->aspdl
[1 0 2]
>>> $a->indptr->aspdl
[0 1 2 2 3]
See Also
--------
csr_matrix: Several ways to construct a CSRNDArray
slice
Returns a newly created array based on the indexing key.
Parameters
----------
key : int or array ref
Indexing key.
Examples
--------
>>> $indptr = [0, 2, 3, 6];
>>> $indices = [0, 2, 2, 0, 1, 2];
>>> $data = [1, 2, 3, 4, 5, 6];
>>> $a = mx->nd->sparse->csr_matrix([$data, $indices, $indptr], shape=>[3, 3])
>>> $a->aspdl
[[ 1 0 2]
[ 0 0 3]
[ 4 5 6]]
>>> $a->slice([1,2])->aspdl
[[ 0 0 3]]
>>> $a->slice(1)->aspdl
[[ 0 0 3]]
>>> $a->[-1]->aspdl
[[ 4 5 6]]
set
Set self to value. Also usable as overloaded .=
Parameters
----------
value : AI::MXNet::NDArray or AI::MXNet::NDArray::CSR
or PDL/PDL::CCS::Nd/perl array ref in PDL constructor format
The value to set.
Examples
--------
>>> $src = mx->nd->sparse->zeros('csr', [3,3])
>>> $src->aspdl
[[ 0 0 0]
[ 0 0 0]
[ 0 0 0]]
>>> # AI::MXNet::NDArray::CSR with same storage type
>>> $x = mx->nd->ones('row_sparse', [3,3])->tostype('csr')
>>> $x .= $src
>>> $x->aspdl
[[ 1 1 1]
[ 1 1 1]
[ 1 1 1]]
>>> # assign NDArray to AI::MXNet::NDArray::CSR
>>> $x .= mx->nd->ones([3,3]) * 2
>>> $x->aspdl
[[ 2 2 2]
[ 2 2 2]
[ 2 2 2]]
indices
A deep copy NDArray of the indices array of the AI::MXNet::NDArray::CSR.
This generates a deep copy of the column indices of the current `csr` matrix.
Returns
-------
NDArray
This AI::MXNet::NDArray::CSR indices array.
indptr
A deep copy NDArray of the inptr array of the AI::MXNet::NDArray::CSR.
This generates a deep copy of the indptr of the current `csr` matrix.
Returns
-------
NDArray
This AI::MXNet::NDArray::CSR indptr array.
data
A deep copy NDArray of the data array of the AI::MXNet::NDArray::CSR.
This generates a deep copy of the data of the current `csr` matrix.
Returns
-------
NDArray
This AI::MXNet::NDArray::CSR data array.
tostype
Return a copy of the array with chosen storage type.
Returns
-------
NDArray or AI::MXNet::NDArray::CSR
A copy of the array with the chosen storage stype
copyto
Copies the value of this array to another array.
If $other is a AI::MXNet::NDArray or AI::MXNet::NDArray::CSR 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 AI::MXNet::NDArray::CSR will be first created on
the target context, and the value of $self is copied.
Parameters
----------
$other : AI::MXNet::NDArray or AI::MXNet::NDArray::CSR or AI::MXNet::Context
The destination array or context.
Returns
-------
AI::MXNet::NDArray or AI::MXNet::NDArray::CSR
Returns a PDL::CCS::Nd object with value copied from this array
NAME
AI::MXNet::NDArray::RowSparse - A sparse representation of a set of NDArray row slices at given indices.
DESCRIPTION
A AI::MXNet::NDArray::RowSparse 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 AI::MXNet::NDArray::RowSparse ``rsp`` has
``dense[rsp.indices[i], :, :, :, ...] = rsp.data[i, :, :, :, ...]``
>>> $dense->aspdl
[[ 1 2 3 ]
[ 0 0 0 ]
[ 4 0 5 ]
[ 0 0 0 ]
[ 0 0 0 ]]
>>> $rsp = $dense->tostype('row_sparse');
>>> $rsp->indices->aspdl
[ 0 2 ]
>>> $rsp->data->aspdl
[[ 1 2 3 ]
[ 4 0 5 ]]
A AI::MXNet::NDArray::RowSparse 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.
AI::MXNet::NDArray::RowSparse 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 AI::MXNet::NDArray::RowSparse
set
Set self to value. Also usable as overloaded .=
Parameters
----------
value : AI::MXNet::NDArray or AI::MXNet::NDArray::CSR
or PDL/PDL::CCS::Nd/perl array ref in PDL constructor format
The value to set.
Examples
--------
>>> $src = mx->nd->sparse->zeros('raw_sparse', [3,3])
>>> $src->aspdl
[[ 0 0 0]
[ 0 0 0]
[ 0 0 0]]
>>> # AI::MXNet::NDArray::RowSparse with same storage type
>>> $x = mx->nd->ones('row_sparse', [3,3])
>>> $src .= $x
>>> $src->aspdl
[[ 1 1 1]
[ 1 1 1]
[ 1 1 1]]
>>> # assign NDArray to AI::MXNet::NDArray::RowSparse
>>> $x .= mx->nd->ones([3,3]) * 2
>>> $x->aspdl
[[ 2 2 2]
[ 2 2 2]
[ 2 2 2]]
data
A deep copy NDArray of the data array of the AI::MXNet::NDArray::RowSparse.
This generates a deep copy of the data of the current `row_sparse` matrix.
Returns
-------
NDArray
This AI::MXNet::NDArray::RowSparse data array.
indices
A deep copy NDArray of the indices array of the AI::MXNet::NDArray::RowSparse.
This generates a deep copy of the column indices of the current `row_sparse` matrix.
Returns
-------
NDArray
This AI::MXNet::NDArray::RowSparse indices array.
data
A deep copy NDArray of the data array of the AI::MXNet::NDArray::RowSparse.
This generates a deep copy of the data of the current `row_sparse` matrix.
Returns
-------
NDArray
This AI::MXNet::NDArray::RowSparse data array.
tostype
Return a copy of the array with chosen storage type.
Returns
-------
NDArray or RowSparseNDArray
A copy of the array with the chosen storage stype
copyto
Copies the value of this array to another array.
If $other is a AI::MXNet::NDArray or AI::MXNet::NDArray::RawSparse 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 AI::MXNet::NDArray::RawSparse will be first created on
the target context, and the value of $self is copied.
Parameters
----------
$other : AI::MXNet::NDArray or AI::MXNet::NDArray::RawSparse or AI::MXNet::Context
The destination array or context.
Returns
-------
AI::MXNet::NDArray or AI::MXNet::NDArray::RawSparse
csr_matrix
Creates a AI::MXNet::NDArray::CSR, an 2D array with compressed sparse row (CSR) format.
The AI::MXNet::NDArray::CSR can be instantiated in several ways:
- csr_matrix($arg1, Maybe[AI::MXNet::Context] :$ctx=, Maybe[Shape] :$shape, Maybe [Dtype] :$dtype=)
$ctx, $shape, $dtype are optional
$arg1 can be given in following variants
- to construct a AI::MXNet::NDArray::CSR with a dense 2D array $arg1
- $arg1 is in AI::MXNet::NDArray::array input format
- to construct a AI::MXNet::NDArray::CSR with a sparse 2D array $arg1
$arg1 is AI::MXNet::NDArray::CSR or PDL::CCS::Nd - A sparse matrix.
PDL::CCS::Nd is expected to be converted internally into CSR format
AI::MXNet injects 'tocsr' method into PDL and PDL::CCS::Nd modules for this purpose.
- to construct an empty AI::MXNet::NDArray::CSR with shape $arg1 = [$M, $N]
- $M - Number of rows in the matrix
- $N - Number of columns in the matrix
- to construct a AI::MXNet::NDArray::CSR 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.
In this case $arg1 = [$data, $indices, $indptr]
$data, $indices, $indptr must be given in the AI::MXNet::NDArray::array input format
- $data - holds all the non-zero entries of the matrix in row-major order.
- $indices - stores the column index for each non-zero element in $data.
stores the column index for each non-zero element in $data.
- $indptr - stores the offset into $data of the first non-zero element number of each
row of the matrix.
to construct a AI::MXNet::NDArray::CSR 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.
In this case $arg1 = [$data, [$row, $col]]
$data, $row, $col must be given in the AI::MXNet::NDArray::array input format
$data - holds all the non-zero entries of the matrix in COO format.
$row - stores the row index for each non zero element in $data.
- **col** (*array_like*) - An object exposing the array interface, which
$col - stores the col index for each non zero element in $data.
Returns
-------
AI::MXNet::NDArray::CSR
A AI::MXNet::NDArray::CSR with the 'csr' storage representation.
Example
-------
>>> $a = mx->nd->sparse->csr_matrix([[1, 2, 3], [1, 0, 2], [0, 1, 2, 2, 3]], shape => [4, 3])
>>> $a->aspdl
[[ 0 1 0]
[ 2 0 0]
[ 0 0 0]
[ 0 0 3]]
See Also
--------
CSRNDArray : MXNet NDArray in compressed sparse row format.
row_sparse_array
Creates a AI::MXNet::NDArray::RowSparse, a multidimensional row sparse array with a set of
tensor slices at given indices.
The AI::MXNet::NDArray::RowSparse can be instantiated in several ways:
- row_sparse_array($arg1, Maybe[AI::MXNet::Context] :$ctx=, Maybe[Shape] :$shape, Maybe [Dtype] :$dtype=)
$ctx, $shape, $dtype are optional
$arg1 can be given in following variants
- to construct a AI::MXNet::NDArray::RowSparse with a dense array $arg1
- $arg1 is in AI::MXNet::NDArray::array input format
- to construct a AI::MXNet::NDArray::RowSparse with a sparse array $arg1
$arg1 is AI::MXNet::NDArray::RowSparse
- to construct an empty AI::MXNet::NDArray::RowSparse with shape $arg1 = [$D1, $D1, ...$DN]
- 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 RowSparse rsp has
dense[rsp.indices[i], :, :, :, ...] = rsp.data[i, :, :, :, ...]
The row indices for are expected to be **sorted in ascending order.
$arg1 = [$data, $indices]
$data, $indices must be given in the AI::MXNet::NDArray::array input format
Returns
-------
AI::MXNet::NDArray::RowSparse
A AI::MXNet::NDArray::RowSparse with the 'row_sparse' storage representation.
Example
-------
>>> $a = mx->nd->sparse->row_sparse_array([[[1, 2], [3, 4]], [1, 4]], shape=>[6, 2])
>>> $a->aspdl
[[ 0 0]
[ 1 2]
[ 0 0]
[ 0 0]
[ 3 4]
[ 0 0]]
zeros
Return a new array of given shape and type, filled with zeros.
Parameters
----------
$stype: string
The storage type of the empty array, such as 'row_sparse', 'csr', etc
shape : int or array ref of int
The shape of the empty array
:$ctx : AI::MXNet::Context, optional
An optional device context (default is the current default context)
:$dtype : Dtype, optional
An optional value type (default is `float32`)
Returns
-------
AI::MXNet::NDArray::RowSparse or AI::MXNet::NDArray::CSR
A created array
Examples
--------
>>> mx->nd->sparse->zeros('csr', [1,2])
<AI::MXNet::NDArray::CSR 1x2 @cpu(0)>
>>> mx->nd->sparse->zeros('row_sparse', [1,2], ctx=>mx->cpu(), dtype=>'float16')->aspdl
[[ 0 0]]
empty
Returns a new array of given shape and type, without initializing entries.
Parameters
----------
stype: string
The storage type of the empty array, such as 'row_sparse', 'csr', etc
shape : int or array ref of int
The shape of the empty array.
ctx : Context, optional
An optional device context (default is the current default context).
dtype : Dtype, optional
An optional value type (default is `float32`).
Returns
-------
AI::MXNet::NDArray::CSR or AI::MXNet::NDArray::RowSparse
A created array.
array
Creates a sparse array from any object exposing the array interface.
Parameters
----------
$source_array : AI::MXNet::NDArray::RowSparse, AI::MXNet::NDArray::CSR or PDL::CCS::Nd
The source sparse array
:$ctx : Context, optional
The default context is $source_array->context if $source_array is an NDArray.
The current default context otherwise.
:$dtype : Dtype, optional
The data type of the output array. The default dtype is $source_array->dtype
if $source_array is an AI::MXNet::NDArray, PDL or PDL::CCS::Nd
'float32' otherwise.
Returns
-------
AI::MXNet::NDArray::RowSparse or AI::MXNet::NDArray::CSR
An array with the same contents as the $source_array.
Examples
--------
>>> use PDL; use PDL::CCS::Nd
>>> $csr = zeros([100, 2])->tocsr
>>> mx->nd->sparse->array($csr)
<AI::MXNet::NDArray::CSR 2x100 @cpu(0)>
>>> mx->nd->sparse->array(mx->nd->sparse->zeros('csr', [3, 2]))
<AI::MXNet::NDArray::CSR 3x2 @cpu(0)>
>>> mx->nd->sparse->array(mx->nd->sparse->zeros('row_sparse', [3, 2]))
<AI::MXNet::NDArray::RowSparse 3x2 @cpu(0)>