This is an automated email from the ASF dual-hosted git repository.
jxie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-mxnet.git
The following commit(s) were added to refs/heads/master by this push:
new 10a72c8 Python symbol/ndarray api re-org (#7712)
10a72c8 is described below
commit 10a72c8275e462d3052c5d59e73963ce73c1250c
Author: Haibin Lin <[email protected]>
AuthorDate: Thu Sep 7 13:45:21 2017 -0700
Python symbol/ndarray api re-org (#7712)
* add ndarray folder
* add sparse.md draft
* update sparse.md
* add contrib, linalg, random to ndarray.md
* add contrib, linalg random to symbol
* add sparse.md
* update notes and op docs for sparse
* remove unused files
* add back random & la
* fix inherited methods for sparse ndarray
* remove speical members
* fix lint
* add contrib
* add random.md
---
docs/api/python/index.md | 9 +-
docs/api/python/ndarray/contrib.md | 65 ++++++
docs/api/python/ndarray/index.md | 14 ++
docs/api/python/ndarray/linalg.md | 53 +++++
docs/api/python/{ => ndarray}/ndarray.md | 104 +--------
docs/api/python/ndarray/random.md | 55 +++++
docs/api/python/ndarray/sparse.md | 277 +++++++++++++++++++++++
docs/api/python/symbol/contrib.md | 65 ++++++
docs/api/python/symbol/index.md | 14 ++
docs/api/python/symbol/linalg.md | 53 +++++
docs/api/python/symbol/random.md | 55 +++++
docs/api/python/symbol/sparse.md | 113 +++++++++
docs/api/python/{ => symbol}/symbol.md | 57 +----
python/mxnet/ndarray/ndarray.py | 11 +-
python/mxnet/ndarray/sparse.py | 36 ++-
python/mxnet/symbol/contrib.py | 2 +-
python/mxnet/symbol/linalg.py | 2 +-
python/mxnet/symbol/random.py | 2 +-
python/mxnet/symbol/symbol.py | 8 +-
src/operator/contrib/count_sketch.cc | 7 +-
src/operator/contrib/deformable_psroi_pooling.cc | 2 +-
src/operator/contrib/fft.cc | 1 +
src/operator/contrib/ifft.cc | 1 +
src/operator/tensor/cast_storage.cc | 6 +-
src/operator/tensor/init_op.cc | 6 +
25 files changed, 836 insertions(+), 182 deletions(-)
diff --git a/docs/api/python/index.md b/docs/api/python/index.md
index 964ccde..3838abb 100644
--- a/docs/api/python/index.md
+++ b/docs/api/python/index.md
@@ -24,9 +24,14 @@ imported by running:
```eval_rst
.. toctree::
:maxdepth: 2
+ :titlesonly:
+
+ ndarray/index.md
+ symbol/index.md
+
+.. toctree::
+ :maxdepth: 2
- ndarray
- symbol
module
autograd
gluon
diff --git a/docs/api/python/ndarray/contrib.md
b/docs/api/python/ndarray/contrib.md
new file mode 100644
index 0000000..22024bf
--- /dev/null
+++ b/docs/api/python/ndarray/contrib.md
@@ -0,0 +1,65 @@
+# Contrib NDArray API
+
+```eval_rst
+ .. currentmodule:: mxnet.ndarray.contrib
+```
+
+## Overview
+
+This document lists the contrib routines of the *n*-dimensional array package:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ mxnet.ndarray.contrib
+```
+
+The `Contrib NDArray` API, defined in the `ndarray.contrib` package, provides
+many useful experimental APIs for new features.
+This is a place for the community to try out the new features,
+so that feature contributors can receive feedback.
+
+```eval_rst
+.. warning:: This package contains experimental APIs and may change in the
near future.
+```
+
+In the rest of this document, we list routines provided by the
`ndarray.contrib` package.
+
+## Contrib
+
+```eval_rst
+.. currentmodule:: mxnet.ndarray.contrib
+
+.. autosummary::
+ :nosignatures:
+
+ CTCLoss
+ DeformableConvolution
+ DeformablePSROIPooling
+ MultiBoxDetection
+ MultiBoxPrior
+ MultiBoxTarget
+ MultiProposal
+ PSROIPooling
+ Proposal
+ count_sketch
+ ctc_loss
+ dequantize
+ fft
+ ifft
+ quantize
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. automodule:: mxnet.ndarray.contrib
+ :members:
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/ndarray/index.md b/docs/api/python/ndarray/index.md
new file mode 100644
index 0000000..2572e62
--- /dev/null
+++ b/docs/api/python/ndarray/index.md
@@ -0,0 +1,14 @@
+# NDArray API
+
+## Table of Content
+
+```eval_rst
+.. toctree::
+ :maxdepth: 2
+
+ ndarray.md
+ random.md
+ linalg.md
+ sparse.md
+ contrib.md
+```
diff --git a/docs/api/python/ndarray/linalg.md
b/docs/api/python/ndarray/linalg.md
new file mode 100644
index 0000000..6e720cd
--- /dev/null
+++ b/docs/api/python/ndarray/linalg.md
@@ -0,0 +1,53 @@
+# Linear Algebra NDArray API
+
+```eval_rst
+ .. currentmodule:: mxnet.ndarray.linalg
+```
+
+## Overview
+
+This document lists the linear algebra routines of the *n*-dimensional array
package:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ mxnet.ndarray.linalg
+```
+
+The `Linear Algebra NDArray` API, defined in the `ndarray.linalg` package,
provides
+imperative linear algebra tensor operations on CPU/GPU.
+
+In the rest of this document, we list routines provided by the
`ndarray.linalg` package.
+
+## Linear Algebra
+
+```eval_rst
+.. currentmodule:: mxnet.ndarray.linalg
+
+.. autosummary::
+ :nosignatures:
+
+ gemm
+ gemm2
+ potrf
+ potri
+ trmm
+ trsm
+ sumlogdiag
+ syrk
+ gelqf
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. automodule:: mxnet.ndarray.linalg
+ :members:
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/ndarray.md b/docs/api/python/ndarray/ndarray.md
similarity index 79%
rename from docs/api/python/ndarray.md
rename to docs/api/python/ndarray/ndarray.md
index cc8a32d..47f8bfc 100644
--- a/docs/api/python/ndarray.md
+++ b/docs/api/python/ndarray/ndarray.md
@@ -42,7 +42,7 @@ A detailed tutorial is available at
.. note:: ``mxnet.ndarray`` is similar to ``numpy.ndarray`` in some aspects.
But the differences are not negligible. For instance:
- - ``mxnet.ndarray.NDArray.T`` does real data transpose to return new a
copied
+ - ``mxnet.ndarray.NDArray.T`` does real data transpose to return new a
copied
array, instead of returning a view of the input array.
- ``mxnet.ndarray.dot`` performs dot product between the last axis of the
first input array and the first axis of the second input, while
`numpy.dot`
@@ -56,7 +56,7 @@ A detailed tutorial is available at
differs from ``symbol`` in few aspects:
- ``ndarray`` adopts imperative programming, namely sentences are executed
- step-by-step so that the results can be obtained immediately whereas
+ step-by-step so that the results can be obtained immediately whereas
``symbol`` adopts declarative programming.
- Most binary operators in ``ndarray`` such as ``+`` and ``>`` have
@@ -64,8 +64,7 @@ A detailed tutorial is available at
```
In the rest of this document, we first overview the methods provided by the
-`ndarray.NDArray` class and its subclasses, and then list other routines
-provided by the `ndarray` package.
+`ndarray.NDArray` class, and then list other routines provided by the
`ndarray` package.
The `ndarray` package provides several classes:
@@ -78,8 +77,6 @@ The `ndarray` package provides several classes:
sparse.RowSparseNDArray
```
-We summarize the interface for each class in the following sections.
-
## The `NDArray` class
### Array attributes
@@ -278,35 +275,6 @@ We summarize the interface for each class in the following
sections.
NDArray.sign
```
-## The `sparse.RowSparseNDArray` Class
-
-```eval_rst
-.. autosummary::
- :nosignatures:
-
- sparse.RowSparseNDArray.copyto
- sparse.RowSparseNDArray.tostype
- sparse.RowSparseNDArray.__setitem__
- sparse.RowSparseNDArray.__getitem__
- sparse.RowSparseNDArray.data
- sparse.RowSparseNDArray.indices
-```
-
-## The `sparse.CSRNDArray` Class
-
-```eval_rst
-.. autosummary::
- :nosignatures:
-
- sparse.CSRNDArray.copyto
- sparse.CSRNDArray.tostype
- sparse.CSRNDArray.__setitem__
- sparse.CSRNDArray.__getitem__
- sparse.CSRNDArray.data
- sparse.CSRNDArray.indices
- sparse.CSRNDArray.indptr
-```
-
## Array creation routines
```eval_rst
@@ -514,13 +482,6 @@ We summarize the interface for each class in the following
sections.
.. autosummary::
:nosignatures:
- random_uniform
- random_normal
- random_gamma
- random_exponential
- random_poisson
- random_negative_binomial
- random_generalized_negative_binomial
sample_uniform
sample_normal
sample_gamma
@@ -544,21 +505,6 @@ We summarize the interface for each class in the following
sections.
argmin
```
-### Linear Algebra
-
-```eval_rst
-.. autosummary::
- :nosignatures:
-
- linalg_gemm
- linalg_gemm2
- linalg_potrf
- linalg_potri
- linalg_trmm
- linalg_trsm
- linalg_sumlogdiag
-```
-
### Miscellaneous
```eval_rst
@@ -625,37 +571,6 @@ We summarize the interface for each class in the following
sections.
Custom
```
-## Contrib
-
-```eval_rst
-.. warning:: This package contains experimental APIs and may change in the
near future.
-```
-
-The `contrib.ndarray` module contains many useful experimental APIs for new
features. This is a place for the community to try out the new features, so
that feature contributors can receive feedback.
-
-```eval_rst
-.. currentmodule:: mxnet.contrib.ndarray
-
-.. autosummary::
- :nosignatures:
-
- CTCLoss
- DeformableConvolution
- DeformablePSROIPooling
- MultiBoxDetection
- MultiBoxPrior
- MultiBoxTarget
- MultiProposal
- PSROIPooling
- Proposal
- count_sketch
- ctc_loss
- dequantize
- fft
- ifft
- quantize
-```
-
## API Reference
<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
@@ -666,26 +581,15 @@ The `contrib.ndarray` module contains many useful
experimental APIs for new feat
:members:
:special-members:
-.. autoclass:: mxnet.ndarray.sparse.CSRNDArray
- :members:
- :special-members:
-
-.. autoclass:: mxnet.ndarray.sparse.RowSparseNDArray
- :members:
- :special-members:
-
.. automodule:: mxnet.ndarray
:members:
:imported-members:
:special-members:
- :exclude-members: CachedOp, BaseSparseNDArray, NDArray, CSRNDArray,
RowSparseNDArray
+ :exclude-members: CachedOp, NDArray
.. automodule:: mxnet.random
:members:
-.. automodule:: mxnet.contrib.ndarray
- :members:
-
```
<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/ndarray/random.md
b/docs/api/python/ndarray/random.md
new file mode 100644
index 0000000..442ae8c
--- /dev/null
+++ b/docs/api/python/ndarray/random.md
@@ -0,0 +1,55 @@
+# Random Distribution Generator NDArray API
+
+```eval_rst
+ .. currentmodule:: mxnet.ndarray.random
+```
+
+## Overview
+
+This document lists the random distribution generator routines of the
*n*-dimensional array package:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ mxnet.ndarray.random
+```
+
+The `Random Distribution Generator NDArray` API, defined in the
`ndarray.random` package, provides
+imperative random distribution generator operations on CPU/GPU.
+
+In the rest of this document, we list routines provided by the
`ndarray.random` package.
+
+## Random Distribution Generator
+
+```eval_rst
+.. currentmodule:: mxnet.ndarray.random
+
+.. autosummary::
+ :nosignatures:
+
+ exponential
+ gamma
+ generalized_negative_binomial
+ negative_binomial
+ normal
+ poisson
+ uniform
+ mxnet.random.seed
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. automodule:: mxnet.ndarray.random
+ :members:
+
+.. automodule:: mxnet.random
+ :members:
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/ndarray/sparse.md
b/docs/api/python/ndarray/sparse.md
new file mode 100644
index 0000000..d4b8fbd
--- /dev/null
+++ b/docs/api/python/ndarray/sparse.md
@@ -0,0 +1,277 @@
+# Sparse NDArray API
+
+```eval_rst
+.. currentmodule:: mxnet.ndarray.sparse
+```
+
+## Overview
+
+This document lists the routines of the *n*-dimensional sparse array package:
+
+```eval_rst
+.. 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.
+
+```python
+>>> 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'
+```
+
+An `RowSparseNDArray` inherits from `NDArray`, and represents a
multi-dimensional, fixed-size array in row sparse format.
+
+```python
+>>> 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'
+```
+
+```eval_rst
+
+.. 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 reduction 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 section for further details on specific
operators.
+ - GPU support for ``mxnet.ndarray.sparse`` is experimental.
+
+```
+
+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:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ CSRNDArray
+ RowSparseNDArray
+```
+
+We summarize the interface for each class in the following sections.
+
+## The `CSRNDArray` class
+
+### Array attributes
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ CSRNDArray.shape
+ CSRNDArray.size
+ CSRNDArray.context
+ CSRNDArray.dtype
+ CSRNDArray.stype
+ CSRNDArray.data
+ CSRNDArray.indices
+ CSRNDArray.indptr
+```
+
+### Array conversion
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ CSRNDArray.copy
+ CSRNDArray.copyto
+ CSRNDArray.as_in_context
+ CSRNDArray.asnumpy
+ CSRNDArray.asscalar
+ CSRNDArray.astype
+ CSRNDArray.tostype
+```
+
+### Array creation
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ CSRNDArray.zeros_like
+```
+
+### Indexing
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ CSRNDArray.__getitem__
+ CSRNDArray.__setitem__
+ CSRNDArray.slice
+```
+
+### Lazy evaluation
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ CSRNDArray.wait_to_read
+```
+
+## The `RowSparseNDArray` class
+
+### Array attributes
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ RowSparseNDArray.shape
+ RowSparseNDArray.size
+ RowSparseNDArray.context
+ RowSparseNDArray.dtype
+ RowSparseNDArray.stype
+ RowSparseNDArray.data
+ RowSparseNDArray.indices
+```
+
+### Array conversion
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ RowSparseNDArray.copy
+ RowSparseNDArray.copyto
+ RowSparseNDArray.as_in_context
+ RowSparseNDArray.asnumpy
+ RowSparseNDArray.asscalar
+ RowSparseNDArray.astype
+ RowSparseNDArray.tostype
+```
+
+### Array creation
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ RowSparseNDArray.zeros_like
+```
+
+### Indexing
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ RowSparseNDArray.__getitem__
+ RowSparseNDArray.__setitem__
+```
+
+### Lazy evaluation
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ RowSparseNDArray.wait_to_read
+```
+
+## Array creation routines
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ array
+ empty
+ zeros
+ zeros_like
+ csr_matrix
+ row_sparse_array
+```
+
+## Array manipulation routines
+
+### Changing array storage type
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ cast_storage
+```
+
+### Indexing routines
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ slice
+ retain
+```
+
+## Mathematical functions
+
+### Arithmetic operations
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ elemwise_add
+ dot
+ add_n
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. autoclass:: mxnet.ndarray.sparse.CSRNDArray
+ :members: shape, size, context, dtype, stype, data, indices, indptr, copy,
copyto, as_in_context, asnumpy, asscalar, astype, tostype, slice, wait_to_read,
zeros_like, __getitem__, __setitem__
+
+.. autoclass:: mxnet.ndarray.sparse.RowSparseNDArray
+ :members: shape, size, context, dtype, stype, data, indices, copy, copyto,
as_in_context, asnumpy, asscalar, astype, tostype, wait_to_read, zeros_like,
__getitem__, __setitem__
+
+.. automodule:: mxnet.ndarray.sparse
+ :members:
+ :special-members:
+ :exclude-members: BaseSparseNDArray, RowSparseNDArray, CSRNDArray
+
+.. automodule:: mxnet.ndarray.sparse
+ :members: array, zeros, empty
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/symbol/contrib.md
b/docs/api/python/symbol/contrib.md
new file mode 100644
index 0000000..e9f9854
--- /dev/null
+++ b/docs/api/python/symbol/contrib.md
@@ -0,0 +1,65 @@
+# Contrib Symbol API
+
+```eval_rst
+ .. currentmodule:: mxnet.symbol.contrib
+```
+
+## Overview
+
+This document lists the contrib routines of the symbolic expression package:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ mxnet.symbol.contrib
+```
+
+The `Contrib Symbol` API, defined in the `symbol.contrib` package, provides
+many useful experimental APIs for new features.
+This is a place for the community to try out the new features,
+so that feature contributors can receive feedback.
+
+```eval_rst
+.. warning:: This package contains experimental APIs and may change in the
near future.
+```
+
+In the rest of this document, we list routines provided by the
`symbol.contrib` package.
+
+## Contrib
+
+```eval_rst
+.. currentmodule:: mxnet.symbol.contrib
+
+.. autosummary::
+ :nosignatures:
+
+ CTCLoss
+ DeformableConvolution
+ DeformablePSROIPooling
+ MultiBoxDetection
+ MultiBoxPrior
+ MultiBoxTarget
+ MultiProposal
+ PSROIPooling
+ Proposal
+ count_sketch
+ ctc_loss
+ dequantize
+ fft
+ ifft
+ quantize
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. automodule:: mxnet.symbol.contrib
+ :members:
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/symbol/index.md b/docs/api/python/symbol/index.md
new file mode 100644
index 0000000..3e8ddbb
--- /dev/null
+++ b/docs/api/python/symbol/index.md
@@ -0,0 +1,14 @@
+# Symbol API
+
+## Table of Content
+
+```eval_rst
+.. toctree::
+ :maxdepth: 2
+
+ symbol.md
+ random.md
+ linalg.md
+ sparse.md
+ contrib.md
+```
diff --git a/docs/api/python/symbol/linalg.md b/docs/api/python/symbol/linalg.md
new file mode 100644
index 0000000..7e7bd1c
--- /dev/null
+++ b/docs/api/python/symbol/linalg.md
@@ -0,0 +1,53 @@
+# Linear Algebra Symbol API
+
+```eval_rst
+ .. currentmodule:: mxnet.symbol.linalg
+```
+
+## Overview
+
+This document lists the linear algebra routines of the symbolic expression
package:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ mxnet.symbol.linalg
+```
+
+The `Linear Algebra Symbol` API, defined in the `symbol.linalg` package,
provides
+symbolic expressions for linear algebra routines.
+
+In the rest of this document, we list routines provided by the `symbol.linalg`
package.
+
+## Linear Algebra
+
+```eval_rst
+.. currentmodule:: mxnet.symbol.linalg
+
+.. autosummary::
+ :nosignatures:
+
+ gemm
+ gemm2
+ potrf
+ potri
+ trmm
+ trsm
+ sumlogdiag
+ syrk
+ gelqf
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. automodule:: mxnet.symbol.linalg
+ :members:
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/symbol/random.md b/docs/api/python/symbol/random.md
new file mode 100644
index 0000000..f202a46
--- /dev/null
+++ b/docs/api/python/symbol/random.md
@@ -0,0 +1,55 @@
+# Random Distribution Generator Symbol API
+
+```eval_rst
+ .. currentmodule:: mxnet.symbol.random
+```
+
+## Overview
+
+This document lists the random distribution generator routines of the symbolic
expression package:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ mxnet.symbol.random
+```
+
+The `Random Distribution Generator Symbol` API, defined in the `symbol.random`
package, provides
+symbolic expressions for random distribution generator routines.
+
+In the rest of this document, we list routines provided by the `symbol.random`
package.
+
+## Random Distribution Generator
+
+```eval_rst
+.. currentmodule:: mxnet.symbol.random
+
+.. autosummary::
+ :nosignatures:
+
+ exponential
+ gamma
+ generalized_negative_binomial
+ negative_binomial
+ normal
+ poisson
+ uniform
+ mxnet.random.seed
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. automodule:: mxnet.symbol.random
+ :members:
+
+.. automodule:: mxnet.random
+ :members:
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/symbol/sparse.md b/docs/api/python/symbol/sparse.md
new file mode 100644
index 0000000..650fb0b
--- /dev/null
+++ b/docs/api/python/symbol/sparse.md
@@ -0,0 +1,113 @@
+# Sparse Symbol API
+
+```eval_rst
+ .. currentmodule:: mxnet.symbol.sparse
+```
+
+## Overview
+
+This document lists the routines of the sparse symbolic expression package:
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ mxnet.symbol.sparse
+```
+
+The `Sparse Symbol` API, defined in the `symbol.sparse` package, provides
+sparse neural network graphs and auto-differentiation on CPU.
+
+The storage type of a variable is speficied by the `stype` attribute of the
variable.
+The storage type of a symbolic expression is inferred based on the storage
types of the variables and the operators.
+
+```python
+>>> a = mx.sym.Variable('a', stype='csr')
+>>> b = mx.sym.Variable('b')
+>>> c = mx.sym.dot(a, b, transpose_a=True)
+>>> type(c)
+<class 'mxnet.symbol.Symbol'>
+>>> e = c.bind(mx.cpu(), {'a': mx.nd.array([[1,0,0]]).tostype('csr'),
'b':mx.nd.ones((1,2))})
+>>> y = e.forward()
+# the result storage type of dot(csr.T, dense) is inferred to be `row_sparse`
+>>> y
+[<RowSparseNDArray 3x2 @cpu(0)>]
+>>> y[0].asnumpy()
+array([ 1., 1.],
+ [ 0., 0.],
+ [ 0., 0.]], dtype=float32)
+```
+
+```eval_rst
+
+.. note:: most operators provided in ``mxnet.symbol.sparse`` are similar to
those in
+ ``mxnet.symbol`` although there are few differences:
+
+ - Only a subset of operators in ``mxnet.symbol`` have specialized
implementations in ``mxnet.symbol.sparse``.
+ Operators such as reduction 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.symbol.sparse`` infer
"default" (dense) storage type for outputs.
+ Please refer to the API reference section for further details on specific
operators.
+ - GPU support for ``mxnet.symbol.sparse`` is experimental.
+
+```
+
+In the rest of this document, we list sparse related routines provided by the
+`symbol.sparse` package.
+
+## Symbol creation routines
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ zeros_like
+ mxnet.symbol.var
+```
+
+## Symbol manipulation routines
+
+### Changing symbol storage type
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ cast_storage
+```
+
+### Indexing routines
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ slice
+ retain
+```
+
+## Mathematical functions
+
+### Arithmetic operations
+
+```eval_rst
+.. autosummary::
+ :nosignatures:
+
+ elemwise_add
+ dot
+ add_n
+```
+
+## API Reference
+
+<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
+
+```eval_rst
+
+.. automodule:: mxnet.symbol.sparse
+ :members:
+
+```
+
+<script>auto_index("api-reference");</script>
diff --git a/docs/api/python/symbol.md b/docs/api/python/symbol/symbol.md
similarity index 88%
rename from docs/api/python/symbol.md
rename to docs/api/python/symbol/symbol.md
index 05d9468..8d558ff 100644
--- a/docs/api/python/symbol.md
+++ b/docs/api/python/symbol/symbol.md
@@ -483,13 +483,6 @@ Composite multiple symbols into a new one by an operator.
.. autosummary::
:nosignatures:
- random_uniform
- random_normal
- random_gamma
- random_exponential
- random_poisson
- random_negative_binomial
- random_generalized_negative_binomial
sample_uniform
sample_normal
sample_gamma
@@ -513,23 +506,6 @@ Composite multiple symbols into a new one by an operator.
argmin
```
-### Linear Algebra
-
-```eval_rst
-.. autosummary::
- :nosignatures:
-
- linalg_gemm
- linalg_gemm2
- linalg_potrf
- linalg_potri
- linalg_trmm
- linalg_trsm
- linalg_sumlogdiag
- linalg_syrk
- linalg_gelqf
-```
-
### Miscellaneous
```eval_rst
@@ -598,37 +574,6 @@ Composite multiple symbols into a new one by an operator.
Custom
```
-## Contrib
-
-```eval_rst
-.. warning:: This package contains experimental APIs and may change in the
near future.
-```
-
-The `contrib.symbol` module contains many useful experimental APIs for new
features. This is a place for the community to try out the new features, so
that feature contributors can receive feedback.
-
-```eval_rst
-.. currentmodule:: mxnet.contrib.symbol
-
-.. autosummary::
- :nosignatures:
-
- CTCLoss
- DeformableConvolution
- DeformablePSROIPooling
- MultiBoxDetection
- MultiBoxPrior
- MultiBoxTarget
- MultiProposal
- PSROIPooling
- Proposal
- count_sketch
- ctc_loss
- dequantize
- fft
- ifft
- quantize
-```
-
## API Reference
<script type="text/javascript"
src='../../_static/js/auto_module_index.js'></script>
@@ -645,7 +590,7 @@ The `contrib.symbol` module contains many useful
experimental APIs for new featu
:special-members:
:exclude-members: Symbol
-.. automodule:: mxnet.contrib.symbol
+.. automodule:: mxnet.symbol.random
:members:
```
diff --git a/python/mxnet/ndarray/ndarray.py b/python/mxnet/ndarray/ndarray.py
index 670ecd9..8347571 100644
--- a/python/mxnet/ndarray/ndarray.py
+++ b/python/mxnet/ndarray/ndarray.py
@@ -1287,6 +1287,11 @@ fixed-size items.
dtype : numpy.dtype or str
The type of the returned array.
+ Returns
+ -------
+ NDArray, CSRNDArray or RowSparseNDArray
+ The copied array after casting to the specified type.
+
Examples
--------
>>> x = mx.nd.zeros((2,3), dtype='float32')
@@ -1315,7 +1320,7 @@ fixed-size items.
Returns
-------
- NDArray, CSRNDArray, RowSparseNDArray
+ NDArray, CSRNDArray or RowSparseNDArray
The copied array. If ``other`` is an ``NDArray``, then the return
value
and ``other`` will point to the same ``NDArray``.
@@ -1349,7 +1354,7 @@ fixed-size items.
Returns
-------
- NDArray
+ NDArray, CSRNDArray or RowSparseNDArray
The copied array
Examples
@@ -1375,7 +1380,7 @@ fixed-size items.
Returns
-------
- NDArray
+ NDArray, CSRNDArray or RowSparseNDArray
The target array.
diff --git a/python/mxnet/ndarray/sparse.py b/python/mxnet/ndarray/sparse.py
index fa2761d..15d445f 100644
--- a/python/mxnet/ndarray/sparse.py
+++ b/python/mxnet/ndarray/sparse.py
@@ -52,7 +52,7 @@ from .ndarray import array as _array
from . import op
# When possible, use cython to speedup part of computation.
-# pylint: disable=unused-import
+# pylint: disable=unused-import, too-many-lines
try:
if int(_os.environ.get("MXNET_ENABLE_CYTHON", True)) == 0:
from .._ctypes.ndarray import _set_ndarray_class
@@ -190,7 +190,7 @@ class BaseSparseNDArray(NDArray):
The type of the returned array.
Examples
--------
- >>> x = mx.nd.zeros('row_sparse', (2,3), dtype='float32')
+ >>> x = mx.nd.sparse.zeros('row_sparse', (2,3), dtype='float32')
>>> y = x.astype('int32')
>>> y.dtype
<type 'numpy.int32'>
@@ -346,7 +346,7 @@ class CSRNDArray(BaseSparseNDArray):
Examples
--------
- >>> src = mx.nd.zeros((3,3), stype='csr')
+ >>> src = mx.nd.sparse.zeros('csr', (3,3))
>>> src.asnumpy()
array([[ 0., 0., 0.],
[ 0., 0., 0.],
@@ -556,7 +556,7 @@ class RowSparseNDArray(BaseSparseNDArray):
Examples
--------
- >>> x = mx.nd.zeros((2, 3), stype='row_sparse')
+ >>> x = mx.nd.sparse.zeros('row_sparse', (2, 3))
>>> x[:].asnumpy()
array([[ 0., 0., 0.],
[ 0., 0., 0.]], dtype=float32)
@@ -591,7 +591,7 @@ class RowSparseNDArray(BaseSparseNDArray):
[ 0., 0., 0.],
[ 4., 5., 6.]], dtype=float32)
>>> # assign RowSparseNDArray with same storage type
- >>> x = mx.nd.zeros('row_sparse', (3,3))
+ >>> x = mx.nd.sparse.zeros('row_sparse', (3,3))
>>> x[:] = src
>>> x.asnumpy()
array([[ 1., 0., 2.],
@@ -723,7 +723,7 @@ def _prepare_src_array(src, dtype, default_dtype):
def csr_matrix(data, indptr, indices, shape, ctx=None, dtype=None,
indptr_type=None,
indices_type=None):
- """Creates a 2D array with compressed sparse row(CSR) format.
+ """Creates a 2D array with compressed sparse row (CSR) format.
Parameters
----------
@@ -900,9 +900,9 @@ def zeros(stype, shape, ctx=None, dtype=None,
aux_types=None, **kwargs):
A created array
Examples
--------
- >>> mx.nd.zeros((1,2), mx.cpu(), stype='csr')
+ >>> mx.nd.sparse.zeros('csr', (1,2))
<CSRNDArray 1x2 @cpu(0)>
- >>> mx.nd.zeros((1,2), mx.cpu(), 'float16', stype='row_sparse').asnumpy()
+ >>> mx.nd.sparse.zeros('row_sparse', (1,2), ctx=mx.cpu(),
dtype='float16').asnumpy()
array([[ 0., 0.]], dtype=float16)
"""
if stype == 'default':
@@ -922,6 +922,22 @@ def zeros(stype, shape, ctx=None, dtype=None,
aux_types=None, **kwargs):
def empty(stype, shape, ctx=None, dtype=None, aux_types=None):
"""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 tuple of int
+ The shape of the empty array.
+ ctx : Context, optional
+ An optional device context (default is the current default context).
+ dtype : str or numpy.dtype, optional
+ An optional value type (default is `float32`).
+
+ Returns
+ -------
+ CSRNDArray or RowSparseNDArray
+ A created array.
"""
if isinstance(shape, int):
shape = (shape, )
@@ -964,9 +980,9 @@ def array(source_array, ctx=None, dtype=None,
aux_types=None):
>>> csr = sp.csr_matrix((2, 100))
>>> mx.nd.sparse.array(csr)
<CSRNDArray 2x100 @cpu(0)>
- >>> mx.nd.sparse.array(mx.nd.zeros((3, 2), stype='csr'))
+ >>> mx.nd.sparse.array(mx.nd.sparse.zeros('csr', (3, 2)))
<CSRNDArray 3x2 @cpu(0)>
- >>> mx.nd.sparse.array(mx.nd.zeros((3, 2), stype='row_sparse'))
+ >>> mx.nd.sparse.array(mx.nd.sparse.zeros('row_sparse', (3, 2)))
<RowSparseNDArray 3x2 @cpu(0)>
"""
if isinstance(source_array, NDArray):
diff --git a/python/mxnet/symbol/contrib.py b/python/mxnet/symbol/contrib.py
index f21d144..ff5aa37 100644
--- a/python/mxnet/symbol/contrib.py
+++ b/python/mxnet/symbol/contrib.py
@@ -15,5 +15,5 @@
# specific language governing permissions and limitations
# under the License.
-"""Contrib NDArray API of MXNet."""
+"""Contrib Symbol API of MXNet."""
__all__ = []
diff --git a/python/mxnet/symbol/linalg.py b/python/mxnet/symbol/linalg.py
index 0c8e7fd..58514ba 100644
--- a/python/mxnet/symbol/linalg.py
+++ b/python/mxnet/symbol/linalg.py
@@ -15,5 +15,5 @@
# specific language governing permissions and limitations
# under the License.
-"""Linear Algebra NDArray API of MXNet."""
+"""Linear Algebra Symbol API of MXNet."""
__all__ = []
diff --git a/python/mxnet/symbol/random.py b/python/mxnet/symbol/random.py
index 0ec4578..75ff7ed 100644
--- a/python/mxnet/symbol/random.py
+++ b/python/mxnet/symbol/random.py
@@ -15,5 +15,5 @@
# specific language governing permissions and limitations
# under the License.
-"""Random distribution generator NDArray API of MXNet."""
+"""Random Distribution Generator Symbol API of MXNet."""
__all__ = []
diff --git a/python/mxnet/symbol/symbol.py b/python/mxnet/symbol/symbol.py
index cc128b2..2a7d5ba 100644
--- a/python/mxnet/symbol/symbol.py
+++ b/python/mxnet/symbol/symbol.py
@@ -2102,6 +2102,12 @@ def var(name, attr=None, shape=None, lr_mult=None,
wd_mult=None, dtype=None,
>>> data = mx.sym.Variable('data', attr={'a': 'b'})
>>> data
<Symbol data>
+ >>> csr_data = mx.sym.Variable('csr_data', stype='csr')
+ >>> csr_data
+ <Symbol csr_data>
+ >>> row_sparse_weight = mx.sym.Variable('weight', stype='row_sparse')
+ >>> row_sparse_weight
+ <Symbol weight>
Parameters
----------
@@ -2122,7 +2128,7 @@ def var(name, attr=None, shape=None, lr_mult=None,
wd_mult=None, dtype=None,
init : initializer (mxnet.init.*)
Initializer for this variable to (optionally) override the default
initializer.
stype : str
- The storage type of the variable.
+ The storage type of the variable, such as 'row_sparse', 'csr',
'default', etc
kwargs : Additional attribute variables
Additional attributes must start and end with double underscores.
diff --git a/src/operator/contrib/count_sketch.cc
b/src/operator/contrib/count_sketch.cc
index 6aba8f4..000425f 100644
--- a/src/operator/contrib/count_sketch.cc
+++ b/src/operator/contrib/count_sketch.cc
@@ -55,12 +55,13 @@ Then the operator computs:
out[h[i]] += data[i] * s[i]
Example::
+
out_dim = 5
x = [[1.2, 2.5, 3.4],[3.2, 5.7, 6.6]]
- h = [0, 3, 4]
- s = [1, -1, 1]
+ h = [[0, 3, 4]]
+ s = [[1, -1, 1]]
mx.contrib.ndarray.count_sketch(data=x, h=h, s=s, out_dim = 5) = [[1.2, 0,
0, -2.5, 3.4],
- [3.2, 0,
0, -5.7, 6.6]]
+ [3.2, 0,
0, -5.7, 6.6]]
)code" ADD_FILELINE)
.add_argument("data", "NDArray-or-Symbol", "Input data to the CountSketchOp.")
diff --git a/src/operator/contrib/deformable_psroi_pooling.cc
b/src/operator/contrib/deformable_psroi_pooling.cc
index 47f369a..42cf6f1 100644
--- a/src/operator/contrib/deformable_psroi_pooling.cc
+++ b/src/operator/contrib/deformable_psroi_pooling.cc
@@ -101,7 +101,7 @@ namespace op {
DMLC_REGISTER_PARAMETER(DeformablePSROIPoolingParam);
MXNET_REGISTER_OP_PROPERTY(_contrib_DeformablePSROIPooling,
DeformablePSROIPoolingProp)
- .describe("Performs deformable position-sensitive region-of-interest
pooling on inputs."
+ .describe("Performs deformable position-sensitive region-of-interest
pooling on inputs.\n"
"The DeformablePSROIPooling operation is described in
https://arxiv.org/abs/1703.06211 ."
"batch_size will change to the number of region bounding boxes after
DeformablePSROIPooling")
.add_argument("data", "Symbol", "Input data to the pooling operator, a 4D
Feature maps")
diff --git a/src/operator/contrib/fft.cc b/src/operator/contrib/fft.cc
index 6f78003..0b31a92 100644
--- a/src/operator/contrib/fft.cc
+++ b/src/operator/contrib/fft.cc
@@ -48,6 +48,7 @@ Currently accept 2 input data shapes: (N, d) or (N1, N2, N3,
d), data can only b
The output data has shape: (N, 2*d) or (N1, N2, N3, 2*d). The format is:
[real0, imag0, real1, imag1, ...].
Example::
+
data = np.random.normal(0,1,(3,4))
out = mx.contrib.ndarray.fft(data = mx.nd.array(data,ctx = mx.gpu(0)))
diff --git a/src/operator/contrib/ifft.cc b/src/operator/contrib/ifft.cc
index 95c79a7..f57df69 100644
--- a/src/operator/contrib/ifft.cc
+++ b/src/operator/contrib/ifft.cc
@@ -50,6 +50,7 @@ Last dimension must be an even number.
The output data has shape: (N, d/2) or (N1, N2, N3, d/2). It is only the real
part of the result.
Example::
+
data = np.random.normal(0,1,(3,4))
out = mx.contrib.ndarray.ifft(data = mx.nd.array(data,ctx = mx.gpu(0)))
diff --git a/src/operator/tensor/cast_storage.cc
b/src/operator/tensor/cast_storage.cc
index b5de8d0..604e4fb 100644
--- a/src/operator/tensor/cast_storage.cc
+++ b/src/operator/tensor/cast_storage.cc
@@ -55,13 +55,13 @@ Example::
[ 0., 0., 0.]]
# cast to row_sparse storage type
- rsp = cast_storage(default, 'default')
+ rsp = cast_storage(default, 'row_sparse')
rsp.indices = [0, 1]
rsp.values = [[ 0., 1., 0.],
[ 2., 0., 3.]]
- # cast to row_sparse storage type
- csr = cast_storage(default, 'default')
+ # cast to csr storage type
+ csr = cast_storage(default, 'csr')
csr.indices = [1, 0, 2]
csr.values = [ 1., 2., 3.]
csr.indptr = [0, 1, 3, 3, 3]
diff --git a/src/operator/tensor/init_op.cc b/src/operator/tensor/init_op.cc
index 37296c5..e6a0c9b 100644
--- a/src/operator/tensor/init_op.cc
+++ b/src/operator/tensor/init_op.cc
@@ -67,6 +67,12 @@ NNVM_REGISTER_OP(zeros_like)
.describe(R"code(Return an array of zeros with the same shape and type
as the input array.
+The storage type of ``zeros_like`` output depends on the storage type of the
input
+
+- zeros_like(row_sparse) = row_sparse
+- zeros_like(csr) = csr
+- zeros_like(default) = default
+
Examples::
x = [[ 1., 1., 1.],
--
To stop receiving notification emails like this one, please contact
['"[email protected]" <[email protected]>'].
