├── .gitignore ├── Jenkinsfile ├── LICENSE ├── README.md ├── api ├── deepnumpy │ ├── arrays.indexing.rst │ ├── arrays.ndarray.rst │ ├── arrays.rst │ ├── index.rst │ ├── npx.rst │ ├── random │ │ └── index.rst │ ├── routines.array-creation.rst │ ├── routines.array-manipulation.rst │ ├── routines.io.rst │ ├── routines.linalg.rst │ ├── routines.math.rst │ ├── routines.rst │ ├── routines.sort.rst │ └── routines.statistics.rst ├── gluon │ ├── block.rst │ ├── container.rst │ ├── creation.rst │ ├── data.rst │ ├── index.rst │ ├── loss.rst │ ├── modelzoo.rst │ ├── mxnet.autograd.rst │ ├── mxnet.gluon.Parameter.rst │ ├── mxnet.gluon.ParameterDict.rst │ ├── mxnet.gluon.Trainer.rst │ ├── mxnet.initializer.rst │ ├── mxnet.lr_scheduler.rst │ ├── mxnet.optimizer.rst │ ├── nn.rst │ ├── parameter.rst │ ├── rnn.rst │ ├── training.rst │ └── utils.rst └── index.rst ├── build_html.sh ├── config.ini ├── guide ├── crash-course │ ├── 1-ndarray.md │ ├── 2-nn.md │ ├── 3-autograd.md │ ├── 4-train.md │ ├── 5-predict.md │ ├── 6-use_gpus.md │ └── index.rst ├── deepnumpy │ ├── cheat-sheet.md │ ├── deepnumpy-vs-numpy.md │ └── index.rst ├── gluon │ └── index.rst └── index.rst ├── index.rst ├── install └── install-include.rst └── static ├── autosummary ├── base.rst ├── class.rst └── module.rst ├── disqus.js ├── install-options.js ├── mxnet-icon.png ├── mxnet-logo.svg └── mxnet.css /.gitignore: -------------------------------------------------------------------------------- 1 | /_build/ 2 | /guide/deepnumpy/my_array 3 | /guide/deepnumpy/my_arrays 4 | /guide/deepnumpy/.ipynb_checkpoints/cheat-sheet-checkpoint.md 5 | .idea 6 | .DS_Store 7 | **/.ipynb_checkpoints/* 8 | *.jpg 9 | *.params 10 | *.txt 11 | -------------------------------------------------------------------------------- /Jenkinsfile: -------------------------------------------------------------------------------- 1 | stage("Build and Publish") { 2 | def TASK = "numpy-api-doc" 3 | node { 4 | ws("workspace/${TASK}") { 5 | checkout scm 6 | def ENV_NAME = "${TASK}-${EXECUTOR_NUMBER}"; 7 | 8 | sh label: "Build Environment", script: """set -ex 9 | rm -rf ~/miniconda3/envs/${ENV_NAME} 10 | conda create -n ${ENV_NAME} pip -y 11 | conda activate ${ENV_NAME} 12 | pip install mxnet-cu101==1.6.0b20191122 13 | pip install git+https://github.com/d2l-ai/d2l-book@f26c20923edd4fb9fe9e6eb6e8d4b8976e41c22a 14 | pip install matplotlib 15 | pip list 16 | """ 17 | 18 | sh label:"Build HTML", script:"""set -ex 19 | conda activate ${ENV_NAME} 20 | ./build_html.sh 21 | """ 22 | 23 | if (env.BRANCH_NAME == 'master') { 24 | sh label:"Publish", script:"""set -ex 25 | conda activate ${ENV_NAME} 26 | d2lbook deploy html 27 | """ 28 | } 29 | } 30 | } 31 | } 32 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Documents for MXNet with NP on MXNet 2 | 3 | 4 | How to build 5 | 6 | 1. Assume you have MXNet's NumPy branch compiled and installed. 7 | 2. `pip install git+https://github.com/d2l-ai/d2l-book` 8 | 3. `bash build_html.sh` 9 | -------------------------------------------------------------------------------- /api/deepnumpy/arrays.indexing.rst: -------------------------------------------------------------------------------- 1 | .. _arrays.indexing: 2 | 3 | Indexing 4 | ======== 5 | 6 | .. sectionauthor:: adapted from "Guide to NumPy" by Travis E. Oliphant 7 | 8 | .. currentmodule:: mxnet.np 9 | 10 | .. index:: indexing, slicing 11 | 12 | :class:`ndarrays ` can be indexed using the standard Python 13 | ``x[obj]`` syntax, where *x* is the array and *obj* the selection. 14 | There are three kinds of indexing available: basic 15 | slicing, advanced indexing, and boolean mask indexing. Which one occurs depends on *obj*. 16 | 17 | .. note:: 18 | 19 | In Python, ``x[(exp1, exp2, ..., expN)]`` is equivalent to 20 | ``x[exp1, exp2, ..., expN]``; the latter is just syntactic sugar 21 | for the former. 22 | 23 | 24 | Basic Slicing and Indexing 25 | -------------------------- 26 | 27 | Basic slicing extends Python's basic concept of slicing to N 28 | dimensions. Basic slicing occurs when *obj* is a :class:`slice` object 29 | (constructed by ``start:stop:step`` notation inside of brackets), an 30 | integer, or a tuple of slice objects and integers. :const:`Ellipsis` 31 | and :const:`newaxis` objects can be interspersed with these as 32 | well. 33 | 34 | The simplest case of indexing with *N* integers returns an :ref:`array 35 | scalar ` representing the corresponding item. As in 36 | Python, all indices are zero-based: for the *i*-th index :math:`n_i`, 37 | the valid range is :math:`0 \le n_i < d_i` where :math:`d_i` is the 38 | *i*-th element of the shape of the array. Negative indices are 39 | interpreted as counting from the end of the array (*i.e.*, if 40 | :math:`n_i < 0`, it means :math:`n_i + d_i`). 41 | 42 | All arrays generated by basic slicing are always :term:`views ` 43 | of the original array if the fetched elements are contiguous in memory. 44 | 45 | The standard rules of sequence slicing apply to basic slicing on a 46 | per-dimension basis (including using a step index). Some useful 47 | concepts to remember include: 48 | 49 | - The basic slice syntax is ``i:j:k`` where *i* is the starting index, 50 | *j* is the stopping index, and *k* is the step (:math:`k\neq0`). 51 | This selects the *m* elements (in the corresponding dimension) with 52 | index values *i*, *i + k*, ..., *i + (m - 1) k* where 53 | :math:`m = q + (r\neq0)` and *q* and *r* are the quotient and remainder 54 | obtained by dividing *j - i* by *k*: *j - i = q k + r*, so that 55 | *i + (m - 1) k < j*. 56 | 57 | .. admonition:: Example 58 | 59 | >>> x = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) 60 | >>> x[1:7:2] 61 | array([1, 3, 5]) 62 | 63 | - Negative *i* and *j* are interpreted as *n + i* and *n + j* where 64 | *n* is the number of elements in the corresponding dimension. 65 | Negative *k* makes stepping go towards smaller indices. 66 | 67 | .. admonition:: Example 68 | 69 | >>> x[-2:10] 70 | array([8, 9]) 71 | >>> x[-3:3:-1] 72 | array([7, 6, 5, 4]) 73 | 74 | - Assume *n* is the number of elements in the dimension being 75 | sliced. Then, if *i* is not given it defaults to 0 for *k > 0* and 76 | *n - 1* for *k < 0* . If *j* is not given it defaults to *n* for *k > 0* 77 | and *-n-1* for *k < 0* . If *k* is not given it defaults to 1. Note that 78 | ``::`` is the same as ``:`` and means select all indices along this 79 | axis. 80 | 81 | .. admonition:: Example 82 | 83 | >>> x[5:] 84 | array([5, 6, 7, 8, 9]) 85 | 86 | - If the number of objects in the selection tuple is less than 87 | *N* , then ``:`` is assumed for any subsequent dimensions. 88 | 89 | .. admonition:: Example 90 | 91 | >>> x = np.array([[[1],[2],[3]], [[4],[5],[6]]]) 92 | >>> x.shape 93 | (2, 3, 1) 94 | >>> x[1:2] 95 | array([[[4], 96 | [5], 97 | [6]]]) 98 | 99 | - :const:`Ellipsis` expands to the number of ``:`` objects needed for the 100 | selection tuple to index all dimensions. In most cases, this means that 101 | length of the expanded selection tuple is ``x.ndim``. There may only be a 102 | single ellipsis present. 103 | 104 | .. admonition:: Example 105 | 106 | >>> x[...,0] 107 | array([[1, 2, 3], 108 | [4, 5, 6]]) 109 | 110 | - Each :const:`newaxis` object in the selection tuple serves to expand 111 | the dimensions of the resulting selection by one unit-length 112 | dimension. The added dimension is the position of the :const:`newaxis` 113 | object in the selection tuple. 114 | 115 | .. admonition:: Example 116 | 117 | >>> x[:,np.newaxis,:,:].shape 118 | (2, 1, 3, 1) 119 | 120 | - An integer, *i*, returns the same values as ``i:i+1`` 121 | **except** the dimensionality of the returned object is reduced by 122 | 1. In particular, a selection tuple with the *p*-th 123 | element an integer (and all other entries ``:``) returns the 124 | corresponding sub-array with dimension *N - 1*. If *N = 1* 125 | then the returned object is an scalar `ndarray` whose `ndim=0`. 126 | 127 | - If the selection tuple has all entries ``:`` except the 128 | *p*-th entry which is a slice object ``i:j:k``, 129 | then the returned array has dimension *N* formed by 130 | concatenating the sub-arrays returned by integer indexing of 131 | elements *i*, *i+k*, ..., *i + (m - 1) k < j*, 132 | 133 | - Basic slicing with more than one non-``:`` entry in the slicing 134 | tuple, acts like repeated application of slicing using a single 135 | non-``:`` entry, where the non-``:`` entries are successively taken 136 | (with all other non-``:`` entries replaced by ``:``). Thus, 137 | ``x[ind1,...,ind2,:]`` acts like ``x[ind1][...,ind2,:]`` under basic 138 | slicing. 139 | 140 | .. warning:: The above is **not** true for advanced indexing. 141 | 142 | - You may use slicing to set values in the array, but (unlike lists) you 143 | can never grow the array. The size of the value to be set in 144 | ``x[obj] = value`` must be (broadcastable) to the same shape as 145 | ``x[obj]``. 146 | 147 | .. note:: 148 | 149 | Remember that a slicing tuple can always be constructed as *obj* 150 | and used in the ``x[obj]`` notation. Slice objects can be used in 151 | the construction in place of the ``[start:stop:step]`` 152 | notation. For example, ``x[1:10:5,::-1]`` can also be implemented 153 | as ``obj = (slice(1,10,5), slice(None,None,-1)); x[obj]`` . This 154 | can be useful for constructing generic code that works on arrays 155 | of arbitrary dimension. 156 | 157 | .. data:: newaxis 158 | :noindex: 159 | 160 | The :const:`newaxis` object can be used in all slicing operations to 161 | create an axis of length one. :const:`newaxis` is an alias for 162 | 'None', and 'None' can be used in place of this with the same result. 163 | 164 | 165 | Advanced Indexing 166 | ----------------- 167 | 168 | Advanced indexing is triggered when the selection object, *obj*, is a 169 | non-tuple sequence object, an :class:`ndarray` (of data type integer or bool), 170 | or a tuple with at least one sequence object or ndarray (of data type 171 | integer or bool). There are two types of advanced indexing: integer 172 | and Boolean. 173 | 174 | Advanced indexing always returns a *copy* of the data (contrast with 175 | some cases in basic slicing that returns a :term:`view`). 176 | 177 | .. warning:: 178 | 179 | The definition of advanced indexing means that ``x[(1,2,3),]`` is 180 | fundamentally different than ``x[(1,2,3)]``. The latter is 181 | equivalent to ``x[1,2,3]`` which will trigger basic selection while 182 | the former will trigger advanced indexing. Be sure to understand 183 | why this occurs. 184 | 185 | Also recognize that ``x[[1,2,3]]`` will trigger advanced indexing, 186 | whereas due to the deprecated Numeric compatibility mentioned above, 187 | ``x[[1,2,slice(None)]]`` will trigger basic slicing in the official NumPy 188 | which is not currently supported in MXNet `numpy` module. 189 | 190 | Integer array indexing 191 | ^^^^^^^^^^^^^^^^^^^^^^ 192 | 193 | Integer array indexing allows selection of arbitrary items in the array 194 | based on their *N*-dimensional index. Each integer array represents a number 195 | of indexes into that dimension. 196 | 197 | Purely integer array indexing 198 | """"""""""""""""""""""""""""" 199 | 200 | When the index consists of as many integer arrays as the array being indexed 201 | has dimensions, the indexing is straight forward, but different from slicing. 202 | 203 | Advanced indexes always are broadcasting and 204 | iterated as *one*:: 205 | 206 | result[i_1, ..., i_M] == x[ind_1[i_1, ..., i_M], ind_2[i_1, ..., i_M], 207 | ..., ind_N[i_1, ..., i_M]] 208 | 209 | Note that the result shape is identical to the (broadcast) indexing array 210 | shapes ``ind_1, ..., ind_N``. 211 | 212 | .. admonition:: Example 213 | 214 | From each row, a specific element should be selected. The row index is just 215 | ``[0, 1, 2]`` and the column index specifies the element to choose for the 216 | corresponding row, here ``[0, 1, 0]``. Using both together the task 217 | can be solved using advanced indexing: 218 | 219 | >>> x = np.array([[1, 2], [3, 4], [5, 6]]) 220 | >>> x[[0, 1, 2], [0, 1, 0]] 221 | array([1, 4, 5]) 222 | 223 | Combining advanced and basic indexing 224 | """"""""""""""""""""""""""""""""""""" 225 | 226 | When there is at least one slice (``:``), ellipsis (``...``) or :const:`newaxis` 227 | in the index (or the array has more dimensions than there are advanced indexes), 228 | then the behaviour can be more complicated. It is like concatenating the 229 | indexing result for each advanced index element 230 | 231 | In the simplest case, there is only a *single* advanced index. A single 232 | advanced index can for example replace a slice and the result array will be 233 | the same, however, it is a copy and may have a different memory layout. 234 | A slice is preferable when it is possible. 235 | 236 | .. admonition:: Example 237 | 238 | >>> x[1:2, 1:3] 239 | array([[4, 5]]) 240 | >>> x[1:2, [1, 2]] 241 | array([[4, 5]]) 242 | 243 | The easiest way to understand the situation may be to think in 244 | terms of the result shape. There are two parts to the indexing operation, 245 | the subspace defined by the basic indexing (excluding integers) and the 246 | subspace from the advanced indexing part. Two cases of index combination 247 | need to be distinguished: 248 | 249 | * The advanced indexes are separated by a slice, :const:`Ellipsis` or :const:`newaxis`. 250 | For example ``x[arr1, :, arr2]``. 251 | * The advanced indexes are all next to each other. 252 | For example ``x[..., arr1, arr2, :]`` but *not* ``x[arr1, :, 1]`` 253 | since ``1`` is an advanced index in this regard. 254 | 255 | In the first case, the dimensions resulting from the advanced indexing 256 | operation come first in the result array, and the subspace dimensions after 257 | that. 258 | In the second case, the dimensions from the advanced indexing operations 259 | are inserted into the result array at the same spot as they were in the 260 | initial array (the latter logic is what makes simple advanced indexing 261 | behave just like slicing). 262 | 263 | .. admonition:: Example 264 | 265 | Suppose ``x.shape`` is (10,20,30) and ``ind`` is a (2,3,4)-shaped 266 | indexing :class:`intp` array, then ``result = x[...,ind,:]`` has 267 | shape (10,2,3,4,30) because the (20,)-shaped subspace has been 268 | replaced with a (2,3,4)-shaped broadcasted indexing subspace. If 269 | we let *i, j, k* loop over the (2,3,4)-shaped subspace then 270 | ``result[...,i,j,k,:] = x[...,ind[i,j,k],:]``. This example 271 | produces the same result as :meth:`x.take(ind, axis=-2) `. 272 | 273 | .. admonition:: Example 274 | 275 | Let ``x.shape`` be (10,20,30,40,50) and suppose ``ind_1`` 276 | and ``ind_2`` can be broadcast to the shape (2,3,4). Then 277 | ``x[:,ind_1,ind_2]`` has shape (10,2,3,4,40,50) because the 278 | (20,30)-shaped subspace from X has been replaced with the 279 | (2,3,4) subspace from the indices. However, 280 | ``x[:,ind_1,:,ind_2]`` has shape (2,3,4,10,30,50) because there 281 | is no unambiguous place to drop in the indexing subspace, thus 282 | it is tacked-on to the beginning. It is always possible to use 283 | :meth:`.transpose() ` to move the subspace 284 | anywhere desired. Note that this example cannot be replicated 285 | using :func:`take`. 286 | 287 | 288 | Boolean array indexing 289 | ^^^^^^^^^^^^^^^^^^^^^^ 290 | 291 | This advanced indexing occurs when obj is an array object of Boolean 292 | type, such as may be returned from comparison operators. A single 293 | boolean index array is practically identical to ``x[obj.nonzero()]`` where, 294 | as described above, :meth:`obj.nonzero() ` returns a 295 | tuple (of length :attr:`obj.ndim `) of integer index 296 | arrays showing the :const:`True` elements of *obj*. However, it is 297 | faster when ``obj.shape == x.shape``. 298 | 299 | If ``obj.ndim == x.ndim``, ``x[obj]`` returns a 1-dimensional array 300 | filled with the elements of *x* corresponding to the :const:`True` 301 | values of *obj*. The search order will be :term:`row-major`, 302 | C-style. If *obj* has :const:`True` values at entries that are outside 303 | of the bounds of *x*, then an index error will be raised. If *obj* is 304 | smaller than *x* it is identical to filling it with :const:`False`. 305 | 306 | .. note:: 307 | 308 | Boolean indexing currently only supports a single boolean ndarray as a index. 309 | An composite index including a boolean array is not supported for now. 310 | 311 | If there is only one Boolean array and no integer indexing array present, 312 | this is straight forward. Care must only be taken to make sure that the 313 | boolean index has *exactly* as many dimensions as it is supposed to work 314 | with. 315 | 316 | .. admonition:: Example 317 | 318 | From an array, select all rows which sum up to less or equal two: 319 | 320 | >>> x = np.array([[0, 1], [1, 1], [2, 2]], dtype=np.int32) 321 | >>> rowsum = x.sum(-1) 322 | >>> x[rowsum <= 2] 323 | array([[0, 1], 324 | [1, 1]], dtype=int32) 325 | 326 | But if ``rowsum`` would have two dimensions as well: 327 | 328 | >>> rowsum = x.sum(-1, keepdims=True) 329 | >>> rowsum.shape 330 | (3, 1) 331 | >>> x[rowsum <= 2] # fail 332 | IndexError: boolean index did not match indexed array along dimension 1 333 | 334 | Detailed notes 335 | -------------- 336 | 337 | These are some detailed notes, which are not of importance for day to day 338 | indexing (in no particular order): 339 | 340 | * For advanced assignments, there is in general no guarantee for the 341 | iteration order. This means that if an element is set more than once, 342 | it is not possible to predict the final result. 343 | * An empty (tuple) index is a full scalar index into a zero dimensional array. 344 | ``x[()]`` returns a *scalar* `ndarray` if ``x`` has zero dimensions. 345 | On the other hand ``x[...]`` always returns a view. 346 | * If a zero dimensional array is present in the index *and* it is *not considered as* a full 347 | integer index as in NumPy. Advanced indexing is not triggered. 348 | * the ``nonzero`` equivalence for Boolean arrays does not hold for zero 349 | dimensional boolean arrays. 350 | * When the result of an advanced indexing operation has no elements but an 351 | individual index is out of bounds, currently no ``IndexError`` is 352 | raised as in NumPy. 353 | 354 | .. index:: 355 | single: indexing 356 | single: ndarray 357 | -------------------------------------------------------------------------------- /api/deepnumpy/arrays.ndarray.rst: -------------------------------------------------------------------------------- 1 | .. _arrays.ndarray: 2 | 3 | ****************************************** 4 | The N-dimensional array (:class:`ndarray`) 5 | ****************************************** 6 | 7 | .. currentmodule:: mxnet.np 8 | 9 | An :class:`ndarray` is a (usually fixed-size) multidimensional 10 | container of items of the same type and size. The number of dimensions 11 | and items in an array is defined by its :attr:`shape `, 12 | which is a :class:`tuple` of *N* non-negative integers that specify the 13 | sizes of each dimension. The type of items in the array is specified by 14 | a separate :ref:`data-type object (dtype) `, one of which 15 | is associated with each ndarray. 16 | 17 | As with other container objects in Python, the contents of an 18 | :class:`ndarray` can be accessed and modified by :ref:`indexing or 19 | slicing ` the array (using, for example, *N* integers), 20 | and via the methods and attributes of the :class:`ndarray`. 21 | 22 | .. index:: view, base 23 | 24 | Different :class:`ndarrays ` can share the same data, so that 25 | changes made in one :class:`ndarray` may be visible in another. That 26 | is, an ndarray can be a *"view"* to another ndarray, and the data it 27 | is referring to is taken care of by the *"base"* ndarray. 28 | 29 | 30 | .. admonition:: Example 31 | 32 | A 2-dimensional array of size 2 x 3, composed of 4-byte integer 33 | elements: 34 | 35 | >>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32) 36 | >>> type(x) 37 | 38 | >>> x.shape 39 | (2, 3) 40 | >>> x.dtype 41 | dtype('int32') 42 | 43 | The array can be indexed using Python container-like syntax: 44 | 45 | >>> # The element of x in the *second* row, *third* column, namely, 6. 46 | >>> x[1, 2] 47 | array(6, dtype=int32) # this is different than the official NumPy which returns a np.int32 object 48 | 49 | For example :ref:`slicing ` can produce views of 50 | the array if the elements to be sliced is continguous in memory: 51 | 52 | >>> y = x[1,:] 53 | >>> y 54 | array([9, 5, 6], dtype=int32) # this also changes the corresponding element in x 55 | >>> x 56 | array([[1, 2, 3], 57 | [9, 5, 6]], dtype=int32) 58 | 59 | 60 | Constructing arrays 61 | =================== 62 | 63 | New arrays can be constructed using the routines detailed in 64 | :ref:`routines.array-creation`, and also by using the low-level 65 | :class:`ndarray` constructor: 66 | 67 | .. autosummary:: 68 | :toctree: generated/ 69 | 70 | ndarray 71 | 72 | :: 73 | 74 | 75 | Indexing arrays 76 | =============== 77 | 78 | Arrays can be indexed using an extended Python slicing syntax, 79 | ``array[selection]``. Similar syntax is also used for accessing 80 | fields in a :term:`structured data type`. 81 | 82 | .. seealso:: :ref:`Array Indexing `. 83 | 84 | .. _memory-layout: 85 | 86 | Internal memory layout of an ndarray 87 | ==================================== 88 | 89 | An instance of class :class:`ndarray` consists of a contiguous 90 | one-dimensional segment of computer memory (owned by the array, or by 91 | some other object), combined with an indexing scheme that maps *N* 92 | integers into the location of an item in the block. The ranges in 93 | which the indices can vary is specified by the :obj:`shape 94 | ` of the array. How many bytes each item takes and how 95 | the bytes are interpreted is defined by the :ref:`data-type object 96 | ` associated with the array. 97 | 98 | .. index:: C-order, Fortran-order, row-major, column-major, stride, 99 | offset 100 | 101 | .. note:: 102 | 103 | `mxnet.numpy.ndarray` currently only supports storing elements in 104 | C-order/row-major and contiguous memory space. The following content 105 | on explaining a variety of memory layouts of an ndarray 106 | are copied from the official NumPy documentation as a comprehensive reference. 107 | 108 | A segment of memory is inherently 1-dimensional, and there are many 109 | different schemes for arranging the items of an *N*-dimensional array 110 | in a 1-dimensional block. NumPy is flexible, and :class:`ndarray` 111 | objects can accommodate any *strided indexing scheme*. In a strided 112 | scheme, the N-dimensional index :math:`(n_0, n_1, ..., n_{N-1})` 113 | corresponds to the offset (in bytes): 114 | 115 | .. math:: n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k 116 | 117 | from the beginning of the memory block associated with the 118 | array. Here, :math:`s_k` are integers which specify the :obj:`strides 119 | ` of the array. The :term:`column-major` order (used, 120 | for example, in the Fortran language and in *Matlab*) and 121 | :term:`row-major` order (used in C) schemes are just specific kinds of 122 | strided scheme, and correspond to memory that can be *addressed* by the strides: 123 | 124 | .. math:: 125 | 126 | s_k^{\mathrm{column}} = \mathrm{itemsize} \prod_{j=0}^{k-1} d_j , 127 | \quad s_k^{\mathrm{row}} = \mathrm{itemsize} \prod_{j=k+1}^{N-1} d_j . 128 | 129 | .. index:: single-segment, contiguous, non-contiguous 130 | 131 | where :math:`d_j` `= self.shape[j]`. 132 | 133 | Both the C and Fortran orders are :term:`contiguous`, *i.e.,* 134 | single-segment, memory layouts, in which every part of the 135 | memory block can be accessed by some combination of the indices. 136 | 137 | While a C-style and Fortran-style contiguous array, which has the corresponding 138 | flags set, can be addressed with the above strides, the actual strides may be 139 | different. This can happen in two cases: 140 | 141 | 1. If ``self.shape[k] == 1`` then for any legal index ``index[k] == 0``. 142 | This means that in the formula for the offset :math:`n_k = 0` and thus 143 | :math:`s_k n_k = 0` and the value of :math:`s_k` `= self.strides[k]` is 144 | arbitrary. 145 | 2. If an array has no elements (``self.size == 0``) there is no legal 146 | index and the strides are never used. Any array with no elements may be 147 | considered C-style and Fortran-style contiguous. 148 | 149 | Point 1. means that ``self`` and ``self.squeeze()`` always have the same 150 | contiguity and ``aligned`` flags value. This also means 151 | that even a high dimensional array could be C-style and Fortran-style 152 | contiguous at the same time. 153 | 154 | .. index:: aligned 155 | 156 | An array is considered aligned if the memory offsets for all elements and the 157 | base offset itself is a multiple of `self.itemsize`. Understanding 158 | `memory-alignment` leads to better performance on most hardware. 159 | 160 | .. note:: 161 | 162 | Points (1) and (2) are not yet applied by default. Beginning with 163 | NumPy 1.8.0, they are applied consistently only if the environment 164 | variable ``NPY_RELAXED_STRIDES_CHECKING=1`` was defined when NumPy 165 | was built. Eventually this will become the default. 166 | 167 | You can check whether this option was enabled when your NumPy was 168 | built by looking at the value of ``np.ones((10,1), 169 | order='C').flags.f_contiguous``. If this is ``True``, then your 170 | NumPy has relaxed strides checking enabled. 171 | 172 | .. warning:: 173 | 174 | It does *not* generally hold that ``self.strides[-1] == self.itemsize`` 175 | for C-style contiguous arrays or ``self.strides[0] == self.itemsize`` for 176 | Fortran-style contiguous arrays is true. 177 | 178 | Data in new :class:`ndarrays ` is in the :term:`row-major` 179 | (C) order, unless otherwise specified, but, for example, :ref:`basic 180 | array slicing ` often produces :term:`views ` 181 | in a different scheme. 182 | 183 | .. seealso: :ref:`Indexing `_ 184 | 185 | .. note:: 186 | 187 | Several algorithms in NumPy work on arbitrarily strided arrays. 188 | However, some algorithms require single-segment arrays. When an 189 | irregularly strided array is passed in to such algorithms, a copy 190 | is automatically made. 191 | 192 | .. _arrays.ndarray.attributes: 193 | 194 | Array attributes 195 | ================ 196 | 197 | Array attributes reflect information that is intrinsic to the array 198 | itself. Generally, accessing an array through its attributes allows 199 | you to get and sometimes set intrinsic properties of the array without 200 | creating a new array. The exposed attributes are the core parts of an 201 | array and only some of them can be reset meaningfully without creating 202 | a new array. Information on each attribute is given below. 203 | 204 | Memory layout 205 | ------------- 206 | 207 | The following attributes contain information about the memory layout 208 | of the array: 209 | 210 | .. autosummary:: 211 | :toctree: generated/ 212 | 213 | ndarray.shape 214 | ndarray.ndim 215 | ndarray.size 216 | 217 | :: 218 | 219 | ndarray.flags 220 | ndarray.strides 221 | ndarray.data 222 | ndarray.itemsize 223 | ndarray.nbytes 224 | ndarray.base 225 | 226 | Data type 227 | --------- 228 | 229 | .. seealso:: :ref:`Data type objects ` 230 | 231 | The data type object associated with the array can be found in the 232 | :attr:`dtype ` attribute: 233 | 234 | .. autosummary:: 235 | :toctree: generated/ 236 | 237 | ndarray.dtype 238 | 239 | Other attributes 240 | ---------------- 241 | 242 | .. autosummary:: 243 | :toctree: generated/ 244 | 245 | ndarray.T 246 | 247 | :: 248 | 249 | ndarray.real 250 | ndarray.imag 251 | ndarray.flat 252 | ndarray.ctypes 253 | 254 | .. _array.ndarray.methods: 255 | 256 | Array methods 257 | ============= 258 | 259 | An :class:`ndarray` object has many methods which operate on or with 260 | the array in some fashion, typically returning an array result. These 261 | methods are briefly explained below. (Each method's docstring has a 262 | more complete description.) 263 | 264 | For the following methods there are also corresponding functions in 265 | :mod:`numpy`: :func:`all`, :func:`any`, :func:`argmax`, 266 | :func:`argmin`, :func:`argpartition`, :func:`argsort`, :func:`choose`, 267 | :func:`clip`, :func:`compress`, :func:`copy`, :func:`cumprod`, 268 | :func:`cumsum`, :func:`diagonal`, :func:`imag`, :func:`max `, 269 | :func:`mean`, :func:`min `, :func:`nonzero`, :func:`partition`, 270 | :func:`prod`, :func:`ptp`, :func:`put`, :func:`ravel`, :func:`real`, 271 | :func:`repeat`, :func:`reshape`, :func:`round `, 272 | :func:`searchsorted`, :func:`sort`, :func:`squeeze`, :func:`std`, 273 | :func:`sum`, :func:`swapaxes`, :func:`take`, :func:`trace`, 274 | :func:`transpose`, :func:`var`. 275 | 276 | Array conversion 277 | ---------------- 278 | 279 | .. autosummary:: 280 | :toctree: generated/ 281 | 282 | ndarray.item 283 | ndarray.copy 284 | ndarray.tolist 285 | ndarray.astype 286 | 287 | :: 288 | 289 | ndarray.itemset 290 | ndarray.tostring 291 | ndarray.tobytes 292 | ndarray.tofile 293 | ndarray.dump 294 | ndarray.dumps 295 | ndarray.byteswap 296 | ndarray.view 297 | ndarray.getfield 298 | ndarray.setflags 299 | ndarray.fill 300 | 301 | Shape manipulation 302 | ------------------ 303 | 304 | For reshape, resize, and transpose, the single tuple argument may be 305 | replaced with ``n`` integers which will be interpreted as an n-tuple. 306 | 307 | .. autosummary:: 308 | :toctree: generated/ 309 | 310 | ndarray.reshape 311 | ndarray.transpose 312 | ndarray.swapaxes 313 | ndarray.flatten 314 | ndarray.squeeze 315 | 316 | :: 317 | 318 | ndarray.resize 319 | ndarray.ravel 320 | 321 | Item selection and manipulation 322 | ------------------------------- 323 | 324 | For array methods that take an *axis* keyword, it defaults to 325 | :const:`None`. If axis is *None*, then the array is treated as a 1-D 326 | array. Any other value for *axis* represents the dimension along which 327 | the operation should proceed. 328 | 329 | .. autosummary:: 330 | :toctree: generated/ 331 | 332 | ndarray.nonzero 333 | ndarray.take 334 | ndarray.repeat 335 | 336 | 337 | :: 338 | 339 | ndarray.argsort 340 | ndarray.sort 341 | ndarray.put 342 | ndarray.choose 343 | ndarray.partition 344 | ndarray.argpartition 345 | ndarray.searchsorted 346 | ndarray.compress 347 | ndarray.diagonal 348 | 349 | Calculation 350 | ----------- 351 | 352 | .. index:: axis 353 | 354 | Many of these methods take an argument named *axis*. In such cases, 355 | 356 | - If *axis* is *None* (the default), the array is treated as a 1-D 357 | array and the operation is performed over the entire array. This 358 | behavior is also the default if self is a 0-dimensional array or 359 | array scalar. (An array scalar is an instance of the types/classes 360 | float32, float64, etc., whereas a 0-dimensional array is an ndarray 361 | instance containing precisely one array scalar.) 362 | 363 | - If *axis* is an integer, then the operation is done over the given 364 | axis (for each 1-D subarray that can be created along the given axis). 365 | 366 | .. admonition:: Example of the *axis* argument 367 | 368 | A 3-dimensional array of size 3 x 3 x 3, summed over each of its 369 | three axes 370 | 371 | >>> x 372 | array([[[ 0, 1, 2], 373 | [ 3, 4, 5], 374 | [ 6, 7, 8]], 375 | [[ 9, 10, 11], 376 | [12, 13, 14], 377 | [15, 16, 17]], 378 | [[18, 19, 20], 379 | [21, 22, 23], 380 | [24, 25, 26]]]) 381 | >>> x.sum(axis=0) 382 | array([[27, 30, 33], 383 | [36, 39, 42], 384 | [45, 48, 51]]) 385 | >>> # for sum, axis is the first keyword, so we may omit it, 386 | >>> # specifying only its value 387 | >>> x.sum(0), x.sum(1), x.sum(2) 388 | (array([[27, 30, 33], 389 | [36, 39, 42], 390 | [45, 48, 51]]), 391 | array([[ 9, 12, 15], 392 | [36, 39, 42], 393 | [63, 66, 69]]), 394 | array([[ 3, 12, 21], 395 | [30, 39, 48], 396 | [57, 66, 75]])) 397 | 398 | The parameter *dtype* specifies the data type over which a reduction 399 | operation (like summing) should take place. The default reduce data 400 | type is the same as the data type of *self*. To avoid overflow, it can 401 | be useful to perform the reduction using a larger data type. 402 | 403 | For several methods, an optional *out* argument can also be provided 404 | and the result will be placed into the output array given. The *out* 405 | argument must be an :class:`ndarray` and have the same number of 406 | elements. It can have a different data type in which case casting will 407 | be performed. 408 | 409 | .. autosummary:: 410 | :toctree: generated/ 411 | 412 | ndarray.max 413 | ndarray.argmax 414 | ndarray.min 415 | ndarray.argmin 416 | ndarray.clip 417 | ndarray.sum 418 | ndarray.mean 419 | ndarray.prod 420 | ndarray.cumsum 421 | ndarray.var 422 | ndarray.std 423 | 424 | :: 425 | 426 | ndarray.round 427 | ndarray.ptp 428 | ndarray.conj 429 | ndarray.trace 430 | ndarray.cumprod 431 | ndarray.all 432 | ndarray.any 433 | 434 | Arithmetic, matrix multiplication, and comparison operations 435 | ============================================================ 436 | 437 | .. index:: comparison, arithmetic, matrix, operation, operator 438 | 439 | Arithmetic and comparison operations on :class:`ndarrays ` 440 | are defined as element-wise operations, and generally yield 441 | :class:`ndarray` objects as results. 442 | 443 | Each of the arithmetic operations (``+``, ``-``, ``*``, ``/``, ``//``, 444 | ``%``, ``divmod()``, ``**`` or ``pow()``, ``<<``, ``>>``, ``&``, 445 | ``^``, ``|``, ``~``) and the comparisons (``==``, ``<``, ``>``, 446 | ``<=``, ``>=``, ``!=``) is equivalent to the corresponding 447 | universal function (or :term:`ufunc` for short) in NumPy. For 448 | more information, see the section on :ref:`Universal Functions 449 | `. 450 | 451 | Comparison operators: 452 | 453 | .. autosummary:: 454 | :toctree: generated/ 455 | 456 | ndarray.__lt__ 457 | ndarray.__le__ 458 | ndarray.__gt__ 459 | ndarray.__ge__ 460 | ndarray.__eq__ 461 | ndarray.__ne__ 462 | 463 | Truth value of an array (:func:`bool()`): 464 | 465 | .. autosummary:: 466 | :toctree: generated/ 467 | 468 | ndarray.__bool__ 469 | 470 | .. note:: 471 | 472 | Truth-value testing of an array invokes 473 | :meth:`ndarray.__bool__`, which raises an error if the number of 474 | elements in the array is larger than 1, because the truth value 475 | of such arrays is ambiguous. 476 | 477 | 478 | Unary operations: 479 | 480 | .. autosummary:: 481 | :toctree: generated/ 482 | 483 | ndarray.__neg__ 484 | 485 | :: 486 | 487 | ndarray.__pos__ 488 | ndarray.__abs__ 489 | ndarray.__invert__ 490 | 491 | Arithmetic: 492 | 493 | .. autosummary:: 494 | :toctree: generated/ 495 | 496 | ndarray.__add__ 497 | ndarray.__sub__ 498 | ndarray.__mul__ 499 | ndarray.__truediv__ 500 | ndarray.__mod__ 501 | ndarray.__pow__ 502 | 503 | :: 504 | 505 | ndarray.__floordiv__ 506 | ndarray.__divmod__ 507 | ndarray.__lshift__ 508 | ndarray.__rshift__ 509 | ndarray.__and__ 510 | ndarray.__or__ 511 | ndarray.__xor__ 512 | 513 | .. note:: 514 | 515 | - Any third argument to :func:`pow()` is silently ignored, 516 | as the underlying :func:`ufunc ` takes only two arguments. 517 | 518 | - The three division operators are all defined; :obj:`div` is active 519 | by default, :obj:`truediv` is active when 520 | :obj:`__future__` division is in effect. 521 | 522 | - Because :class:`ndarray` is a built-in type (written in C), the 523 | ``__r{op}__`` special methods are not directly defined. 524 | 525 | - The functions called to implement many arithmetic special methods 526 | for arrays can be modified using :class:`__array_ufunc__ `. 527 | 528 | Arithmetic, in-place: 529 | 530 | .. autosummary:: 531 | :toctree: generated/ 532 | 533 | ndarray.__iadd__ 534 | ndarray.__isub__ 535 | ndarray.__imul__ 536 | ndarray.__itruediv__ 537 | ndarray.__imod__ 538 | 539 | :: 540 | 541 | ndarray.__ifloordiv__ 542 | ndarray.__ipow__ 543 | ndarray.__ilshift__ 544 | ndarray.__irshift__ 545 | ndarray.__iand__ 546 | ndarray.__ior__ 547 | ndarray.__ixor__ 548 | 549 | .. warning:: 550 | 551 | In place operations will perform the calculation using the 552 | precision decided by the data type of the two operands, but will 553 | silently downcast the result (if necessary) so it can fit back into 554 | the array. Therefore, for mixed precision calculations, ``A {op}= 555 | B`` can be different than ``A = A {op} B``. For example, suppose 556 | ``a = ones((3,3))``. Then, ``a += 3j`` is different than ``a = a + 557 | 3j``: while they both perform the same computation, ``a += 3`` 558 | casts the result to fit back in ``a``, whereas ``a = a + 3j`` 559 | re-binds the name ``a`` to the result. 560 | 561 | Matrix Multiplication: 562 | 563 | .. autosummary:: 564 | :toctree: generated/ 565 | 566 | :: 567 | 568 | ndarray.__matmul__ 569 | 570 | 571 | Special methods 572 | =============== 573 | 574 | For standard library functions: 575 | 576 | .. autosummary:: 577 | :toctree: generated/ 578 | 579 | ndarray.__reduce__ 580 | ndarray.__setstate__ 581 | 582 | :: 583 | 584 | ndarray.__copy__ 585 | ndarray.__deepcopy__ 586 | 587 | Basic customization: 588 | 589 | .. autosummary:: 590 | :toctree: generated/ 591 | 592 | :: 593 | 594 | ndarray.__array__ 595 | ndarray.__new__ 596 | ndarray.__array_wrap__ 597 | 598 | Container customization: (see :ref:`Indexing `) 599 | 600 | .. autosummary:: 601 | :toctree: generated/ 602 | 603 | ndarray.__len__ 604 | ndarray.__getitem__ 605 | ndarray.__setitem__ 606 | 607 | :: 608 | 609 | ndarray.__contains__ 610 | 611 | Conversion; the operations :func:`int()` and :func:`float()`. 612 | They work only on arrays that have one element in them 613 | and return the appropriate scalar. 614 | 615 | .. autosummary:: 616 | :toctree: generated/ 617 | 618 | ndarray.__int__ 619 | ndarray.__float__ 620 | 621 | :: 622 | 623 | ndarray.__complex__ 624 | 625 | String representations: 626 | 627 | .. autosummary:: 628 | :toctree: generated/ 629 | 630 | ndarray.__str__ 631 | ndarray.__repr__ 632 | -------------------------------------------------------------------------------- /api/deepnumpy/arrays.rst: -------------------------------------------------------------------------------- 1 | .. _arrays: 2 | 3 | ************* 4 | Array objects 5 | ************* 6 | 7 | .. currentmodule:: mxnet.np 8 | 9 | ``np`` provides an N-dimensional array type, the :ref:`ndarray 10 | `, which describes a collection of "items" of the same 11 | type. The items can be :ref:`indexed ` using for 12 | example N integers. 13 | 14 | All ndarrays are :term:`homogenous`: every item takes up the same size 15 | block of memory, and all blocks are interpreted in exactly the same 16 | way. How each item in the array is to be interpreted is specified by a 17 | separate :ref:`data-type object `, one of which is associated 18 | with every array. In addition to basic types (integers, floats, 19 | *etc.*), the data type objects can also represent data structures. 20 | 21 | An item extracted from an array, *e.g.*, by indexing, is represented 22 | by a Python object whose type is one of the :ref:`array scalar types 23 | ` built in NumPy. The array scalars allow easy manipulation 24 | of also more complicated arrangements of data. 25 | 26 | .. note:: 27 | 28 | A major difference to ``numpy.ndarray`` is that ``mxnet.np.ndarray``'s scalar 29 | is a 0-dim ndarray instead of a scalar object (``numpy.generic``). 30 | 31 | .. toctree:: 32 | :maxdepth: 2 33 | 34 | arrays.ndarray 35 | arrays.scalars 36 | arrays.dtypes 37 | arrays.indexing 38 | arrays.nditer 39 | arrays.classes 40 | maskedarray 41 | arrays.interface 42 | arrays.datetime 43 | -------------------------------------------------------------------------------- /api/deepnumpy/index.rst: -------------------------------------------------------------------------------- 1 | .. _reference: 2 | 3 | NP on MXNet reference 4 | ============================ 5 | 6 | 7 | .. module:: mxnet.np 8 | 9 | This section contains the `mxnet.np` API reference documentation. The topics here explain the functions, modules, and objects 10 | included in `mxnet.np`. Use the links here to learn more. 11 | 12 | 13 | .. toctree:: 14 | :maxdepth: 2 15 | 16 | arrays 17 | constants 18 | ufuncs 19 | routines 20 | distutils 21 | distutils_guide 22 | c-api 23 | internals 24 | swig 25 | npx 26 | 27 | 28 | **Acknowledgements** 29 | 30 | Large parts of this manual originate from NumPy documents. 31 | -------------------------------------------------------------------------------- /api/deepnumpy/npx.rst: -------------------------------------------------------------------------------- 1 | NP Extensions 2 | ==================== 3 | 4 | .. currentmodule:: mxnet.npx 5 | 6 | Compatibility 7 | ------------- 8 | 9 | .. autosummary:: 10 | :toctree: generated/ 11 | 12 | set_np 13 | reset_np 14 | 15 | .. code:: 16 | 17 | is_np_array 18 | use_np_array 19 | is_np_shape 20 | use_np_shape 21 | np_array 22 | np_shape 23 | 24 | 25 | Devices 26 | --------- 27 | 28 | 29 | .. autosummary:: 30 | :toctree: generated/ 31 | 32 | cpu 33 | cpu_pinned 34 | gpu 35 | gpu_memory_info 36 | current_context 37 | num_gpus 38 | 39 | Nerual networks 40 | ----------------------- 41 | 42 | .. autosummary:: 43 | :toctree: generated/ 44 | 45 | activation 46 | batch_norm 47 | convolution 48 | dropout 49 | embedding 50 | fully_connected 51 | layer_norm 52 | pooling 53 | rnn 54 | leaky_relu 55 | multibox_detection 56 | multibox_prior 57 | multibox_target 58 | roi_pooling 59 | 60 | 61 | More operators 62 | ------------------ 63 | 64 | .. autosummary:: 65 | :toctree: generated/ 66 | 67 | sigmoid 68 | smooth_l1 69 | softmax 70 | threading 71 | topk 72 | waitall 73 | load 74 | save 75 | one_hot 76 | pick 77 | reshape_like 78 | batch_flatten 79 | batch_dot 80 | gamma 81 | sequence_mask 82 | 83 | .. code:: 84 | 85 | seed -------------------------------------------------------------------------------- /api/deepnumpy/random/index.rst: -------------------------------------------------------------------------------- 1 | .. _numpyrandom: 2 | 3 | .. currentmodule:: mxnet.np.random 4 | 5 | np.random 6 | ============ 7 | 8 | .. 9 | remove a large part about generator here, this page contains a part of generator.rst 10 | 11 | 12 | Accessing the BitGenerator 13 | -------------------------- 14 | .. autosummary:: 15 | :toctree: generated/ 16 | 17 | :: 18 | 19 | bit_generator 20 | 21 | Simple random data 22 | ------------------ 23 | .. autosummary:: 24 | :toctree: generated/ 25 | 26 | choice 27 | 28 | :: 29 | 30 | random 31 | integers 32 | bytes 33 | 34 | Permutations 35 | ------------ 36 | .. autosummary:: 37 | :toctree: generated/ 38 | 39 | shuffle 40 | 41 | :: 42 | 43 | permutation 44 | 45 | Distributions 46 | ------------- 47 | .. autosummary:: 48 | :toctree: generated/ 49 | 50 | 51 | normal 52 | uniform 53 | rand 54 | randint 55 | 56 | :: 57 | 58 | beta 59 | binomial 60 | chisquare 61 | dirichlet 62 | exponential 63 | f 64 | gamma 65 | geometric 66 | gumbel 67 | hypergeometric 68 | laplace 69 | logistic 70 | lognormal 71 | logseries 72 | multinomial 73 | multivariate_normal 74 | negative_binomial 75 | noncentral_chisquare 76 | noncentral_f 77 | pareto 78 | poisson 79 | power 80 | rayleigh 81 | standard_cauchy 82 | standard_exponential 83 | standard_gamma 84 | standard_normal 85 | standard_t 86 | triangular 87 | vonmises 88 | wald 89 | weibull 90 | zipf 91 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.array-creation.rst: -------------------------------------------------------------------------------- 1 | .. _routines.array-creation: 2 | 3 | Array creation routines 4 | ======================= 5 | 6 | .. seealso:: :ref:`Array creation ` 7 | 8 | .. currentmodule:: mxnet.np 9 | 10 | Ones and zeros 11 | -------------- 12 | .. autosummary:: 13 | :toctree: generated/ 14 | 15 | eye 16 | empty 17 | full 18 | identity 19 | ones 20 | ones_like 21 | zeros 22 | zeros_like 23 | 24 | .. code:: 25 | 26 | full_like 27 | empty_like 28 | 29 | From existing data 30 | ------------------ 31 | .. autosummary:: 32 | :toctree: generated/ 33 | 34 | array 35 | copy 36 | 37 | .. code:: 38 | 39 | asarray 40 | asanyarray 41 | ascontiguousarray 42 | asmatrix 43 | frombuffer 44 | fromfile 45 | fromfunction 46 | fromiter 47 | fromstring 48 | loadtxt 49 | 50 | .. _routines.array-creation.rec: 51 | 52 | Creating record arrays (:mod:`np.rec`) 53 | ----------------------------------------- 54 | 55 | .. note:: :mod:`np.rec` is the preferred alias for 56 | :mod:`np.core.records`. 57 | 58 | .. autosummary:: 59 | :toctree: generated/ 60 | 61 | .. code:: 62 | 63 | core.records.array 64 | core.records.fromarrays 65 | core.records.fromrecords 66 | core.records.fromstring 67 | core.records.fromfile 68 | 69 | .. _routines.array-creation.char: 70 | 71 | Creating character arrays (:mod:`np.char`) 72 | --------------------------------------------- 73 | 74 | .. note:: :mod:`np.char` is the preferred alias for 75 | :mod:`np.core.defchararray`. 76 | 77 | .. autosummary:: 78 | :toctree: generated/ 79 | 80 | .. code:: 81 | 82 | core.defchararray.array 83 | core.defchararray.asarray 84 | 85 | Numerical ranges 86 | ---------------- 87 | .. autosummary:: 88 | :toctree: generated/ 89 | 90 | arange 91 | linspace 92 | logspace 93 | meshgrid 94 | 95 | .. code:: 96 | 97 | geomspace 98 | mgrid 99 | ogrid 100 | 101 | Building matrices 102 | ----------------- 103 | .. autosummary:: 104 | :toctree: generated/ 105 | 106 | tril 107 | 108 | .. code:: 109 | 110 | diag 111 | diagflat 112 | tri 113 | triu 114 | vander 115 | 116 | The Matrix class 117 | ---------------- 118 | .. autosummary:: 119 | :toctree: generated/ 120 | 121 | :: 122 | 123 | mat 124 | bmat 125 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.array-manipulation.rst: -------------------------------------------------------------------------------- 1 | Array manipulation routines 2 | *************************** 3 | 4 | .. currentmodule:: mxnet.np 5 | 6 | Basic operations 7 | ================ 8 | .. autosummary:: 9 | :toctree: generated/ 10 | 11 | :: 12 | 13 | copyto 14 | 15 | Changing array shape 16 | ==================== 17 | .. autosummary:: 18 | :toctree: generated/ 19 | 20 | 21 | reshape 22 | ravel 23 | ndarray.flatten 24 | 25 | :: 26 | 27 | ndarray.flat 28 | 29 | Transpose-like operations 30 | ========================= 31 | .. autosummary:: 32 | :toctree: generated/ 33 | 34 | swapaxes 35 | ndarray.T 36 | transpose 37 | moveaxis 38 | 39 | :: 40 | 41 | rollaxis 42 | 43 | Changing number of dimensions 44 | ============================= 45 | .. autosummary:: 46 | :toctree: generated/ 47 | 48 | expand_dims 49 | squeeze 50 | broadcast_to 51 | broadcast_arrays 52 | 53 | :: 54 | 55 | atleast_1d 56 | atleast_2d 57 | atleast_3d 58 | broadcast 59 | 60 | Changing kind of array 61 | ====================== 62 | .. autosummary:: 63 | :toctree: generated/ 64 | 65 | :: 66 | 67 | asarray 68 | asanyarray 69 | asmatrix 70 | asfarray 71 | asfortranarray 72 | ascontiguousarray 73 | asarray_chkfinite 74 | asscalar 75 | require 76 | 77 | Joining arrays 78 | ============== 79 | .. autosummary:: 80 | :toctree: generated/ 81 | 82 | concatenate 83 | stack 84 | dstack 85 | vstack 86 | 87 | :: 88 | 89 | column_stack 90 | hstack 91 | block 92 | 93 | Splitting arrays 94 | ================ 95 | .. autosummary:: 96 | :toctree: generated/ 97 | 98 | split 99 | hsplit 100 | vsplit 101 | 102 | :: 103 | 104 | array_split 105 | dsplit 106 | 107 | Tiling arrays 108 | ============= 109 | .. autosummary:: 110 | :toctree: generated/ 111 | 112 | tile 113 | repeat 114 | 115 | Adding and removing elements 116 | ============================ 117 | .. autosummary:: 118 | :toctree: generated/ 119 | 120 | unique 121 | 122 | :: 123 | 124 | delete 125 | insert 126 | append 127 | resize 128 | trim_zeros 129 | 130 | Rearranging elements 131 | ==================== 132 | .. autosummary:: 133 | :toctree: generated/ 134 | 135 | reshape 136 | flip 137 | roll 138 | rot90 139 | 140 | :: 141 | 142 | fliplr 143 | flipud 144 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.io.rst: -------------------------------------------------------------------------------- 1 | Input and output 2 | **************** 3 | 4 | .. currentmodule:: mxnet.np 5 | 6 | NumPy binary files (NPY, NPZ) 7 | ----------------------------- 8 | .. autosummary:: 9 | :toctree: generated/ 10 | 11 | :: 12 | load 13 | save 14 | savez 15 | savez_compressed 16 | 17 | The format of these binary file types is documented in 18 | :py:mod:`numpy.lib.format` 19 | 20 | Text files 21 | ---------- 22 | .. autosummary:: 23 | :toctree: generated/ 24 | 25 | genfromtxt 26 | 27 | :: 28 | 29 | loadtxt 30 | savetxt 31 | fromregex 32 | fromstring 33 | ndarray.tofile 34 | ndarray.tolist 35 | 36 | Raw binary files 37 | ---------------- 38 | 39 | .. autosummary:: 40 | 41 | 42 | :: 43 | 44 | fromfile 45 | ndarray.tofile 46 | 47 | String formatting 48 | ----------------- 49 | .. autosummary:: 50 | :toctree: generated/ 51 | 52 | 53 | :: 54 | 55 | array2string 56 | array_repr 57 | array_str 58 | format_float_positional 59 | format_float_scientific 60 | 61 | Memory mapping files 62 | -------------------- 63 | .. autosummary:: 64 | :toctree: generated/ 65 | 66 | 67 | :: 68 | 69 | memmap 70 | 71 | Text formatting options 72 | ----------------------- 73 | .. autosummary:: 74 | :toctree: generated/ 75 | 76 | 77 | :: 78 | 79 | set_printoptions 80 | get_printoptions 81 | set_string_function 82 | printoptions 83 | 84 | Base-n representations 85 | ---------------------- 86 | .. autosummary:: 87 | :toctree: generated/ 88 | 89 | 90 | :: 91 | 92 | binary_repr 93 | base_repr 94 | 95 | Data sources 96 | ------------ 97 | .. autosummary:: 98 | :toctree: generated/ 99 | 100 | 101 | :: 102 | 103 | DataSource 104 | 105 | Binary Format Description 106 | ------------------------- 107 | .. autosummary:: 108 | :template: autosummary/minimal_module.rst 109 | :toctree: generated/ 110 | 111 | 112 | :: 113 | 114 | lib.format 115 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.linalg.rst: -------------------------------------------------------------------------------- 1 | .. _routines.linalg: 2 | 3 | .. module:: mxnet.np.linalg 4 | 5 | Linear algebra (:mod:`numpy.linalg`) 6 | ************************************ 7 | 8 | The NumPy linear algebra functions rely on BLAS and LAPACK to provide efficient 9 | low level implementations of standard linear algebra algorithms. Those 10 | libraries may be provided by NumPy itself using C versions of a subset of their 11 | reference implementations but, when possible, highly optimized libraries that 12 | take advantage of specialized processor functionality are preferred. Examples 13 | of such libraries are OpenBLAS_, MKL (TM), and ATLAS. Because those libraries 14 | are multithreaded and processor dependent, environmental variables and external 15 | packages such as threadpoolctl_ may be needed to control the number of threads 16 | or specify the processor architecture. 17 | 18 | .. _OpenBLAS: https://www.openblas.net/ 19 | .. _threadpoolctl: https://github.com/joblib/threadpoolctl 20 | 21 | .. currentmodule:: mxnet.np 22 | 23 | Matrix and vector products 24 | -------------------------- 25 | .. autosummary:: 26 | :toctree: generated/ 27 | 28 | dot 29 | vdot 30 | inner 31 | outer 32 | tensordot 33 | einsum 34 | 35 | :: 36 | 37 | linalg.multi_dot 38 | matmul 39 | einsum_path 40 | linalg.matrix_power 41 | kron 42 | 43 | Decompositions 44 | -------------- 45 | .. autosummary:: 46 | :toctree: generated/ 47 | 48 | linalg.svd 49 | 50 | :: 51 | 52 | linalg.cholesky 53 | linalg.qr 54 | 55 | Matrix eigenvalues 56 | ------------------ 57 | .. autosummary:: 58 | :toctree: generated/ 59 | 60 | 61 | :: 62 | 63 | linalg.eig 64 | linalg.eigh 65 | linalg.eigvals 66 | linalg.eigvalsh 67 | 68 | Norms and other numbers 69 | ----------------------- 70 | .. autosummary:: 71 | :toctree: generated/ 72 | 73 | linalg.norm 74 | trace 75 | 76 | :: 77 | 78 | linalg.cond 79 | linalg.det 80 | linalg.matrix_rank 81 | linalg.slogdet 82 | 83 | Solving equations and inverting matrices 84 | ---------------------------------------- 85 | .. autosummary:: 86 | :toctree: generated/ 87 | 88 | 89 | :: 90 | 91 | linalg.solve 92 | linalg.tensorsolve 93 | linalg.lstsq 94 | linalg.inv 95 | linalg.pinv 96 | linalg.tensorinv 97 | 98 | Exceptions 99 | ---------- 100 | .. autosummary:: 101 | :toctree: generated/ 102 | 103 | 104 | :: 105 | 106 | linalg.LinAlgError 107 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.math.rst: -------------------------------------------------------------------------------- 1 | Mathematical functions 2 | ********************** 3 | 4 | .. currentmodule:: mxnet.np 5 | 6 | .. note:: 7 | 8 | Currently, most of the math functions only support inputs and outputs of the same dtype. 9 | This limitation usually results in imprecise outputs for ndarrays with integral dtype 10 | while floating-point values are expected in the output. 11 | Appropriate handling of ndarrays integral dtypes is in active development. 12 | 13 | 14 | Trigonometric functions 15 | ----------------------- 16 | .. autosummary:: 17 | :toctree: generated/ 18 | 19 | sin 20 | cos 21 | tan 22 | arcsin 23 | arccos 24 | arctan 25 | degrees 26 | radians 27 | hypot 28 | arctan2 29 | deg2rad 30 | rad2deg 31 | 32 | :: 33 | 34 | unwrap 35 | 36 | Hyperbolic functions 37 | -------------------- 38 | .. autosummary:: 39 | :toctree: generated/ 40 | 41 | sinh 42 | cosh 43 | tanh 44 | arcsinh 45 | arccosh 46 | arctanh 47 | 48 | Rounding 49 | -------- 50 | .. autosummary:: 51 | :toctree: generated/ 52 | 53 | rint 54 | fix 55 | floor 56 | ceil 57 | trunc 58 | around 59 | 60 | :: 61 | 62 | round_ 63 | 64 | 65 | Sums, products, differences 66 | --------------------------- 67 | .. autosummary:: 68 | :toctree: generated/ 69 | 70 | sum 71 | prod 72 | cumsum 73 | 74 | :: 75 | 76 | nanprod 77 | nansum 78 | cumprod 79 | nancumprod 80 | nancumsum 81 | diff 82 | ediff1d 83 | gradient 84 | cross 85 | trapz 86 | 87 | Exponents and logarithms 88 | ------------------------ 89 | .. autosummary:: 90 | :toctree: generated/ 91 | 92 | exp 93 | expm1 94 | log 95 | log10 96 | log2 97 | log1p 98 | 99 | :: 100 | 101 | exp2 102 | logaddexp 103 | logaddexp2 104 | 105 | Other special functions 106 | ----------------------- 107 | .. autosummary:: 108 | :toctree: generated/ 109 | 110 | 111 | :: 112 | 113 | i0 114 | sinc 115 | 116 | Floating point routines 117 | ----------------------- 118 | .. autosummary:: 119 | :toctree: generated/ 120 | 121 | ldexp 122 | 123 | :: 124 | 125 | signbit 126 | copysign 127 | frexp 128 | nextafter 129 | spacing 130 | 131 | Rational routines 132 | ----------------- 133 | .. autosummary:: 134 | :toctree: generated/ 135 | 136 | lcm 137 | 138 | :: 139 | 140 | gcd 141 | 142 | Arithmetic operations 143 | --------------------- 144 | .. autosummary:: 145 | :toctree: generated/ 146 | 147 | add 148 | reciprocal 149 | negative 150 | divide 151 | power 152 | subtract 153 | mod 154 | multiply 155 | true_divide 156 | remainder 157 | 158 | :: 159 | 160 | positive 161 | floor_divide 162 | float_power 163 | 164 | fmod 165 | modf 166 | divmod 167 | 168 | Handling complex numbers 169 | ------------------------ 170 | .. autosummary:: 171 | :toctree: generated/ 172 | 173 | 174 | :: 175 | 176 | angle 177 | real 178 | imag 179 | conj 180 | conjugate 181 | 182 | 183 | Miscellaneous 184 | ------------- 185 | .. autosummary:: 186 | :toctree: generated/ 187 | 188 | clip 189 | 190 | sqrt 191 | cbrt 192 | square 193 | 194 | absolute 195 | sign 196 | maximum 197 | minimum 198 | 199 | :: 200 | 201 | convolve 202 | 203 | fabs 204 | 205 | heaviside 206 | 207 | fmax 208 | fmin 209 | 210 | nan_to_num 211 | real_if_close 212 | 213 | interp 214 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.rst: -------------------------------------------------------------------------------- 1 | Routines 2 | ============ 3 | 4 | In this chapter routine docstrings are presented, grouped by functionality. 5 | Many docstrings contain example code, which demonstrates basic usage 6 | of the routine. The examples assume that the `np` module is imported with:: 7 | 8 | >>> from mxnet import np, npx 9 | >>> npx.set_np() 10 | 11 | A convenient way to execute examples is the ``%doctest_mode`` mode of 12 | IPython, which allows for pasting of multi-line examples and preserves 13 | indentation. 14 | 15 | .. toctree:: 16 | :maxdepth: 2 17 | 18 | routines.array-creation 19 | routines.array-manipulation 20 | routines.bitwise 21 | routines.char 22 | routines.ctypeslib 23 | routines.datetime 24 | routines.dtype 25 | routines.dual 26 | routines.emath 27 | routines.err 28 | routines.fft 29 | routines.financial 30 | routines.functional 31 | routines.help 32 | routines.indexing 33 | routines.io 34 | routines.linalg 35 | routines.logic 36 | routines.ma 37 | routines.math 38 | routines.matlib 39 | routines.other 40 | routines.padding 41 | routines.polynomials 42 | random/index 43 | routines.set 44 | routines.sort 45 | routines.statistics 46 | routines.testing 47 | routines.window 48 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.sort.rst: -------------------------------------------------------------------------------- 1 | Sorting, searching, and counting 2 | ================================ 3 | 4 | .. currentmodule:: mxnet.np 5 | 6 | Sorting 7 | ------- 8 | .. autosummary:: 9 | :toctree: generated/ 10 | 11 | :: 12 | 13 | ndarray.sort 14 | sort 15 | lexsort 16 | argsort 17 | msort 18 | sort_complex 19 | partition 20 | argpartition 21 | 22 | Searching 23 | --------- 24 | .. autosummary:: 25 | :toctree: generated/ 26 | 27 | argmax 28 | argmin 29 | 30 | :: 31 | 32 | nanargmax 33 | nanargmin 34 | argwhere 35 | nonzero 36 | flatnonzero 37 | where 38 | searchsorted 39 | extract 40 | 41 | Counting 42 | -------- 43 | .. autosummary:: 44 | :toctree: generated/ 45 | 46 | 47 | :: 48 | 49 | count_nonzero 50 | -------------------------------------------------------------------------------- /api/deepnumpy/routines.statistics.rst: -------------------------------------------------------------------------------- 1 | Statistics 2 | ========== 3 | 4 | .. currentmodule:: mxnet.np 5 | 6 | 7 | Order statistics 8 | ---------------- 9 | 10 | .. autosummary:: 11 | :toctree: generated/ 12 | 13 | min 14 | max 15 | 16 | :: 17 | 18 | amin 19 | amax 20 | nanmin 21 | nanmax 22 | ptp 23 | percentile 24 | nanpercentile 25 | quantile 26 | nanquantile 27 | 28 | Averages and variances 29 | ---------------------- 30 | 31 | .. autosummary:: 32 | :toctree: generated/ 33 | 34 | mean 35 | std 36 | var 37 | 38 | :: 39 | 40 | median 41 | average 42 | nanmedian 43 | nanmean 44 | nanstd 45 | nanvar 46 | 47 | Correlating 48 | ----------- 49 | 50 | .. autosummary:: 51 | :toctree: generated/ 52 | 53 | 54 | :: 55 | 56 | corrcoef 57 | correlate 58 | cov 59 | 60 | Histograms 61 | ---------- 62 | 63 | .. autosummary:: 64 | :toctree: generated/ 65 | 66 | histogram 67 | 68 | :: 69 | 70 | histogram2d 71 | histogramdd 72 | bincount 73 | histogram_bin_edges 74 | digitize 75 | -------------------------------------------------------------------------------- /api/gluon/block.rst: -------------------------------------------------------------------------------- 1 | Block objects 2 | ================== 3 | 4 | .. currentmodule:: mxnet.gluon 5 | 6 | A neural network is often constructed block by block. A block could be a single 7 | function, e.g. sigmoid, a layer with parameters, e.g. a dense layer, or a 8 | combination of multiple layers and functions. The `Block` object in the Gluon 9 | package is the base object for such a block. 10 | 11 | 12 | .. admonition:: Example 13 | 14 | Define a model that has a dense layer and return the summed results: 15 | 16 | >>> from mxnet import np, npx, gluon 17 | >>> npx.set_np() 18 | >>> class MyModel(gluon.Block): 19 | ... def __init__(self, **kwargs): 20 | ... super(MyModel, self).__init__(**kwargs) 21 | ... self.dense = gluon.nn.Dense(10) 22 | ... def forward(self, x): 23 | ... return self.dense(x).sum() 24 | 25 | Initialize this model: 26 | 27 | >>> model = MyModel() 28 | >>> model.initialize() 29 | 30 | Feed in a random input to print the forward output: 31 | 32 | >>> x = np.random.uniform(size=(10,2)) 33 | >>> print(model(x)) 34 | -0.5192252 35 | 36 | .. autosummary:: 37 | :toctree: generated/ 38 | 39 | Block 40 | 41 | .. note:: 42 | 43 | ``Block`` can be accessed by either ``mxnet.gluon.Block`` and 44 | ``mxnet.gluon.nn.Block``. Similar for ``HybridBlock`` and ``SymbolBlock``. 45 | 46 | 47 | Running computations 48 | -------------------------- 49 | 50 | .. autosummary:: 51 | :toctree: generated/ 52 | 53 | Block.forward 54 | Block.__call__ 55 | 56 | Handling parameters 57 | ------------------------- 58 | 59 | .. autosummary:: 60 | :toctree: generated/ 61 | 62 | 63 | Block.initialize 64 | Block.save_parameters 65 | Block.load_parameters 66 | Block.collect_params 67 | Block.cast 68 | Block.apply 69 | 70 | 71 | Summarization 72 | ------------------ 73 | 74 | .. autosummary:: 75 | :toctree: generated/ 76 | 77 | Block.summary 78 | 79 | Advanced APIs for customization 80 | ---------------------------------------- 81 | 82 | 83 | .. autosummary:: 84 | :toctree: generated/ 85 | 86 | Block.name_scope 87 | Block.register_child 88 | Block.register_forward_hook 89 | Block.register_forward_pre_hook 90 | 91 | Attributes 92 | ------------------ 93 | 94 | .. autosummary:: 95 | :toctree: generated/ 96 | 97 | Block.name 98 | Block.params 99 | Block.prefix 100 | 101 | 102 | .. warning:: 103 | 104 | The following two APIs are deprecated since `v1.2.1 105 | `_. 106 | 107 | .. autosummary:: 108 | :toctree: generated/ 109 | 110 | Block.save_params 111 | Block.load_params 112 | 113 | Hybridizable block 114 | ----------------------- 115 | 116 | .. autosummary:: 117 | :toctree: generated/ 118 | 119 | HybridBlock 120 | 121 | ``HybridBlock`` is a subclass of ``Block`` that provides two additional 122 | functions 123 | 124 | .. autosummary:: 125 | :toctree: generated/ 126 | 127 | HybridBlock.hybridize 128 | HybridBlock.hybrid_forward 129 | 130 | 131 | Block construction with Symbol 132 | -------------------------------------- 133 | 134 | .. autosummary:: 135 | :toctree: generated/ 136 | 137 | SymbolBlock 138 | -------------------------------------------------------------------------------- /api/gluon/container.rst: -------------------------------------------------------------------------------- 1 | Container objects 2 | ===================== 3 | 4 | Besides constructing neural networks through creating a subclass of ``Block``, 5 | Gluon provides containers to facilitate the construction. 6 | 7 | 8 | .. admonition:: Example 9 | 10 | Import modules 11 | 12 | >>> from mxnet import np, npx 13 | >>> from mxnet.gluon import nn 14 | >>> npx.set_np() 15 | 16 | Construct a MLP 17 | 18 | >>> net = nn.Sequential() 19 | >>> net.add(nn.Dense(10, activation='relu'), 20 | ... nn.Dense(2)) 21 | 22 | Initialize the network and run forward 23 | 24 | >>> net.initialize() 25 | >>> x = np.random.uniform(size=(4, 20)) 26 | >>> print(net(x)) 27 | [[-0.01270512 0.01225275] 28 | [-0.01303939 0.01191816] 29 | [-0.01165176 0.00252366] 30 | [-0.02191715 0.01045103]] 31 | 32 | .. currentmodule:: mxnet.gluon 33 | 34 | .. autosummary:: 35 | :toctree: generated/ 36 | 37 | nn.Sequential 38 | nn.HybridSequential 39 | 40 | 41 | .. autosummary:: 42 | :toctree: generated/ 43 | 44 | contrib.nn.Concurrent 45 | contrib.nn.HybridConcurrent 46 | -------------------------------------------------------------------------------- /api/gluon/creation.rst: -------------------------------------------------------------------------------- 1 | Creating Nerual Networks 2 | =================================== 3 | 4 | The Gluon package provides multiple ways to construct a neural networks, and a 5 | large set of pre-defined neural network layers. 6 | 7 | .. toctree:: 8 | 9 | :maxdepth: 2 10 | 11 | block 12 | container 13 | nn 14 | rnn 15 | -------------------------------------------------------------------------------- /api/gluon/data.rst: -------------------------------------------------------------------------------- 1 | Loading Data 2 | ================= 3 | 4 | .. automodule:: mxnet.gluon 5 | 6 | Datasets 7 | -------- 8 | 9 | .. autosummary:: 10 | :toctree: _autogen 11 | 12 | data.Dataset 13 | data.ArrayDataset 14 | data.RecordFileDataset 15 | 16 | Sampling examples 17 | ------------------ 18 | 19 | .. autosummary:: 20 | :toctree: _autogen 21 | 22 | data.Sampler 23 | data.SequentialSampler 24 | data.RandomSampler 25 | data.BatchSampler 26 | 27 | Loading examples 28 | ---------------- 29 | 30 | .. autosummary:: 31 | :toctree: _autogen 32 | 33 | data.DataLoader 34 | -------------------------------------------------------------------------------- /api/gluon/index.rst: -------------------------------------------------------------------------------- 1 | Gluon reference 2 | ===================== 3 | 4 | The Gluon library in Apache MXNet provides a clear, concise, and simple API for deep learning. 5 | It makes it easy to prototype, build, and train deep learning models without sacrificing training speed. 6 | 7 | .. note:: 8 | 9 | The exmaples in API documents haven't fully updated yet, e.g. 10 | 11 | - Most examples use ndarrays defined in ``mxnet.nd``. We can replace it by 12 | the ndarrays in ``mxnet.np`` if running ``npx.set_np()`` before. 13 | 14 | - Some examples may put codes under the naming scope by ``with 15 | self.name_scope()``. It's optional since version 1.2. 16 | 17 | .. toctree:: 18 | :maxdepth: 2 19 | 20 | creation 21 | parameter 22 | initilization 23 | loss 24 | training 25 | data 26 | modelzoo 27 | utils 28 | -------------------------------------------------------------------------------- /api/gluon/loss.rst: -------------------------------------------------------------------------------- 1 | Loss functions 2 | ======================== 3 | 4 | Gluon provides pre-defined loss functions in the :py:mod:`mxnet.gluon.loss` 5 | module. 6 | 7 | .. automodule:: mxnet.gluon 8 | 9 | .. autosummary:: 10 | :toctree: generated/ 11 | 12 | loss.Loss 13 | loss.L2Loss 14 | loss.L1Loss 15 | loss.SigmoidBinaryCrossEntropyLoss 16 | loss.SoftmaxCrossEntropyLoss 17 | loss.KLDivLoss 18 | loss.HuberLoss 19 | loss.HingeLoss 20 | loss.SquaredHingeLoss 21 | loss.LogisticLoss 22 | loss.TripletLoss 23 | loss.CTCLoss 24 | -------------------------------------------------------------------------------- /api/gluon/modelzoo.rst: -------------------------------------------------------------------------------- 1 | Model Zoo 2 | ================= 3 | 4 | 5 | .. automodule:: mxnet.gluon.model_zoo.vision 6 | 7 | .. autosummary:: 8 | :toctree: _autogen 9 | 10 | get_model 11 | 12 | ResNet 13 | ------ 14 | 15 | .. autosummary:: 16 | :toctree: _autogen 17 | 18 | resnet18_v1 19 | resnet34_v1 20 | resnet50_v1 21 | resnet101_v1 22 | resnet152_v1 23 | resnet18_v2 24 | resnet34_v2 25 | resnet50_v2 26 | resnet101_v2 27 | resnet152_v2 28 | 29 | .. autosummary:: 30 | :toctree: _autogen 31 | 32 | ResNetV1 33 | ResNetV2 34 | BasicBlockV1 35 | BasicBlockV2 36 | BottleneckV1 37 | BottleneckV2 38 | get_resnet 39 | 40 | VGG 41 | --- 42 | 43 | .. autosummary:: 44 | :toctree: _autogen 45 | 46 | vgg11 47 | vgg13 48 | vgg16 49 | vgg19 50 | vgg11_bn 51 | vgg13_bn 52 | vgg16_bn 53 | vgg19_bn 54 | 55 | .. autosummary:: 56 | :toctree: _autogen 57 | 58 | VGG 59 | get_vgg 60 | 61 | Alexnet 62 | -------- 63 | 64 | .. autosummary:: 65 | :toctree: _autogen 66 | 67 | AlexNet 68 | 69 | 70 | DenseNet 71 | -------- 72 | 73 | 74 | .. autosummary:: 75 | :toctree: _autogen 76 | 77 | densenet121 78 | densenet161 79 | densenet169 80 | densenet201 81 | 82 | 83 | 84 | .. autosummary:: 85 | :toctree: _autogen 86 | 87 | DenseNet 88 | 89 | 90 | SqueezeNet 91 | ------------ 92 | 93 | 94 | .. autosummary:: 95 | :toctree: _autogen 96 | 97 | squeezenet1_0 98 | squeezenet1_1 99 | 100 | 101 | 102 | .. autosummary:: 103 | :toctree: _autogen 104 | 105 | SqueezeNet 106 | 107 | 108 | Inception 109 | --------- 110 | 111 | 112 | .. autosummary:: 113 | :toctree: _autogen 114 | 115 | inception_v3 116 | 117 | 118 | 119 | .. autosummary:: 120 | :toctree: _autogen 121 | 122 | Inception3 123 | 124 | 125 | MobileNet 126 | --------- 127 | 128 | 129 | .. autosummary:: 130 | :toctree: _autogen 131 | 132 | mobilenet1_0 133 | mobilenet0_75 134 | mobilenet0_5 135 | mobilenet0_25 136 | mobilenet_v2_1_0 137 | mobilenet_v2_0_75 138 | mobilenet_v2_0_5 139 | mobilenet_v2_0_25 140 | 141 | 142 | .. autosummary:: 143 | :toctree: _autogen 144 | 145 | MobileNet 146 | MobileNetV2 147 | -------------------------------------------------------------------------------- /api/gluon/mxnet.autograd.rst: -------------------------------------------------------------------------------- 1 | mxnet.autograd 2 | =================== 3 | 4 | .. automodule:: mxnet.autograd 5 | 6 | .. autosummary:: 7 | :toctree: _autogen 8 | 9 | 10 | backward 11 | get_symbol 12 | grad 13 | is_recording 14 | is_training 15 | mark_variables 16 | pause 17 | predict_mode 18 | record 19 | set_recording 20 | set_training 21 | train_mode 22 | Function 23 | 24 | .. disqus:: 25 | -------------------------------------------------------------------------------- /api/gluon/mxnet.gluon.Parameter.rst: -------------------------------------------------------------------------------- 1 | Parameter 2 | ========= 3 | 4 | .. currentmodule:: mxnet.gluon 5 | 6 | .. autoclass:: Parameter 7 | 8 | 9 | Get and set parameters 10 | ----------------------- 11 | 12 | .. autosummary:: 13 | :toctree: _autogen 14 | 15 | Parameter.initialize 16 | Parameter.data 17 | Parameter.list_data 18 | Parameter.list_row_sparse_data 19 | Parameter.row_sparse_data 20 | Parameter.set_data 21 | Parameter.shape 22 | 23 | 24 | Get and set gradients associated with parameters 25 | ------------------------------------------------- 26 | 27 | .. autosummary:: 28 | :toctree: _autogen 29 | 30 | Parameter.grad 31 | Parameter.list_grad 32 | Parameter.zero_grad 33 | Parameter.grad_req 34 | 35 | Handle device contexts 36 | ------------------------ 37 | 38 | .. autosummary:: 39 | :toctree: _autogen 40 | 41 | Parameter.cast 42 | Parameter.list_ctx 43 | Parameter.reset_ctx 44 | 45 | Convert to symbol 46 | -------------------- 47 | 48 | .. autosummary:: 49 | :toctree: _autogen 50 | 51 | Parameter.var 52 | -------------------------------------------------------------------------------- /api/gluon/mxnet.gluon.ParameterDict.rst: -------------------------------------------------------------------------------- 1 | ParameterDict 2 | ============= 3 | 4 | .. currentmodule:: mxnet.gluon 5 | 6 | .. autoclass:: ParameterDict 7 | 8 | Load and save parameters 9 | -------------------------- 10 | 11 | .. autosummary:: 12 | :toctree: _autogen 13 | 14 | ParameterDict.load 15 | ParameterDict.save 16 | 17 | Get a particular parameter 18 | -------------------------- 19 | 20 | .. autosummary:: 21 | :toctree: _autogen 22 | 23 | ParameterDict.get 24 | ParameterDict.get_constant 25 | 26 | Get (name, paramter) pairs 27 | -------------------------- 28 | 29 | .. autosummary:: 30 | :toctree: _autogen 31 | 32 | ParameterDict.items 33 | ParameterDict.keys 34 | ParameterDict.values 35 | 36 | Update parameters 37 | -------------------------- 38 | 39 | .. autosummary:: 40 | :toctree: _autogen 41 | 42 | ParameterDict.initialize 43 | ParameterDict.setattr 44 | ParameterDict.update 45 | 46 | 47 | Set devices contexts and gradients 48 | --------------------------------------- 49 | 50 | .. autosummary:: 51 | :toctree: _autogen 52 | 53 | ParameterDict.reset_ctx 54 | ParameterDict.zero_grad 55 | 56 | Attributes 57 | --------------------------------------- 58 | 59 | 60 | .. autosummary:: 61 | :toctree: _autogen 62 | 63 | ParameterDict.prefix 64 | -------------------------------------------------------------------------------- /api/gluon/mxnet.gluon.Trainer.rst: -------------------------------------------------------------------------------- 1 | Trainer 2 | =========== 3 | 4 | .. currentmodule:: mxnet.gluon 5 | 6 | .. autoclass:: Trainer 7 | 8 | Updating parameters 9 | ------------------- 10 | 11 | .. autosummary:: 12 | :toctree: _autogen 13 | 14 | Trainer.step 15 | Trainer.allreduce_grads 16 | Trainer.update 17 | 18 | Trainer States 19 | -------------- 20 | 21 | .. autosummary:: 22 | :toctree: _autogen 23 | 24 | Trainer.load_states 25 | Trainer.save_states 26 | 27 | Learning rate 28 | -------------- 29 | 30 | .. autosummary:: 31 | :toctree: _autogen 32 | 33 | Trainer.learning_rate 34 | Trainer.set_learning_rate 35 | -------------------------------------------------------------------------------- /api/gluon/mxnet.initializer.rst: -------------------------------------------------------------------------------- 1 | mxnet.initializer 2 | ================= 3 | 4 | .. automodule:: mxnet.initializer 5 | 6 | 7 | 8 | 9 | Initialization methods 10 | ----------------------- 11 | 12 | 13 | .. autosummary:: 14 | :toctree: _autogen/ 15 | 16 | Bilinear 17 | Constant 18 | FusedRNN 19 | InitDesc 20 | Initializer 21 | LSTMBias 22 | Load 23 | MSRAPrelu 24 | Mixed 25 | Normal 26 | One 27 | Orthogonal 28 | Uniform 29 | Xavier 30 | Zero 31 | 32 | 33 | 34 | 35 | Helper functions 36 | ---------------- 37 | 38 | .. autosummary:: 39 | :toctree: _autogen/ 40 | 41 | register 42 | 43 | 44 | 45 | 46 | 47 | .. disqus:: 48 | :disqus_identifier: mxnet.initializer 49 | -------------------------------------------------------------------------------- /api/gluon/mxnet.lr_scheduler.rst: -------------------------------------------------------------------------------- 1 | mxnet.lr\_scheduler 2 | =================== 3 | 4 | .. automodule:: mxnet.lr_scheduler 5 | 6 | .. autosummary:: 7 | :toctree: _autogen 8 | 9 | LRScheduler 10 | FactorScheduler 11 | MultiFactorScheduler 12 | PolyScheduler 13 | CosineScheduler 14 | 15 | .. disqus:: 16 | :disqus_identifier: mxnet.lr_scheduler 17 | -------------------------------------------------------------------------------- /api/gluon/mxnet.optimizer.rst: -------------------------------------------------------------------------------- 1 | mxnet.optimizer 2 | =============== 3 | 4 | .. automodule:: mxnet.optimizer 5 | 6 | 7 | 8 | Optimization methods 9 | -------------------- 10 | 11 | .. autosummary:: 12 | :toctree: _autogen 13 | 14 | AdaDelta 15 | AdaGrad 16 | Adam 17 | Adamax 18 | DCASGD 19 | FTML 20 | Ftrl 21 | LBSGD 22 | NAG 23 | Nadam 24 | Optimizer 25 | RMSProp 26 | SGD 27 | SGLD 28 | Signum 29 | Updater 30 | 31 | Helper functions 32 | ---------------- 33 | 34 | .. autosummary:: 35 | 36 | create 37 | get_updater 38 | register 39 | 40 | 41 | .. disqus:: 42 | :disqus_identifier: mxnet.optimizer 43 | -------------------------------------------------------------------------------- /api/gluon/nn.rst: -------------------------------------------------------------------------------- 1 | Feedforward Layers 2 | ============================================== 3 | 4 | Gluon provides a large number of build-in feedforward neural network layers in 5 | two modiules, ``mxnet.gluon.nn`` and ``mxnet.gluon.contrib.nn``. 6 | 7 | .. currentmodule:: mxnet.gluon 8 | 9 | 10 | Basic Layers 11 | ------------ 12 | 13 | .. autosummary:: 14 | :nosignatures: 15 | :toctree: _autogen 16 | 17 | nn.Dense 18 | nn.Activation 19 | nn.Dropout 20 | nn.Flatten 21 | nn.Lambda 22 | nn.HybridLambda 23 | 24 | Convolutional Layers 25 | -------------------- 26 | 27 | .. autosummary:: 28 | :nosignatures: 29 | :toctree: _autogen 30 | 31 | nn.Conv1D 32 | nn.Conv2D 33 | nn.Conv3D 34 | nn.Conv1DTranspose 35 | nn.Conv2DTranspose 36 | nn.Conv3DTranspose 37 | 38 | Pooling Layers 39 | -------------- 40 | 41 | .. autosummary:: 42 | :nosignatures: 43 | :toctree: _autogen 44 | 45 | nn.MaxPool1D 46 | nn.MaxPool2D 47 | nn.MaxPool3D 48 | nn.AvgPool1D 49 | nn.AvgPool2D 50 | nn.AvgPool3D 51 | nn.GlobalMaxPool1D 52 | nn.GlobalMaxPool2D 53 | nn.GlobalMaxPool3D 54 | nn.GlobalAvgPool1D 55 | nn.GlobalAvgPool2D 56 | nn.GlobalAvgPool3D 57 | nn.ReflectionPad2D 58 | 59 | Normalization Layers 60 | -------------------- 61 | 62 | .. autosummary:: 63 | :nosignatures: 64 | :toctree: _autogen 65 | 66 | nn.BatchNorm 67 | nn.InstanceNorm 68 | nn.LayerNorm 69 | contrib.nn.SyncBatchNorm 70 | 71 | Embedding Layers 72 | ---------------- 73 | 74 | .. autosummary:: 75 | :nosignatures: 76 | :toctree: _autogen 77 | 78 | nn.Embedding 79 | contrib.nn.SparseEmbedding 80 | 81 | 82 | Advanced Activation Layers 83 | -------------------------- 84 | 85 | .. autosummary:: 86 | :nosignatures: 87 | :toctree: _autogen 88 | 89 | nn.LeakyReLU 90 | nn.PReLU 91 | nn.ELU 92 | nn.SELU 93 | nn.Swish 94 | -------------------------------------------------------------------------------- /api/gluon/parameter.rst: -------------------------------------------------------------------------------- 1 | Parameters 2 | ================= 3 | 4 | Neural network parameters are often ndarrays. A ndarray, such as the weight of a 5 | dense layer, is presented as a ``Parameter`` object in Gluon. Then 6 | ``ParameterDict`` is used store multiple ``Parameter``'s. 7 | 8 | 9 | .. currentmodule:: mxnet.gluon 10 | 11 | .. autosummary:: 12 | :toctree: . 13 | 14 | Parameter 15 | ParameterDict 16 | 17 | 18 | .. admonition:: Example 19 | 20 | Import modules and construct a MLP. 21 | 22 | >>> from mxnet import np, npx 23 | >>> from mxnet.gluon import nn 24 | >>> npx.set_np() 25 | 26 | >>> net = nn.Sequential() 27 | >>> net.add(nn.Dense(10, activation='relu'), 28 | ... nn.Dense(2)) 29 | 30 | 31 | Access the weight of the first layer (uninitialized yet) 32 | 33 | >>> print(net[0].weight) 34 | Parameter dense0_weight (shape=(10, -1), dtype=float32) 35 | 36 | Get all parameters 37 | 38 | >>> print(net.collect_params()) 39 | sequential0_ ( 40 | Parameter dense0_weight (shape=(10, -1), dtype=float32) 41 | Parameter dense0_bias (shape=(10,), dtype=float32) 42 | Parameter dense1_weight (shape=(2, -1), dtype=float32) 43 | Parameter dense1_bias (shape=(2,), dtype=float32) 44 | ) 45 | 46 | We can 47 | 48 | .. currentmodule:: mxnet 49 | 50 | .. autosummary:: 51 | :toctree: . 52 | 53 | initializer 54 | -------------------------------------------------------------------------------- /api/gluon/rnn.rst: -------------------------------------------------------------------------------- 1 | Recurrent Layers 2 | ==================================== 3 | 4 | Recurrent neural network layers are provided in the following two modules: 5 | ``mxnet.gluon.rnn`` and ``mxnet.gluon.contrib.rnn``. 6 | 7 | 8 | .. currentmodule:: mxnet.gluon 9 | 10 | Recurrent Cells 11 | ---------------- 12 | 13 | .. autosummary:: 14 | :toctree: generated 15 | 16 | rnn.LSTMCell 17 | rnn.GRUCell 18 | rnn.RecurrentCell 19 | rnn.SequentialRNNCell 20 | rnn.BidirectionalCell 21 | rnn.DropoutCell 22 | rnn.ZoneoutCell 23 | rnn.ResidualCell 24 | contrib.rnn.Conv1DRNNCell 25 | contrib.rnn.Conv2DRNNCell 26 | contrib.rnn.Conv3DRNNCell 27 | contrib.rnn.Conv1DLSTMCell 28 | contrib.rnn.Conv2DLSTMCell 29 | contrib.rnn.Conv3DLSTMCell 30 | contrib.rnn.Conv1DGRUCell 31 | contrib.rnn.Conv2DGRUCell 32 | contrib.rnn.Conv3DGRUCell 33 | contrib.rnn.VariationalDropoutCell 34 | contrib.rnn.LSTMPCell 35 | 36 | Recurrent Layers 37 | ---------------- 38 | 39 | .. autosummary:: 40 | :toctree: generated 41 | 42 | 43 | rnn.RNN 44 | rnn.LSTM 45 | rnn.GRU 46 | -------------------------------------------------------------------------------- /api/gluon/training.rst: -------------------------------------------------------------------------------- 1 | Training 2 | =========== 3 | 4 | .. currentmodule:: mxnet.gluon 5 | 6 | .. autosummary:: 7 | :toctree: . 8 | 9 | Trainer 10 | 11 | .. currentmodule:: mxnet 12 | 13 | .. autosummary:: 14 | :toctree: . 15 | 16 | autograd 17 | optimizer 18 | lr_scheduler 19 | -------------------------------------------------------------------------------- /api/gluon/utils.rst: -------------------------------------------------------------------------------- 1 | Utility functions 2 | ======================== 3 | 4 | .. automodule:: mxnet.gluon 5 | 6 | .. autosummary:: 7 | :toctree: _autogen 8 | 9 | utils.split_data 10 | utils.split_and_load 11 | utils.clip_global_norm 12 | utils.download 13 | utils.check_sha1 14 | -------------------------------------------------------------------------------- /api/index.rst: -------------------------------------------------------------------------------- 1 | API 2 | === 3 | 4 | Overview 5 | -------- 6 | 7 | This API section details functions, modules, and objects included in MXNet, 8 | describing what they are and what they do. The APIs are grouped into the 9 | following categories: 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | :hidden: 14 | 15 | deepnumpy/index 16 | gluon/index 17 | -------------------------------------------------------------------------------- /build_html.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | rm -rf _build 4 | d2lbook build rst 5 | sphinx-autogen -t ./static/ _build/rst/api/*/*.rst _build/rst/api/*/*/*.rst 6 | d2lbook build html 7 | -------------------------------------------------------------------------------- /config.ini: -------------------------------------------------------------------------------- 1 | [project] 2 | 3 | # The project name, used as the filename of the package and the PDF file. For 4 | # example, if set to d2l-book, then will build d2l-book.zip and d2l-book.pdf 5 | name = deepnumpy 6 | 7 | # Book title. It will be displayed on the top-right of the HTML page and the 8 | # front page of the PDF file 9 | title = deepnumpy 10 | 11 | author = mxnet contributors 12 | 13 | copyright = 2019, All authors. Licensed under the CC BY-NC-SA 14 | 15 | release = 0.1 16 | 17 | [html] 18 | 19 | # A list of links that is displayed on the navbar. A link consists of three 20 | # items: name, URL, and a fontawesome icon 21 | # (https://fontawesome.com/icons?d=gallery). Items are separated by commas. 22 | header_links = D2L Book, http://numpy.d2l.ai, fas fa-external-link-alt, 23 | GitHub, https://github.com/mli/numpy-doc, fab fa-github 24 | 25 | favicon = static/mxnet-icon.png 26 | 27 | logo = static/mxnet-logo.svg 28 | 29 | include_js = static/*.js 30 | 31 | include_css = static/mxnet.css 32 | 33 | [build] 34 | 35 | rsts = index.rst api/**/*.rst install/*.rst guide/**/*.rst 36 | 37 | notebooks = **/*.md 38 | 39 | # A list of files that will be copied to the build folder. 40 | resources = 41 | 42 | # Files that will be skipped. 43 | # Temporarily disable notebooks that need a GPU wheel to run 44 | exclusions = README.md 45 | 46 | # If True (default), then will evaluate the notebook to obtain outputs. 47 | eval_notebook = True 48 | 49 | # If True, the mark the build as failed for any warning. Default is False. 50 | warning_is_error = False 51 | 52 | # A list of files, if anyone is modified after the last build, will re-build all 53 | # documents. 54 | dependencies = 55 | 56 | sphinx_extensions = numpydoc 57 | 58 | sphinx_configs = add_module_names = False 59 | autodoc_inherit_docstrings = True 60 | numpydoc_show_class_members = False 61 | numpydoc_show_inherited_class_members = False 62 | 63 | 64 | [deploy] 65 | s3_bucket = s3://numpy.mxnet.io 66 | 67 | google_analytics_tracking_id = UA-96378503-17 68 | -------------------------------------------------------------------------------- /guide/crash-course/1-ndarray.md: -------------------------------------------------------------------------------- 1 | 2 | # Step 1: Manipulate data with NP on MXNet 3 | :label:`crash_course_ndarray` 4 | 5 | This getting started exercise introduces the `np` package, which is the primary tool for storing and 6 | transforming data on MXNet. If you’ve worked with NumPy before, you’ll notice `np` is, by design, similar to NumPy. 7 | 8 | ## Import packages and create an array 9 | 10 | 11 | To get started, run the following commands to import the `np` package together with the NumPy extensions package `npx`. Together, `np` with `npx` make up the NP on MXNet front end. 12 | 13 | ```{.python .input n=1} 14 | from mxnet import np, npx 15 | npx.set_np() # Activate NumPy-like mode. 16 | ``` 17 | 18 | In this step, create a 2D array (also called a matrix). The following code example creates a matrix with values from two sets of numbers: 1, 2, 3 and 4, 5, 6. This might also be referred to as a tuple of a tuple of integers. 19 | 20 | ```{.python .input n=2} 21 | np.array(((1,2,3),(5,6,7))) 22 | ``` 23 | 24 | You can also create a very simple matrix with the same shape (2 rows by 3 columns), but fill it with 1s. 25 | 26 | ```{.python .input n=3} 27 | x = np.ones((2,3)) 28 | x 29 | ``` 30 | 31 | You can create arrays whose values are sampled randomly. For example, sampling values uniformly between -1 and 1. The following code example creates the same shape, but with random sampling. 32 | 33 | ```{.python .input n=15} 34 | y = np.random.uniform(-1,1, (2,3)) 35 | y 36 | ``` 37 | 38 | As with NumPy, the dimensions of each ndarray are shown by accessing the `.shape` attribute. As the following code example shows, you can also query for `size`, which is equal to the product of the components of the shape. In addition, `.dtype` tells the data type of the stored values. 39 | 40 | ```{.python .input n=17} 41 | (x.shape, x.size, x.dtype) 42 | ``` 43 | 44 | ## Performing operations on an array 45 | 46 | An ndarray supports a large number of standard mathematical operations. Here are three examples. You can perform element-wise multiplication by using the following code example. 47 | 48 | ```{.python .input n=18} 49 | x * y 50 | ``` 51 | 52 | You can perform exponentiation by using the following code example. 53 | 54 | ```{.python .input n=23} 55 | np.exp(y) 56 | ``` 57 | 58 | You can also find a matrix’s transpose to compute a proper matrix-matrix product by using the following code example. 59 | 60 | ```{.python .input n=24} 61 | np.dot(x, y.T) 62 | ``` 63 | 64 | ## Indexing an array 65 | 66 | The ndarrays support slicing in many ways you might want to access your data. The following code example shows how to read a particular element, which returns a 1D array with shape `(1,)`. 67 | 68 | ```{.python .input n=25} 69 | y[1,2] 70 | ``` 71 | 72 | This example shows how to read the second and third columns from `y`. 73 | 74 | ```{.python .input n=26} 75 | y[:,1:3] 76 | ``` 77 | 78 | This example shows how to write to a specific element. 79 | 80 | ```{.python .input n=27} 81 | y[:,1:3] = 2 82 | y 83 | ``` 84 | 85 | You can perform multi-dimensional slicing, which is shown in the following code example. 86 | 87 | ```{.python .input n=28} 88 | y[1:2,0:2] = 4 89 | y 90 | ``` 91 | 92 | ## Converting between MXNet ndarrays and NumPy ndarrays 93 | 94 | You can convert MXNet ndarrays to and from NumPy ndarrays, as shown in the following example. The converted arrays do not share memory. 95 | 96 | ```{.python .input n=29} 97 | a = x.asnumpy() 98 | (type(a), a) 99 | ``` 100 | 101 | ```{.python .input n=30} 102 | np.array(a) 103 | ``` 104 | 105 | ## Next steps 106 | 107 | Learn how to construct a neural network with the Gluon module: :ref:`crash_course_nn`. 108 | -------------------------------------------------------------------------------- /guide/crash-course/2-nn.md: -------------------------------------------------------------------------------- 1 | # Step 2: Create a neural network 2 | :label:`crash_course_nn` 3 | 4 | 5 | In this step, you learn how to use NP on MXNet to create neural networks in Gluon. In addition to the `np` package that you learned about in the previous step :ref:`crash_course_ndarray`, you also import the neural network `nn` package from `gluon`. 6 | 7 | Use the following commands to import the packages required for this step. 8 | 9 | ```{.python .input n=2} 10 | from mxnet import np, npx 11 | from mxnet.gluon import nn 12 | npx.set_np() # Change MXNet to the numpy-like mode. 13 | ``` 14 | 15 | ## Create your neural network's first layer 16 | 17 | Use the following code example to start with a dense layer with two output units. 18 | 19 | 20 | ```{.python .input n=31} 21 | layer = nn.Dense(2) 22 | layer 23 | ``` 24 | 25 | Initialize its weights with the default initialization method, which draws random values uniformly from $[-0.7, 0.7]$. You can see this in the following example. 26 | 27 | ```{.python .input n=32} 28 | layer.initialize() 29 | ``` 30 | 31 | Do a forward pass with random data, shown in the following example. We create a $(3,4)$ shape random input `x` and feed into the layer to compute the output. 32 | 33 | ```{.python .input n=34} 34 | x = np.random.uniform(-1,1,(3,4)) 35 | layer(x) 36 | ``` 37 | 38 | As can be seen, the layer's input limit of two produced a $(3,2)$ shape output from our $(3,4)$ input. You didn't specify the input size of `layer` before, though you can specify it with the argument `in_units=4` here. The system automatically infers it during the first time you feed in data, create, and initialize the weights. You can access the weight after the first forward pass, as shown in this example. 39 | 40 | ```{.python .input n=35} 41 | # layer.weight.data() # FIXME 42 | ``` 43 | 44 | ## Chain layers into a neural network 45 | 46 | Consider a simple case where a neural network is a chain of layers. During the forward pass, you run layers sequentially one-by-one. Use the following code to implement a famous network called [LeNet](http://yann.lecun.com/exdb/lenet/) through `nn.Sequential`. 47 | 48 | ```{.python .input} 49 | net = nn.Sequential() 50 | # Add a sequence of layers. 51 | net.add(# Similar to Dense, it is not necessary to specify the input channels 52 | # by the argument `in_channels`, which will be automatically inferred 53 | # in the first forward pass. Also, we apply a relu activation on the 54 | # output. In addition, we can use a tuple to specify a non-square 55 | # kernel size, such as `kernel_size=(2,4)` 56 | nn.Conv2D(channels=6, kernel_size=5, activation='relu'), 57 | # One can also use a tuple to specify non-symmetric pool and stride sizes 58 | nn.MaxPool2D(pool_size=2, strides=2), 59 | nn.Conv2D(channels=16, kernel_size=3, activation='relu'), 60 | nn.MaxPool2D(pool_size=2, strides=2), 61 | # The dense layer will automatically reshape the 4-D output of last 62 | # max pooling layer into the 2-D shape: (x.shape[0], x.size/x.shape[0]) 63 | nn.Dense(120, activation="relu"), 64 | nn.Dense(84, activation="relu"), 65 | nn.Dense(10)) 66 | net 67 | ``` 68 | 69 | 70 | 71 | Using `nn.Sequential` is similar to `nn.Dense`. In fact, both of them are subclasses of `nn.Block`. Use the following code to initialize the weights and run the forward pass. 72 | 73 | ```{.python .input} 74 | net.initialize() 75 | # Input shape is (batch_size, color_channels, height, width) 76 | x = np.random.uniform(size=(4,1,28,28)) 77 | y = net(x) 78 | y.shape 79 | ``` 80 | 81 | You can use `[]` to index a particular layer. For example, the following 82 | accesses the first layer's weight and sixth layer's bias. 83 | 84 | ```{.python .input} 85 | (net[0].weight.data().shape, net[5].bias.data().shape) 86 | ``` 87 | 88 | ## Create a neural network flexibly 89 | 90 | In `nn.Sequential`, MXNet will automatically construct the forward function that sequentially executes added layers. 91 | Here is another way to construct a network with a flexible forward function. 92 | 93 | Create a subclass of `nn.Block` and implement two methods by using the following code. 94 | 95 | - `__init__` create the layers 96 | - `forward` define the forward function. 97 | 98 | ```{.python .input n=6} 99 | class MixMLP(nn.Block): 100 | def __init__(self, **kwargs): 101 | # Run `nn.Block`'s init method 102 | super(MixMLP, self).__init__(**kwargs) 103 | self.blk = nn.Sequential() 104 | self.blk.add(nn.Dense(3, activation='relu'), 105 | nn.Dense(4, activation='relu')) 106 | self.dense = nn.Dense(5) 107 | def forward(self, x): 108 | y = npx.relu(self.blk(x)) 109 | print(y) 110 | return self.dense(y) 111 | 112 | net = MixMLP() 113 | net 114 | ``` 115 | 116 | In the sequential chaining approach, you can only add instances with `nn.Block` as the base class and then run them in a forward pass. In this example, you used `print` to get the intermediate results and `nd.relu` to apply relu activation. This approach provides a more flexible way to define the forward function. 117 | 118 | The following code example uses `net` in a similar manner as earlier. 119 | 120 | ```{.python .input} 121 | net.initialize() 122 | x = np.random.uniform(size=(2,2)) 123 | net(x) 124 | ``` 125 | 126 | Finally, access a particular layer's weight with this code. 127 | 128 | ```{.python .input n=8} 129 | net.blk[1].weight.data() 130 | ``` 131 | 132 | ## Next steps 133 | 134 | After you create a neural network, learn how to automatically 135 | compute the gradients in :ref:`crash_course_autograd`. 136 | -------------------------------------------------------------------------------- /guide/crash-course/3-autograd.md: -------------------------------------------------------------------------------- 1 | # Step 3: Automatic differentiation with autograd 2 | :label:`crash_course_autograd` 3 | 4 | In this step, you learn how to use the MXNet `autograd` package to perform gradient calculations by automatically calculating derivatives. 5 | 6 | This is helpful because it will help you save time and effort. You train models to get better as a function of experience. Usually, getting better means minimizing a loss function. To achieve this goal, you often iteratively compute the gradient of the loss with respect to weights and then update the weights accordingly. Gradient calculations are straightforward through a chain rule. However, for complex models, working this out manually is challenging. 7 | 8 | The `autograd` package helps you by automatically calculating derivatives. 9 | 10 | ## Basic use 11 | 12 | To get started, import the `autograd` package as in the following code. 13 | 14 | ```{.python .input} 15 | from mxnet import np, npx 16 | from mxnet import autograd 17 | npx.set_np() 18 | ``` 19 | 20 | As an example, you could differentiate a function $f(x) = 2 x^2$ with respect to parameter $x$. You can start by assigning an initial value of $x$, as follows: 21 | 22 | ```{.python .input n=3} 23 | x = np.array([[1, 2], [3, 4]]) 24 | x 25 | ``` 26 | 27 | After you compute the gradient of $f(x)$ with respect to $x$, you need a place to store it. In MXNet, you can tell an ndarray that you plan to store a gradient by invoking its `attach_grad` method, shown in the following example. 28 | 29 | ```{.python .input n=6} 30 | x.attach_grad() 31 | ``` 32 | 33 | Next, define the function $y=f(x)$. To let MXNet store $y$, so that you can compute gradients later, use the following code to put the definition inside an `autograd.record()` scope. 34 | 35 | ```{.python .input n=7} 36 | with autograd.record(): 37 | y = 2 * x * x 38 | ``` 39 | 40 | You can invoke back propagation (backprop) by calling `y.backward()`. When $y$ has more than one entry, `y.backward()` is equivalent to `y.sum().backward()`. 41 | 42 | 43 | ```{.python .input n=8} 44 | y.backward() 45 | ``` 46 | 47 | Next, verify whether this is the expected output. Note that $y=2x^2$ and $\frac{dy}{dx} = 4x$, which should be `[[4, 8],[12, 16]]`. Check the automatically computed results. 48 | 49 | ```{.python .input n=9} 50 | x.grad 51 | ``` 52 | 53 | ## Using Python control flows 54 | 55 | Sometimes you want to write dynamic programs where the execution depends on real-time values. MXNet records the execution trace and computes the gradient as well. 56 | 57 | Consider the following function `f` in the following example code. The function doubles the inputs until its `norm` reaches 1000. Then it selects one element depending on the sum of its elements. 58 | 59 | 60 | ```{.python .input} 61 | def f(a): 62 | b = a * 2 63 | while np.abs(b).sum() < 1000: 64 | b = b * 2 65 | if b.sum() >= 0: 66 | c = b[0] 67 | else: 68 | c = b[1] 69 | return c 70 | ``` 71 | 72 | In this example, you record the trace and feed in a random value. 73 | 74 | ```{.python .input} 75 | a = np.random.uniform(size=2) 76 | a.attach_grad() 77 | with autograd.record(): 78 | c = f(a) 79 | c.backward() 80 | ``` 81 | 82 | You can see that `b` is a linear function of `a`, and `c` is chosen from `b`. The gradient with respect to `a` be will be either `[c/a[0], 0]` or `[0, c/a[1]]`, depending on which element from `b` is picked. You see the results of this example with this code: 83 | 84 | ```{.python .input} 85 | a.grad == c/a 86 | ``` 87 | 88 | ## Next Steps 89 | 90 | After you have used `autograd`, learn about training a neural network. See :ref:`crash_course_train`. 91 | -------------------------------------------------------------------------------- /guide/crash-course/4-train.md: -------------------------------------------------------------------------------- 1 | # Step 4: Train the neural network 2 | :label:`crash_course_train` 3 | 4 | In this step, you learn how to train the previously defined network with data. First, import the libraries. The new ones are `mxnet.init` for more weight initialization methods. Import the `datasets` and `transforms` to load and transform computer vision datasets. Import `matplotlib` for drawing, and `time` for benchmarking. The example command here shows this. 5 | 6 | ```{.python .input n=1} 7 | # Uncomment the following line if matplotlib is not installed. 8 | # !pip install matplotlib 9 | 10 | from mxnet import np, npx, gluon, init, autograd 11 | from mxnet.gluon import nn 12 | from IPython import display 13 | import matplotlib.pyplot as plt 14 | import time 15 | npx.set_np() 16 | ``` 17 | 18 | ## Get data 19 | 20 | The handwritten digit, MNIST dataset is one of the most commonly used datasets in deep learning. However, it's too simple to get 99 percent accuracy. For this tutorial, you use a similar but slightly more complicated dataset called FashionMNIST. The end-goal is to classify clothing types. 21 | 22 | The dataset can be automatically downloaded through Gluon's `data.vision.datasets` module. The following code downloads the training dataset and shows the first example. 23 | 24 | ```{.python .input n=2} 25 | mnist_train = gluon.data.vision.datasets.FashionMNIST(train=True) 26 | X, y = mnist_train[0] 27 | ('X shape: ', X.shape, 'X dtype', X.dtype, 'y:', y) 28 | ``` 29 | 30 | Each example in this dataset is a $28\times 28$ size grey image, which is presented as ndarray with the shape format of `(height, width, channel)`. The label is a `numpy` scalar. 31 | 32 | Next, visualize the first six examples. 33 | 34 | ```{.python .input n=3} 35 | text_labels = ['t-shirt', 'trouser', 'pullover', 'dress', 'coat', 36 | 'sandal', 'shirt', 'sneaker', 'bag', 'ankle boot'] 37 | X, y = mnist_train[0:10] 38 | # plot images 39 | display.set_matplotlib_formats('svg') 40 | _, figs = plt.subplots(1, X.shape[0], figsize=(15, 15)) 41 | for f, x, yi in zip(figs, X, y): 42 | # 3D->2D by removing the last channel dim 43 | f.imshow(x.reshape((28,28)).asnumpy()) 44 | ax = f.axes 45 | ax.set_title(text_labels[int(yi)]) 46 | ax.title.set_fontsize(14) 47 | ax.get_xaxis().set_visible(False) 48 | ax.get_yaxis().set_visible(False) 49 | plt.show() 50 | ``` 51 | 52 | In order to feed data into a Gluon model, convert the images to the `(channel, height, width)` format with a floating point data type. It can be done by `transforms.ToTensor`. In addition, normalize all pixel values with `transforms.Normalize` with the real mean 0.13 and standard deviation 0.31. You can chain these two transforms together and apply it to the first element of the data pair, namely the images. 53 | 54 | ```{.python .input n=4} 55 | transformer = gluon.data.vision.transforms.Compose([ 56 | gluon.data.vision.transforms.ToTensor(), 57 | gluon.data.vision.transforms.Normalize(0.13, 0.31)]) 58 | mnist_train = mnist_train.transform_first(transformer) 59 | ``` 60 | 61 | `FashionMNIST` is a subclass of `gluon.data.Dataset`, which defines how to get the `i`-th example. In order to use it in training, you need to get a (randomized) batch of examples. Do this by using `gluon.data.DataLoader`. The example here uses four works to process data in parallel, which is often necessary especially for complex data transforms. 62 | 63 | ```{.python .input n=5} 64 | batch_size = 256 65 | train_data = gluon.data.DataLoader( 66 | mnist_train, batch_size=batch_size, shuffle=True, num_workers=4) 67 | ``` 68 | 69 | The returned `train_data` is an iterable object that yields batches of images and labels pairs. 70 | 71 | ```{.python .input n=6} 72 | for data, label in train_data: 73 | print(data.shape, label.shape) 74 | break 75 | ``` 76 | 77 | Finally, create a validation dataset and data loader. 78 | 79 | ```{.python .input n=7} 80 | mnist_valid = gluon.data.vision.FashionMNIST(train=False) 81 | valid_data = gluon.data.DataLoader( 82 | mnist_valid.transform_first(transformer), 83 | batch_size=batch_size, num_workers=4) 84 | ``` 85 | 86 | ## Define the model 87 | 88 | Implement the network called [LeNet](http://yann.lecun.com/exdb/lenet/). One difference here is that you change the weight initialization method to `Xavier`, which is a popular choice for deep convolutional neural networks. 89 | 90 | ```{.python .input n=8} 91 | net = nn.Sequential() 92 | net.add(nn.Conv2D(channels=6, kernel_size=5, activation='relu'), 93 | nn.MaxPool2D(pool_size=2, strides=2), 94 | nn.Conv2D(channels=16, kernel_size=3, activation='relu'), 95 | nn.MaxPool2D(pool_size=2, strides=2), 96 | nn.Dense(120, activation="relu"), 97 | nn.Dense(84, activation="relu"), 98 | nn.Dense(10)) 99 | net.initialize(init=init.Xavier()) 100 | ``` 101 | 102 | In addition to the neural network, define the loss function and optimization method for training. Use standard softmax cross entropy loss for classification problems. It first performs softmax on the output to obtain the predicted probability, and then compares the label with the cross entropy. 103 | 104 | ```{.python .input n=9} 105 | softmax_cross_entropy = gluon.loss.SoftmaxCrossEntropyLoss() 106 | ``` 107 | 108 | The optimization method you pick is the standard stochastic gradient descent with constant learning rate of 0.1. 109 | 110 | ```{.python .input n=10} 111 | trainer = gluon.Trainer(net.collect_params(), 'sgd', {'learning_rate': 0.1}) 112 | ``` 113 | 114 | The `trainer` is created with all parameters (both weights and gradients) in `net`. Later on, you only need to call the `step` method to update its weights. 115 | 116 | ## Train the model 117 | 118 | Create an auxiliary function to calculate the model accuracy. 119 | 120 | ```{.python .input n=11} 121 | def acc(output, label): 122 | # output: (batch, num_output) float32 ndarray 123 | # label: (batch, ) int32 ndarray 124 | return (output.argmax(axis=1) == label.astype('float32')).mean() 125 | ``` 126 | 127 | Implement the complete training loop. 128 | 129 | ```{.python .input n=12} 130 | for epoch in range(10): 131 | train_loss, train_acc, valid_acc = 0., 0., 0. 132 | tic = time.time() 133 | for data, label in train_data: 134 | # forward + backward 135 | with autograd.record(): 136 | output = net(data) 137 | loss = softmax_cross_entropy(output, label) 138 | loss.backward() 139 | # update parameters 140 | trainer.step(batch_size) 141 | # calculate training metrics 142 | train_loss += loss.mean() 143 | train_acc += acc(output, label) 144 | # calculate validation accuracy 145 | for data, label in valid_data: 146 | valid_acc += acc(net(data), label) 147 | print("Epoch %d: loss %.3f, train acc %.3f, test acc %.3f, in %.1f sec" % ( 148 | epoch, train_loss/len(train_data), train_acc/len(train_data), 149 | valid_acc/len(valid_data), time.time()-tic)) 150 | ``` 151 | 152 | ## Save the model 153 | 154 | Finally, save the trained parameters onto disk, so that you can use them later. 155 | 156 | ```{.python .input n=13} 157 | net.save_parameters('net.params') 158 | ``` 159 | 160 | ## Next Steps 161 | 162 | After the model is trained and saved, learn how to use it to predict new examples: :ref:`crash_course_predict`. 163 | -------------------------------------------------------------------------------- /guide/crash-course/5-predict.md: -------------------------------------------------------------------------------- 1 | # Step 5: Predict with a pretrained model 2 | :label:`crash_course_predict` 3 | 4 | In this step, you learn how to predict new examples using a pretrained model. A saved model can be used in multiple places, such as to continue training, to fine tune the model, and for prediction. 5 | 6 | ## Prerequisites 7 | 8 | Before you begin the procedures here, run :label:`crash_course_train` to train the network and save its parameters to file. You use this file to run the following steps. 9 | 10 | ```{.python .input n=1} 11 | from mxnet import np, npx, gluon, image 12 | from mxnet.gluon import nn 13 | from IPython import display 14 | import matplotlib.pyplot as plt 15 | npx.set_np() 16 | ``` 17 | 18 | To start, copy a simple model's definition by using the following code. 19 | 20 | ```{.python .input n=2} 21 | net = nn.Sequential() 22 | net.add(nn.Conv2D(channels=6, kernel_size=5, activation='relu'), 23 | nn.MaxPool2D(pool_size=2, strides=2), 24 | nn.Conv2D(channels=16, kernel_size=3, activation='relu'), 25 | nn.MaxPool2D(pool_size=2, strides=2), 26 | nn.Dense(120, activation="relu"), 27 | nn.Dense(84, activation="relu"), 28 | nn.Dense(10)) 29 | ``` 30 | 31 | In the previous step, you saved all parameters to a file. Now load it back. 32 | 33 | ```{.python .input n=3} 34 | net.load_parameters('net.params') 35 | ``` 36 | 37 | ## Predict 38 | 39 | Remember the data transformation you did for the training step? The following code provides the same transformation for predicting. 40 | 41 | ```{.python .input n=4} 42 | transformer = gluon.data.vision.transforms.Compose([ 43 | gluon.data.vision.transforms.ToTensor(), 44 | gluon.data.vision.transforms.Normalize(0.13, 0.31)]) 45 | ``` 46 | 47 | Use the following code to predict the first six images in the validation dataset and store the predictions into `preds`. 48 | 49 | ```{.python .input n=5} 50 | mnist_valid = gluon.data.vision.datasets.FashionMNIST(train=False) 51 | X, y = mnist_valid[:10] 52 | preds = [] 53 | for x in X: 54 | x = np.expand_dims(transformer(x), axis=0) 55 | pred = net(x).argmax(axis=1) 56 | preds.append(int(pred)) 57 | ``` 58 | 59 | Finally, use the following code to visualize the images and compare the prediction with the ground truth. 60 | 61 | ```{.python .input n=15} 62 | _, figs = plt.subplots(1, 10, figsize=(15, 15)) 63 | text_labels = ['t-shirt', 'trouser', 'pullover', 'dress', 'coat', 64 | 'sandal', 'shirt', 'sneaker', 'bag', 'ankle boot'] 65 | display.set_matplotlib_formats('svg') 66 | for f, x, yi, pyi in zip(figs, X, y, preds): 67 | f.imshow(x.reshape((28,28)).asnumpy()) 68 | ax = f.axes 69 | ax.set_title(text_labels[int(yi)]+'\n'+text_labels[pyi]) 70 | ax.title.set_fontsize(14) 71 | ax.get_xaxis().set_visible(False) 72 | ax.get_yaxis().set_visible(False) 73 | plt.show() 74 | ``` 75 | 76 | ## Predict with models from Gluon model zoo 77 | 78 | 79 | The LeNet, trained on FashionMNIST, is a good example to start with. However, it's too simple to predict real-life pictures. In order to save the time and effort of training a large-scale model from scratch, the [Gluon model zoo](https://mxnet.incubator.apache.org/api/python/gluon/model_zoo.html) provides multiple pre-trained models. For example, with the following code example, you can download a pre-trained ResNet-50 V2 model that was trained on the ImageNet dataset. 80 | 81 | ```{.python .input n=7} 82 | net = gluon.model_zoo.vision.resnet50_v2(pretrained=True) 83 | ``` 84 | 85 | You'll also need to download the text labels for each class, as in the following example. 86 | 87 | ```{.python .input n=8} 88 | url = 'http://data.mxnet.io/models/imagenet/synset.txt' 89 | fname = gluon.utils.download(url) 90 | with open(fname, 'r') as f: 91 | text_labels = [' '.join(l.split()[1:]) for l in f] 92 | ``` 93 | 94 | The following example shows how to select a dog image from Wikipedia as a test, download and read it. 95 | 96 | ```{.python .input n=9} 97 | url = 'https://upload.wikimedia.org/wikipedia/commons/thumb/b/b5/\ 98 | Golden_Retriever_medium-to-light-coat.jpg/\ 99 | 365px-Golden_Retriever_medium-to-light-coat.jpg' 100 | fname = gluon.utils.download(url) 101 | x = image.imread(fname) # TODO, use npx.image instead 102 | ``` 103 | 104 | Following the conventional way of preprocessing ImageNet data, do the following: 105 | 106 | 1. Resize the short edge into 256 pixes. 107 | 2. Perform a center crop to obtain a 224-by-224 image. 108 | 109 | ```{.python .input n=10} 110 | x = image.resize_short(x, 256) 111 | x, _ = image.center_crop(x, (224,224)) 112 | plt.imshow(x.asnumpy()) 113 | plt.show() 114 | ``` 115 | 116 | Now you can see it is a golden retriever. You can also infer it from the image URL. 117 | 118 | The next data transformation is similar to FashionMNIST. Here, you subtract the RGB means and divide by the corresponding variances to normalize each color channel. 119 | 120 | ```{.python .input n=11} 121 | def transform(data): 122 | data = np.expand_dims(np.transpose(data, (2,0,1)), axis=0) 123 | rgb_mean = np.array([0.485, 0.456, 0.406]).reshape((1,3,1,1)) 124 | rgb_std = np.array([0.229, 0.224, 0.225]).reshape((1,3,1,1)) 125 | return (data.astype('float32') / 255 - rgb_mean) / rgb_std 126 | ``` 127 | 128 | Now you can recognize the object in the image. Perform an additional softmax on the output to obtain probability scores. Print the top-5 recognized objects. 129 | 130 | ```{.python .input n=12} 131 | prob = npx.softmax(net(transform(x))) 132 | idx = npx.topk(prob, k=5)[0] 133 | for i in idx: 134 | print('With prob = %.5f, it contains %s' % ( 135 | prob[0, int(i)], text_labels[int(i)])) 136 | ``` 137 | 138 | As can be seen, the model is fairly confident that the image contains a golden retriever. 139 | 140 | ## Next Steps 141 | 142 | You might find that both training and prediction are a little bit slow. If you have a GPU 143 | available, learn how to accomplish your tasks faster in :ref:`crash_course_gpu`. 144 | -------------------------------------------------------------------------------- /guide/crash-course/6-use_gpus.md: -------------------------------------------------------------------------------- 1 | # Step 6: Use GPUs to increase efficiency 2 | :label:`crash_course_gpu` 3 | 4 | In this step, you learn how to use graphics processing units (GPUs) with MXNet. If you use GPUs to train and deploy neural networks, you get significantly more computational power when compared to central processing units (CPUs). 5 | 6 | ## Prerequisites 7 | 8 | Before you start the other steps here, make sure you have at least one Nvidia GPU in your machine and CUDA properly installed. GPUs from AMD and Intel are not supported. Install the GPU-enabled version of MXNet. 9 | 10 | Use the following commands to check the number GPUs that are available. 11 | 12 | ```{.python .input n=2} 13 | from mxnet import np, npx, gluon, autograd 14 | from mxnet.gluon import nn 15 | import time 16 | npx.set_np() 17 | 18 | npx.num_gpus() 19 | ``` 20 | 21 | ## Allocate data to a GPU 22 | 23 | MXNet's ndarray is very similar to NumPy. One major difference is MXNet's ndarray has a `context` attribute that specifies which device an array is on. By default, it is on `npx.cpu()`. Change it to the first GPU with the following code. Use `npx.gpu()` or `npx.gpu(0)` to indicate the first GPU. 24 | 25 | ```{.python .input n=10} 26 | gpu = npx.gpu() if npx.num_gpus() > 0 else npx.cpu() 27 | x = np.ones((3,4), ctx=gpu) 28 | x 29 | ``` 30 | 31 | If you're using a CPU, MXNet allocates data on main memory and tries to use as many CPU cores as possible. This is true even if there is more than one CPU socket. If there are multiple GPUs, MXNet specifies which GPUs the ndarray is allocated. 32 | 33 | Assume there is a least one more GPU. Create another ndarray and assign it there. If you only have one GPU, then you get an error. In the example code here, you copy `x` to the second GPU, `npx.gpu(1)`: 34 | 35 | ```{.python .input n=11} 36 | gpu_1 = npx.gpu(1) if npx.num_gpus() > 1 else npx.cpu() 37 | x.copyto(gpu_1) 38 | ``` 39 | 40 | MXNet requries that users explicitly move data between devices. But several operators such as `print`, and `asnumpy`, will implicitly move data to main memory. 41 | 42 | ## Run an operation on a GPU 43 | 44 | To perform an operation on a particular GPU, you only need to guarantee that the input of an operation is already on that GPU. The output is allocated on the same GPU as well. Almost all operators in the `np` and `npx` module support running on a GPU. 45 | 46 | ```{.python .input n=21} 47 | y = np.random.uniform(size=(3,4), ctx=gpu) 48 | x + y 49 | ``` 50 | 51 | Remember that if the inputs are not on the same GPU, you get an error. 52 | 53 | ## Run a neural network on a GPU 54 | 55 | To run a neural network on a GPU, you only need to copy and move the input data and parameters to the GPU. Reuse the previously defined LeNet. The following code example shows this. 56 | 57 | ```{.python .input n=16} 58 | net = nn.Sequential() 59 | net.add(nn.Conv2D(channels=6, kernel_size=5, activation='relu'), 60 | nn.MaxPool2D(pool_size=2, strides=2), 61 | nn.Conv2D(channels=16, kernel_size=3, activation='relu'), 62 | nn.MaxPool2D(pool_size=2, strides=2), 63 | nn.Dense(120, activation="relu"), 64 | nn.Dense(84, activation="relu"), 65 | nn.Dense(10)) 66 | ``` 67 | 68 | Load the saved parameters into GPU 0 directly as shown here, or use `net.collect_params().reset_ctx` to change the device. 69 | 70 | ```{.python .input n=20} 71 | net.load_parameters('net.params', ctx=gpu) 72 | ``` 73 | 74 | Use the following command to create input data on GPU 0. The forward function will then run on GPU 0. 75 | 76 | ```{.python .input n=22} 77 | # x = np.random.uniform(size=(1,1,28,28), ctx=gpu) 78 | # net(x) FIXME 79 | ``` 80 | 81 | ## Training with multiple GPUs 82 | 83 | Finally, you can see how to use multiple GPUs to jointly train a neural network through data parallelism. Assume there are *n* GPUs. Split each data batch into *n* parts, and then each GPU will run the forward and backward passes using one part of the data. 84 | 85 | First copy the data definitions with the following commands, and the transform function from the [Predict tutorial](predict.md). 86 | 87 | ```{.python .input} 88 | batch_size = 256 89 | transformer = gluon.data.vision.transforms.Compose([ 90 | gluon.data.vision.transforms.ToTensor(), 91 | gluon.data.vision.transforms.Normalize(0.13, 0.31)]) 92 | train_data = gluon.data.DataLoader( 93 | gluon.data.vision.datasets.FashionMNIST(train=True).transform_first( 94 | transformer), batch_size, shuffle=True, num_workers=4) 95 | valid_data = gluon.data.DataLoader( 96 | gluon.data.vision.datasets.FashionMNIST(train=False).transform_first( 97 | transformer), batch_size, shuffle=False, num_workers=4) 98 | ``` 99 | 100 | The training loop is quite similar to that shown earlier. The major differences are highlighted in the following code. 101 | 102 | ```{.python .input} 103 | # Diff 1: Use two GPUs for training. 104 | devices = [gpu, gpu_1] 105 | # Diff 2: reinitialize the parameters and place them on multiple GPUs 106 | net.collect_params().initialize(force_reinit=True, ctx=devices) 107 | # Loss and trainer are the same as before 108 | softmax_cross_entropy = gluon.loss.SoftmaxCrossEntropyLoss() 109 | trainer = gluon.Trainer(net.collect_params(), 'sgd', {'learning_rate': 0.1}) 110 | for epoch in range(10): 111 | train_loss = 0. 112 | tic = time.time() 113 | for data, label in train_data: 114 | # Diff 3: split batch and load into corresponding devices 115 | data_list = gluon.utils.split_and_load(data, devices) 116 | label_list = gluon.utils.split_and_load(label, devices) 117 | # Diff 4: run forward and backward on each devices. 118 | # MXNet will automatically run them in parallel 119 | with autograd.record(): 120 | losses = [softmax_cross_entropy(net(X), y) 121 | for X, y in zip(data_list, label_list)] 122 | for l in losses: 123 | l.backward() 124 | trainer.step(batch_size) 125 | # Diff 5: sum losses over all devices. Here float will copy data 126 | # into CPU. 127 | train_loss += sum([float(l.sum()) for l in losses]) 128 | print("Epoch %d: loss %.3f, in %.1f sec" % ( 129 | epoch, train_loss/len(train_data)/batch_size, time.time()-tic)) 130 | ``` 131 | 132 | ## Next steps 133 | 134 | Now you have completed training and predicting with a neural network by using NP on MXNet and 135 | Gluon. You can check the guides to these two front ends: :ref:`deepnumpy_guide` and :ref:`gluon_guide`. 136 | -------------------------------------------------------------------------------- /guide/crash-course/index.rst: -------------------------------------------------------------------------------- 1 | Getting started with NP on MXNet 2 | ============ 3 | 4 | This crash course shows how to get started with NP on MXNet. The topics here provide a quick overview of the core concepts for both NP on MXNet, which helps you manipulate multiple dimensional arrays, and Gluon, which helps you create and train neural 5 | networks. This is a good place to start if you are already familiar with machine learning or other deep learning frameworks. 6 | 7 | .. toctree:: 8 | :maxdepth: 1 9 | :caption: Contents 10 | 11 | 1-ndarray 12 | 2-nn 13 | 3-autograd 14 | 4-train 15 | 5-predict 16 | 6-use_gpus 17 | -------------------------------------------------------------------------------- /guide/deepnumpy/cheat-sheet.md: -------------------------------------------------------------------------------- 1 | # The NP on MXNet cheat sheet 2 | :label:`deepnumpy_cheat_sheet` 3 | 4 | To begin, import the `np` and `npx` module and update MXNet to run in 5 | NumPy-like mode. 6 | 7 | ```{.python .input n=1} 8 | from mxnet import np, npx 9 | npx.set_np() # Change MXNet to the numpy-like mode. 10 | ``` 11 | 12 | NDArray figure (TODO) 13 | 14 | ## Creating arrays 15 | 16 | ```{.python .input n=2} 17 | np.array([1, 2, 3]) # default datatype is float32 18 | ``` 19 | 20 | ```{.python .input n=3} 21 | np.array([(1.5, 2, 3), (4, 5, 6)], dtype='float16') 22 | ``` 23 | 24 | ```{.python .input n=4} 25 | np.array([[(15,2,3), (4,5,6)], [(3,2,1), (4,5,6)]], dtype='int32') 26 | ``` 27 | 28 | ### Initial placeholders 29 | 30 | ```{.python .input n=5} 31 | np.zeros((3, 4)) # Create an array of zeros 32 | ``` 33 | 34 | ```{.python .input n=6} 35 | np.ones((2, 3, 4), dtype='int8') # Create an array of ones 36 | ``` 37 | 38 | ```{.python .input n=7} 39 | np.arange(10, 25, 5) # Create an array of evenly spaced values (step value) 40 | ``` 41 | 42 | ```{.python .input n=8} 43 | # Create an array of evenly spaced values (number of samples) 44 | # np.linspace(0, 2, 9) 45 | ``` 46 | 47 | ```{.python .input n=9} 48 | # np.full((2, 2), 7) # Create a constant array 49 | ``` 50 | 51 | ```{.python .input n=10} 52 | # np.eye(2) # Create a 2X2 identity matrix 53 | ``` 54 | 55 | ```{.python .input n=11} 56 | # np.random.random((2, 2)) # Create an array with random values 57 | ``` 58 | 59 | ```{.python .input n=12} 60 | np.empty((3,2)) # Create an empty array 61 | ``` 62 | 63 | ## I/O 64 | 65 | ### Saving and loading on disk 66 | 67 | ```{.python .input n=12} 68 | # Save one array 69 | a = np.array([1, 2, 3]) 70 | npx.save('my_array', a) 71 | npx.load('my_array') 72 | ``` 73 | 74 | ```{.python .input n=20} 75 | # Save a list of arrays 76 | b = np.array([4, 6, 8]) 77 | npx.save('my_arrays', [a, b]) # FIXME, cannot be a tuple 78 | npx.load('my_arrays') 79 | ``` 80 | 81 | ### Saving and loading text files 82 | 83 | ```{.python .input n=20} 84 | # np.loadtxt("myfile.txt") 85 | # np.genfromtxt("my_file.csv", delimiter=',') 86 | # np.savetxt("myarray.txt", a, delimiter=" ") 87 | ``` 88 | 89 | ## Data types 90 | 91 | ```{.python .input n=20} 92 | # np.int64 # Signed 64-bit integer types 93 | # np.float32 # Standard double-precision floating point 94 | # np.complex # Complex numbers represented by 128 floats 95 | # np.bool # Boolean type storing TRUE and FALSE values 96 | # np.object # Python object type 97 | # np.string_ # Fixed-length string type 98 | # np.unicode_ # Fixed-length unicode type 99 | ``` 100 | 101 | ## Inspecting your array 102 | 103 | ```{.python .input n=21} 104 | a.shape # Array dimensions 105 | ``` 106 | 107 | ```{.python .input n=22} 108 | len(a) # Length of array 109 | ``` 110 | 111 | ```{.python .input n=23} 112 | b.ndim # Number of array dimensions 113 | ``` 114 | 115 | ```{.python .input n=24} 116 | b.size # Number of array elements 117 | ``` 118 | 119 | ```{.python .input n=25} 120 | b.dtype # Data type of array elements 121 | ``` 122 | 123 | ```{.python .input n=29} 124 | # b.dtype.name # Name of data type 125 | ``` 126 | 127 | ```{.python .input n=35} 128 | b.astype('int') # Convert an array to a different type 129 | ``` 130 | 131 | ## Asking For Help 132 | 133 | ```{.python .input n=36} 134 | # np.info(np.ndarray.dtype) 135 | ``` 136 | 137 | ## Array mathematics 138 | 139 | ### Arithmetic operations 140 | 141 | ```{.python .input n=37} 142 | a - b # Subtraction 143 | ``` 144 | 145 | ```{.python .input n=38} 146 | np.subtract(a, b) # Subtraction 147 | ``` 148 | 149 | ```{.python .input n=39} 150 | b + a # Addition 151 | ``` 152 | 153 | ```{.python .input n=40} 154 | np.add(b, a) # Addition 155 | ``` 156 | 157 | ```{.python .input n=41} 158 | a / b # Division 159 | ``` 160 | 161 | ```{.python .input n=42} 162 | np.divide(a,b) # Division 163 | ``` 164 | 165 | ```{.python .input n=43} 166 | a * b # Multiplication 167 | ``` 168 | 169 | ```{.python .input n=44} 170 | np.multiply(a, b) # Multiplication 171 | ``` 172 | 173 | ```{.python .input n=45} 174 | np.exp(b) # Exponentiation 175 | ``` 176 | 177 | ```{.python .input n=46} 178 | np.sqrt(b) # Square root 179 | ``` 180 | 181 | ```{.python .input n=47} 182 | np.sin(a) # Sines of an array 183 | ``` 184 | 185 | ```{.python .input n=48} 186 | np.cos(b) # Element-wise cosine 187 | ``` 188 | 189 | ```{.python .input n=49} 190 | np.log(a) # Element-wise natural logarithm 191 | ``` 192 | 193 | ```{.python .input n=50} 194 | a.dot(b) # Dot product 195 | ``` 196 | 197 | ### Comparison 198 | 199 | ### Aggregate functions 200 | 201 | ```{.python .input n=51} 202 | a.sum() # Array-wise sum 203 | ``` 204 | 205 | ```{.python .input n=53} 206 | # a.min() # Array-wise minimum value 207 | ``` 208 | 209 | ```{.python .input n=57} 210 | c = np.array(([[1,2,3], [2,3,4]])) 211 | # c.max(axis=0) # Maximum value of an array row 212 | ``` 213 | 214 | ```{.python .input n=56} 215 | # c.cumsum(axis=1) # Cumulative sum of the elements 216 | ``` 217 | 218 | ```{.python .input n=58} 219 | a.mean() # Mean 220 | ``` 221 | 222 | ```{.python .input n=60} 223 | # b.median() # Median 224 | ``` 225 | 226 | ```{.python .input n=61} 227 | # a.corrcoef() # Correlation coefficient 228 | ``` 229 | 230 | ```{.python .input n=63} 231 | # np.std(b) # Standard deviation 232 | ``` 233 | 234 | ## Copying arrays 235 | 236 | ```{.python .input n=63} 237 | # a.view() # Create a view of the array with the same data 238 | ``` 239 | 240 | ```{.python .input n=63} 241 | np.copy(a) # Create a copy of the array 242 | ``` 243 | 244 | ```{.python .input n=63} 245 | a.copy() # Create a deep copy of the array 246 | ``` 247 | 248 | ## Sorting Arrays 249 | 250 | ```{.python .input n=63} 251 | # a.sort() # Sort an array 252 | ``` 253 | 254 | ```{.python .input n=63} 255 | # c.sort(axis=0) # Sort the elements of an array's axis 256 | ``` 257 | 258 | ## Subsetting, slicing, indexing 259 | 260 | ### Subsetting 261 | 262 | ```{.python .input n=63} 263 | a[2] # Select the element at the 2nd index 3 264 | ``` 265 | 266 | ```{.python .input n=63} 267 | c[0,1] # Select the element at row 1 column 2 268 | ``` 269 | 270 | ### Slicing 271 | 272 | ```{.python .input n=63} 273 | a[0:2] # Select items at index 0 and 1 274 | ``` 275 | 276 | ```{.python .input n=63} 277 | c[0:2,1] # Select items at rows 0 and 1 in column 1 278 | ``` 279 | 280 | ```{.python .input n=63} 281 | c[:1] # Select all items at row 0 282 | ``` 283 | 284 | ```{.python .input n=63} 285 | # c[1,...] # Same as [1,:,:] 286 | ``` 287 | 288 | ```{.python .input n=63} 289 | a[ : :-1] #Reversed array a array([3, 2, 1]) 290 | ``` 291 | 292 | ### Boolean Indexing 293 | 294 | ```{.python .input n=63} 295 | # a[a<2] # Select elements from a less than 2 296 | ``` 297 | 298 | ### Fancy indexing 299 | 300 | ```{.python .input n=63} 301 | c[[1,0,1,0], [0,1,2,0]] # Select elements (1,0),(0,1),(1,2) and (0,0) 302 | ``` 303 | 304 | ```{.python .input n=63} 305 | c[[1,0,1,0]][:,[0,1,2,0]] # Select a subset of the matrix’s rows 306 | ``` 307 | 308 | ## Array manipulation 309 | 310 | ### Transposing array 311 | 312 | ```{.python .input n=63} 313 | np.transpose(c) # Permute array dimensions 314 | ``` 315 | 316 | ```{.python .input n=63} 317 | c.T # Permute array dimensions 318 | ``` 319 | 320 | ### Changing array shape 321 | 322 | ```{.python .input n=63} 323 | # b.ravel() # Flatten the array 324 | ``` 325 | 326 | ```{.python .input n=63} 327 | # c.reshape(3,-2) # Reshape, but don’t change data 328 | ``` 329 | 330 | ### Adding and removing elements 331 | 332 | ```{.python .input n=63} 333 | # c.resize((6,2)) # Return a new array with shape (6, 2) 334 | ``` 335 | 336 | ```{.python .input n=63} 337 | # np.append(h,g) # Append items to an array 338 | ``` 339 | 340 | ```{.python .input n=63} 341 | # np.insert(a, 1, 5) # Insert items in an array 342 | ``` 343 | 344 | ```{.python .input n=63} 345 | # np.delete(a, [1]) # Delete items from an array 346 | ``` 347 | 348 | ### Combining arrays 349 | 350 | ```{.python .input n=63} 351 | np.concatenate((a,b),axis=0) # Concatenate arrays 352 | ``` 353 | 354 | ```{.python .input n=63} 355 | # np.vstack((a,b)) # Stack arrays vertically (row-wise) 356 | ``` 357 | 358 | ```{.python .input n=63} 359 | # np.r_[e,f] # Stack arrays vertically (row-wise) 360 | ``` 361 | 362 | ```{.python .input n=63} 363 | # np.hstack((e,f)) # Stack arrays horizontally (column-wise) 364 | ``` 365 | 366 | ```{.python .input n=63} 367 | # np.column_stack((a,d)) # Create stacked column-wise arrays 368 | ``` 369 | 370 | ```{.python .input n=63} 371 | # np.c_[a,d] # Create stacked column-wise arrays 372 | ``` 373 | 374 | ### Splitting arrays 375 | 376 | ```{.python .input n=63} 377 | # np.hsplit(a,3) # Split the array horizontally at the 3rd index 378 | ``` 379 | 380 | ```{.python .input n=63} 381 | # np.vsplit(c,2) # Split the array vertically at the 2nd index 382 | ``` 383 | 384 | ## Use GPUs 385 | 386 | Prerequisites: A GPU exists and GPU-enabled MXNet is installed. 387 | 388 | ```{.python .input} 389 | npx.num_gpus() # Query number of GPUs 390 | ``` 391 | 392 | ```{.python .input} 393 | npx.gpu(0), npx.gpu(1) # Context for the first and second GPUs 394 | ``` 395 | 396 | ```{.python .input} 397 | gpu_0 = npx.gpu(0) if npx.num_gpus() > 1 else npx.cpu() 398 | g0 = np.zeros((2,3), ctx=gpu_0) # Create array on GPU 0 399 | g0 400 | ``` 401 | 402 | ```{.python .input} 403 | gpu_1 = npx.gpu(1) if npx.num_gpus() > 2 else npx.cpu() 404 | g1 = np.random.uniform(size=(2,3), ctx=gpu_1) # Create array on GPU 1 405 | g1 406 | ``` 407 | 408 | ```{.python .input} 409 | # Copy to another GPU 410 | g1.copyto(gpu_0) 411 | ``` 412 | 413 | ```{.python .input} 414 | # Return itself if matching the context, otherwise copy 415 | g1.copyto(gpu_0), g1.copyto(gpu_0) 416 | ``` 417 | 418 | ```{.python .input} 419 | g1.context # Query the device an array is on 420 | ``` 421 | 422 | ```{.python .input} 423 | ## The computation is performed by the devices on which the input arrays are 424 | g0 + g1.copyto(gpu_0) 425 | ``` 426 | 427 | ## Auto differentiation 428 | 429 | ```{.python .input} 430 | a.attach_grad() # Allocate gradient for a variable 431 | a.grad # access the gradient 432 | ``` 433 | 434 | Compute the $\nabla_a b=\exp(2a)^T a$ 435 | 436 | ```{.python .input} 437 | from mxnet import autograd 438 | 439 | with autograd.record(): 440 | b = np.exp(2*a).dot(a) 441 | b.backward() 442 | a.grad 443 | ``` 444 | 445 | **Acknowledgement** 446 | 447 | Adapted from www.datacamp.com. 448 | -------------------------------------------------------------------------------- /guide/deepnumpy/deepnumpy-vs-numpy.md: -------------------------------------------------------------------------------- 1 | # Differences between NP on MXNet and NumPy 2 | :label:`deepnumpy_vs_numpy` 3 | 4 | This topic lists known differences between `mxnet.np` and `numpy`. With this quick reference, NumPy users can more easily adopt the MXNet NumPy-like API. 5 | 6 | ```{.python .input} 7 | import numpy as onp # o means original 8 | from mxnet import np, npx 9 | npx.set_np() # Configue MXNet to be NumPy-like 10 | ``` 11 | 12 | ## Missing operators 13 | 14 | Many, but not all, operators in NumPy are supported in MXNet. You can find the missing operators in :ref:`reference`. They're displayed in gray blocks instead of having links to their documents. 15 | 16 | In addition, an operator might not contain all arguments available in NumPy. For example, MXNet does not support stride. Check the operator document for more details. 17 | 18 | ## Extra functionalities 19 | 20 | The `mxnet.np` module aims to mimic NumPy. Most extra functionalities that enhance NumPy for deep learning use are available on other modules, such as `npx` for operators used in deep learning and `autograd` for automatic differentiation. The `np` module API is not complete. One notable change is GPU support. Creating routines accepts a `ctx` argument: 21 | 22 | ```{.python .input} 23 | gpu = npx.gpu() if npx.num_gpus() > 0 else npx.cpu() 24 | a = np.array(1, ctx=gpu) 25 | b = np.random.uniform(ctx=gpu) 26 | (a, b.context) 27 | ``` 28 | 29 | Methods to move data across devices. 30 | 31 | ```{.python .input} 32 | a.copyto(npx.cpu()), b.as_in_context(npx.cpu()) 33 | ``` 34 | 35 | ## Default data types 36 | 37 | NumPy uses 64-bit floating numbers or 64-bit integers by default. 38 | 39 | ```{.python .input} 40 | onp.array([1,2]).dtype, onp.array([1.2,2.3]).dtype 41 | ``` 42 | 43 | MXNet uses 32-bit floating points as the default date type. It's the default data type for deep learning. 44 | 45 | ```{.python .input} 46 | np.array([1,2]).dtype, np.array([1.2,2.3]).dtype 47 | ``` 48 | 49 | ## Scalars 50 | 51 | NumPy has classes for scalars, whose base class is 'numpy.generic'. The return values of selecting an element and reduce operators are scalars. 52 | 53 | ```{.python .input} 54 | a = onp.array([1,2]) 55 | type(a[0]), type(a.sum()) 56 | ``` 57 | 58 | A scalar is almost identical to a 0-rank tensor (TODO, there may be subtle difference), but it has a different class. You can check the data type with `isinstance` 59 | 60 | ```{.python .input} 61 | b = a[0] 62 | (b.ndim, b.size, isinstance(b, onp.generic), isinstance(b, onp.integer), 63 | isinstance(b, onp.int64), isinstance(b, onp.ndarray)) 64 | ``` 65 | 66 | MXNet returns 0-rank `ndarray` for scalars. (TODO, may consider to add scalar classes later.) 67 | 68 | ```{.python .input} 69 | a = np.array([1,2]) 70 | type(a[0]), type(a.sum()) 71 | ``` 72 | 73 | ```{.python .input} 74 | b = a[0] 75 | b.ndim, b.size, isinstance(b, np.ndarray) 76 | ``` 77 | 78 | ## Save 79 | 80 | The `save` method in `mxnet.np` saves data into a binary format that's not compatible with NumPy format. For example, it contains the device information. (TODO, needs more discussion here.) 81 | 82 | ```{.python .input} 83 | a = np.array(1, ctx=gpu) 84 | npx.save('a', a) 85 | npx.load('a') 86 | ``` 87 | 88 | ## Matplotlib 89 | 90 | Sometimes the MXNet ndarray cannot used by other libraries that accept NumPy input, for example matplotlib. The best practice is converting to NumPy with `asnumpy()`. 91 | 92 | ```{.python .input} 93 | %matplotlib inline 94 | import matplotlib.pyplot as plt 95 | 96 | plt.plot(np.array([1,2]).asnumpy()); 97 | ``` 98 | -------------------------------------------------------------------------------- /guide/deepnumpy/index.rst: -------------------------------------------------------------------------------- 1 | .. _deepnumpy_guide: 2 | 3 | What is NP on MXNet 4 | ============= 5 | 6 | NP on MXNet provides a NumPy-like interface with extensions 7 | for deep learning. It contains two modules, ``mxnet.np``, which is similar to 8 | NumPy, and ``mxnet.npx``, which contains extended operators that are useful for deep 9 | learning. 10 | 11 | If this is your first time using NP on MXNet, we recommend that you review the following topics in this section: 12 | 13 | :ref:`deepnumpy_cheat_sheet` - A quick overview 14 | :ref:`deepnumpy_vs_numpy` - Explains the the differences if you are familiar with NumPy 15 | -------------------------------------------------------------------------------- /guide/gluon/index.rst: -------------------------------------------------------------------------------- 1 | .. _gluon_guide: 2 | 3 | Gluon 4 | ====== 5 | 6 | TODO 7 | -------------------------------------------------------------------------------- /guide/index.rst: -------------------------------------------------------------------------------- 1 | Guide 2 | ====== 3 | 4 | 5 | 6 | .. toctree:: 7 | :maxdepth: 1 8 | 9 | crash-course/index 10 | deepnumpy/index 11 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | Apache MXNet (incubating) documents 2 | ==================================== 3 | 4 | :Date: |today| 5 | 6 | .. a warning, will remove it later 7 | 8 | .. container:: new-site 9 | 10 | .. note:: 11 | 12 | This is a preview of the Apache MXNet (incubating) new **NumPy-like** 13 | interface. It only contains a subset of documents. For more information, see the MXNet 14 | main website. 15 | 16 | .. raw:: html 17 | 18 | 19 | 20 | 21 | Installation 22 | --------------- 23 | 24 | .. Ignore prerequisites to make the index page concise, which will be shown at 25 | the install page 26 | 27 | .. raw:: html 28 | 29 | 30 | 31 | .. include:: install/install-include.rst 32 | 33 | 34 | Guidelines 35 | ------------- 36 | 37 | This guide section is intended as an introductory overview of MXNet modules 38 | for manipulating multi-dimensional arrays, loading data, constructing and 39 | training neural networks. 40 | 41 | .. container:: cards 42 | 43 | .. card:: 44 | :title: Crash Course 45 | :link: guide/crash-course/index.html 46 | 47 | A crash course to train and predict with a convolutional neural 48 | network. 49 | 50 | .. card:: 51 | :title: NP on MXNet 52 | :link: guide/deepnumpy/index.html 53 | 54 | Manipulate multi-dimensional arrays with the NumPy-like interface. 55 | 56 | .. card:: 57 | :title: Gluon 58 | :link: guide/gluon/index.html 59 | 60 | Load data, construct and train neural networks with Gluon. 61 | 62 | 63 | API Documents 64 | ------------------ 65 | 66 | This API section details functions, modules, and objects included in MXNet, 67 | describing what they are and what they do. The APIs are grouped into the 68 | following categories: 69 | 70 | .. container:: cards 71 | 72 | .. card:: 73 | :title: NP on MXNet 74 | :link: api/deepnumpy/index.html 75 | 76 | API documents for ``mxnet.np`` and ``mxnet.npx``. 77 | 78 | .. card:: 79 | :title: Gluon 80 | :link: api/gluon/index.html 81 | 82 | API documents for ``mxnet.gluon`` and other related modules. 83 | 84 | .. toctree:: 85 | :maxdepth: 1 86 | :hidden: 87 | 88 | guide/index 89 | api/index 90 | -------------------------------------------------------------------------------- /install/install-include.rst: -------------------------------------------------------------------------------- 1 | .. role:: title 2 | .. role:: opt 3 | :class: option 4 | .. role:: act 5 | :class: active option 6 | 7 | There is a preview pip package available. These packages 8 | haven't uploaded into Pypi server yet, so you need to select various options 9 | manually. 10 | 11 | .. container:: install 12 | 13 | .. container:: opt-group 14 | 15 | :title:`OS:` 16 | :opt:`Linux` 17 | :opt:`macOS` 18 | :opt:`Windows` 19 | 20 | .. container:: opt-group 21 | 22 | :title:`Backend:` 23 | :act:`Native` 24 | :opt:`CUDA` 25 | :opt:`MKL-DNN` 26 | :opt:`CUDA + MKL-DNN` 27 | 28 | .. raw:: html 29 | 30 |
Build-in backend for CPU.
31 |
Required to run on Nvidia GPUs.
32 |
Accelerate Intel CPU performance.
33 |
Enable both Nvidia CPUs and Inter CPU acceleration.
34 | 35 | .. admonition:: Prerequisites: 36 | 37 | - Requires `pip >= 9. `_ for Python 3. 38 | 39 | .. container:: cuda cuda-mkl-dnn 40 | 41 | - Requires `CUDA 42 | `_. 43 | Supported versions include 8.0, 9.0, and 9.2. 44 | - Hint: `cuDNN `_ is already 45 | included in the MXNet binary, so you don't need to install it. 46 | 47 | .. container:: mkl-dnn cuda-mkl-dnn 48 | 49 | - Hint: `MKL-DNN `_ is already included in 50 | the MXNet binary, so you don't need to install it. 51 | - For detailed information on MKL and MKL-DNN, 52 | refer to the `MKLDNN_README `_. 53 | 54 | .. admonition:: Command: 55 | 56 | .. container:: macos 57 | 58 | .. container:: native 59 | 60 | .. code-block:: bash 61 | 62 | # For python 3.7 63 | pip install https://apache-mxnet.s3-accelerate.amazonaws.com/dist/python/numpy/latest/mxnet-1.5.0-cp37-cp37m-macosx_10_11_x86_64.whl 64 | # For python 3.6 65 | pip install https://apache-mxnet.s3-accelerate.amazonaws.com/dist/python/numpy/latest/mxnet-1.5.0-cp36-cp36m-macosx_10_11_x86_64.whl 66 | 67 | .. container:: mkl-dnn 68 | 69 | .. code-block:: bash 70 | 71 | # For python 3.7 72 | pip install https://apache-mxnet.s3-accelerate.amazonaws.com/dist/python/numpy/latest/mxnet_mkl-1.5.0-cp37-cp37m-macosx_10_11_x86_64.whl 73 | # For python 3.6 74 | pip install https://apache-mxnet.s3-accelerate.amazonaws.com/dist/python/numpy/latest/mxnet_mkl-1.5.0-cp36-cp36m-macosx_10_11_x86_64.whl 75 | 76 | .. container:: linux 77 | 78 | .. container:: native 79 | 80 | .. code-block:: bash 81 | 82 | pip install https://apache-mxnet.s3-accelerate.amazonaws.com/dist/python/numpy/latest/mxnet-1.5.0-py2.py3-none-manylinux1_x86_64.whl 83 | 84 | .. container:: cuda 85 | 86 | .. code-block:: bash 87 | 88 | # You must have CUDA 10.0 is installed. 89 | pip install https://apache-mxnet.s3-accelerate.amazonaws.com/dist/python/numpy/latest/mxnet_cu100-1.5.0-py2.py3-none-manylinux1_x86_64.whl 90 | 91 | .. container:: cuda-mkl-dnn 92 | 93 | .. code-block:: bash 94 | 95 | # You must have CUDA 10.1 is installed. 96 | pip install https://apache-mxnet.s3-accelerate.amazonaws.com/dist/python/numpy/latest/mxnet_cu101mkl-1.5.0-py2.py3-none-manylinux1_x86_64.whl 97 | 98 | .. container:: windows 99 | 100 | Not supported. 101 | 102 | 103 | .. raw:: html 104 | 105 | 106 | -------------------------------------------------------------------------------- /static/autosummary/base.rst: -------------------------------------------------------------------------------- 1 | {{ objname | escape | underline}} 2 | 3 | .. currentmodule:: {{ module }} 4 | 5 | .. auto{{ objtype }}:: {{ objname }} 6 | -------------------------------------------------------------------------------- /static/autosummary/class.rst: -------------------------------------------------------------------------------- 1 | {{ objname | escape | underline}} 2 | 3 | .. currentmodule:: {{ module }} 4 | 5 | .. autoclass:: {{ objname }} 6 | -------------------------------------------------------------------------------- /static/autosummary/module.rst: -------------------------------------------------------------------------------- 1 | {{ fullname | escape | underline}} 2 | 3 | .. automodule:: {{ fullname }} 4 | 5 | {% block functions %} 6 | {% if functions %} 7 | .. rubric:: Functions 8 | 9 | .. autosummary:: 10 | {% for item in functions %} 11 | {{ item }} 12 | {%- endfor %} 13 | {% endif %} 14 | {% endblock %} 15 | 16 | {% block classes %} 17 | {% if classes %} 18 | .. rubric:: Classes 19 | 20 | .. autosummary:: 21 | {% for item in classes %} 22 | {{ item }} 23 | {%- endfor %} 24 | {% endif %} 25 | {% endblock %} 26 | 27 | {% block exceptions %} 28 | {% if exceptions %} 29 | .. rubric:: Exceptions 30 | 31 | .. autosummary:: 32 | {% for item in exceptions %} 33 | {{ item }} 34 | {%- endfor %} 35 | {% endif %} 36 | {% endblock %} 37 | -------------------------------------------------------------------------------- /static/disqus.js: -------------------------------------------------------------------------------- 1 | // var disqus_shortname; 2 | var disqus_identifier; 3 | 4 | var disqus_config = function () { 5 | var disqus_thread = $("#disqus_thread"); 6 | this.page.url = window.location.href; 7 | this.page.identifier = disqus_thread.data('disqusIdentifier'); 8 | }; 9 | 10 | (function() { // DON'T EDIT BELOW THIS LINE 11 | var d = document, s = d.createElement('script'); 12 | s.src = 'https://mxnet.disqus.com/embed.js'; 13 | s.setAttribute('data-timestamp', +new Date()); 14 | (d.head || d.body).appendChild(s); 15 | })(); 16 | -------------------------------------------------------------------------------- /static/install-options.js: -------------------------------------------------------------------------------- 1 | $(document).ready(function () { 2 | 3 | function label(lbl) { 4 | return $.trim(lbl.replace(/[ .]/g, '-').replace('+-', '').toLowerCase()); 5 | } 6 | 7 | // a hack: macos doesn't support cuda, so disable all cuda options when it 8 | // is selected. 9 | function disableCuda() { 10 | $('.install .option').each(function(){ 11 | if (label($(this).text()).indexOf("cuda") != -1) { 12 | $(this).addClass('disabled'); 13 | } 14 | }); 15 | } 16 | function enableCuda() { 17 | $('.install .option').each(function(){ 18 | if (label($(this).text()).indexOf("cuda") != -1) { 19 | $(this).removeClass('disabled'); 20 | } 21 | }); 22 | } 23 | 24 | // find the user os, and set the according option to active 25 | function setActiveOSButton() { 26 | var os = "linux" 27 | var agent = window.navigator.userAgent.toLowerCase(); 28 | if (agent.indexOf("win") != -1) { 29 | os = "windows" 30 | } else if (agent.indexOf("mac") != -1) { 31 | os = "macos" 32 | } 33 | if (os == "macos") { 34 | disableCuda(); 35 | } 36 | $('.install .option').each(function(){ 37 | if (label($(this).text()).indexOf(os) != -1) { 38 | $(this).addClass('active'); 39 | } 40 | }); 41 | } 42 | 43 | setActiveOSButton(); 44 | 45 | // apply theme 46 | function setTheme() { 47 | $('.opt-group .option').each(function(){ 48 | $(this).addClass('mdl-button mdl-js-button mdl-js-ripple-effect mdl-button--raised '); 49 | $(this).attr('id', label($(this).text())); 50 | }); 51 | $('.opt-group .active').each(function(){ 52 | $(this).addClass('mdl-button--colored'); 53 | }); 54 | } 55 | setTheme(); 56 | 57 | 58 | // show the command according to the active options 59 | function showCommand() { 60 | $('.opt-group .option').each(function(){ 61 | $('.'+label($(this).text())).hide(); 62 | // console.log('disable '+label($(this).text())); 63 | }); 64 | $('.opt-group .active').each(function(){ 65 | $('.'+label($(this).text())).show(); 66 | // console.log('enable '+label($(this).text())); 67 | }); 68 | } 69 | showCommand(); 70 | 71 | function setOptions() { 72 | var el = $(this); 73 | el.siblings().removeClass('active'); 74 | el.siblings().removeClass('mdl-button--colored'); 75 | el.addClass('active'); 76 | el.addClass('mdl-button--colored'); 77 | // console.log('enable'+el.text()) 78 | // console.log('disable'+el.siblings().text()) 79 | console.log($('.install #macos').hasClass('active') ) 80 | if ($('.install #macos').hasClass('active') == true) { 81 | disableCuda(); 82 | } else { 83 | enableCuda(); 84 | } 85 | showCommand(); 86 | } 87 | 88 | $('.opt-group').on('click', '.option', setOptions); 89 | 90 | }); 91 | -------------------------------------------------------------------------------- /static/mxnet-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mli/deepnumpy-doc/044c9c4e4c8e7e13a20528611e2d36e26f71a20b/static/mxnet-icon.png -------------------------------------------------------------------------------- /static/mxnet-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | -------------------------------------------------------------------------------- /static/mxnet.css: -------------------------------------------------------------------------------- 1 | body { 2 | font-family: 'Roboto', sans-serif; 3 | } 4 | 5 | p { 6 | font-size: 16px; 7 | /* font-weight: 400; */ 8 | line-height: 1.5em; 9 | margin: 16px 0; 10 | } 11 | 12 | .sidebar { 13 | float: right; 14 | display: block; 15 | width: 30%; 16 | padding: 0 20px; 17 | margin: 0 20px; 18 | background-color: #eee; 19 | border-radius: 8px; 20 | 21 | } 22 | 23 | @media (max-width: 500px) { 24 | .sidebar { 25 | float: none; 26 | width: 100%; 27 | padding: 0 10px; 28 | margin: 0 10px; 29 | width: 80%; 30 | } 31 | } 32 | 33 | .sidebar .sidebar-title { 34 | text-align: center; 35 | display: block; 36 | margin-bottom: 0px; 37 | display: none; 38 | } 39 | 40 | .align-center { 41 | text-align: center; 42 | display: block; 43 | /* float: right; */ 44 | margin: auto; 45 | } 46 | 47 | /* API section */ 48 | 49 | .mx-api .section .hidden-section { 50 | display: none; 51 | } 52 | 53 | .mx-api h3.mdl-color-text--primary { 54 | /* display: none; */ 55 | 56 | /* border-top-style: solid; */ 57 | /* border-color: #ccc; */ 58 | /* border-top-width: 1px; */ 59 | padding: 1em 0 0 0; 60 | margin: 2em 0 0 0; 61 | height: 0; 62 | } 63 | 64 | /* .section .viewcode-link { */ 65 | /* padding-left: 2em; */ 66 | /* font-size: 80%; */ 67 | /* } */ 68 | 69 | .section .class dt { 70 | padding-bottom: 1em; 71 | } 72 | 73 | .install { 74 | max-width: 800px; 75 | } 76 | .install .title { 77 | display: inline-block; 78 | min-width: 100px; 79 | text-transform: uppercase; 80 | font-size: 90%; 81 | color: #555; 82 | } 83 | 84 | .install .option { 85 | margin: 5px; 86 | } 87 | 88 | @media (max-width: 650px) { 89 | .install .option, .install .title { 90 | width: 90%; 91 | } 92 | .install .title { 93 | margin-top: 1em; 94 | } 95 | --------------------------------------------------------------------------------