diff options
Diffstat (limited to 'doc')
22 files changed, 347 insertions, 223 deletions
diff --git a/doc/release/upcoming_changes/15802.expired.rst b/doc/release/upcoming_changes/15802.expired.rst new file mode 100644 index 000000000..1a1b373a7 --- /dev/null +++ b/doc/release/upcoming_changes/15802.expired.rst @@ -0,0 +1,9 @@ +`numpy.insert` and `numpy.delete` can no longer be passed an axis on 0d arrays +------------------------------------------------------------------------------ +This concludes a deprecation from 1.9, where when an ``axis`` argument was +passed to a call to `~numpy.insert` and `~numpy.delete` on a 0d array, the +``axis`` and ``obj`` argument and indices would be completely ignored. +In these cases, ``insert(arr, "nonsense", 42, axis=0)`` would actually overwrite the +entire array, while ``delete(arr, "nonsense", axis=0)`` would be ``arr.copy()`` + +Now passing ``axis`` on a 0d array raises `~numpy.AxisError`. diff --git a/doc/release/upcoming_changes/15815.expired.rst b/doc/release/upcoming_changes/15815.expired.rst new file mode 100644 index 000000000..b853cc9e5 --- /dev/null +++ b/doc/release/upcoming_changes/15815.expired.rst @@ -0,0 +1,6 @@ +`numpy.delete` no longer casts boolean indices to integers +---------------------------------------------------------- +This concludes a deprecation from 1.8, where ``np.delete`` would cast boolean +arrays and scalars passed as an index argument into integer indices. The +behavior now is to treat boolean arrays as a mask, and to raise an error +on boolean scalars. diff --git a/doc/release/upcoming_changes/15870.new_feature.rst b/doc/release/upcoming_changes/15870.new_feature.rst new file mode 100644 index 000000000..9da3f1535 --- /dev/null +++ b/doc/release/upcoming_changes/15870.new_feature.rst @@ -0,0 +1,5 @@ +``keepdims`` parameter for `numpy.count_nonzero` +------------------------------------------------ +The parameter ``keepdims`` was added to `numpy.count_nonzero`. The +parameter has the same meaning as it does in reduction functions such +as `numpy.sum` or `numpy.mean`. diff --git a/doc/release/upcoming_changes/15882.compatibility.rst b/doc/release/upcoming_changes/15882.compatibility.rst new file mode 100644 index 000000000..5790c081c --- /dev/null +++ b/doc/release/upcoming_changes/15882.compatibility.rst @@ -0,0 +1,5 @@ +The ``numpy.ndarray`` constructor no longer interprets ``strides=()`` as ``strides=None`` +----------------------------------------------------------------------------------------- +The former has changed to have the expected meaning of setting +`numpy.ndarray.strides` to ``()``, while the latter continues to result in +strides being chosen automatically. diff --git a/doc/source/_templates/indexcontent.html b/doc/source/_templates/indexcontent.html index 294d39233..d77c5a85e 100644 --- a/doc/source/_templates/indexcontent.html +++ b/doc/source/_templates/indexcontent.html @@ -1,35 +1,43 @@ {% extends "defindex.html" %} {% block tables %} - <p><strong>Parts of the documentation:</strong></p> - <table class="contentstable" align="center"><tr> +<p><strong>For users:</strong></p> +<table class="contentstable" align="center"><tr> <td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("user/index") }}">NumPy User Guide</a><br/> - <span class="linkdescr">start here</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">NumPy Reference</a><br/> - <span class="linkdescr">reference documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("benchmarking") }}">Benchmarking</a><br/> - <span class="linkdescr">benchmarking NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/setting-up") }}">Setting Up</a><br/> + <span class="linkdescr">Learn about what NumPy is and how to install it</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/quickstart") }}">Quickstart Tutorial</a><br/> + <span class="linkdescr">Aimed at domain experts or people migrating to NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/absolute_beginners") }}">Absolute Beginners Tutorial</a><br/> + <span class="linkdescr">Start here for an overview of NumPy features and syntax</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/tutorials_index") }}">Tutorials</a><br/> + <span class="linkdescr">Learn about concepts and submodules</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/howtos_index") }}">How Tos</a><br/> + <span class="linkdescr">How to do common tasks with NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">NumPy API Reference</a><br/> + <span class="linkdescr">Automatically generated reference documentation</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("user/explanations_index") }}">Explanations</a><br/> + <span class="linkdescr">In depth explanation of concepts, best practices and techniques</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("f2py/index") }}">F2Py Guide</a><br/> - <span class="linkdescr">f2py documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("dev/index") }}">NumPy Developer Guide</a><br/> - <span class="linkdescr">contributing to NumPy</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("docs/index") }}">Building and Extending the Documentation</a><br/> - <span class="linkdescr">about this documentation</span></p> - </td></tr> - </table> + <span class="linkdescr">Documentation for the f2py module (Fortran extensions for Python)</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br/> + <span class="linkdescr">List of the most important terms</span></p> + </td></tr> +</table> - <p><strong>Indices and tables:</strong></p> - <table class="contentstable" align="center"><tr> +<p><strong>For developers/contributors:</strong></p> +<table class="contentstable" align="center"><tr> <td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/> - <span class="linkdescr">all functions, classes, terms</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br/> - <span class="linkdescr">the most important terms explained</span></p> - </td><td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/> - <span class="linkdescr">search this documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br/> - <span class="linkdescr">lists all sections and subsections</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("dev/index") }}">NumPy Contributor Guide</a><br/> + <span class="linkdescr">Contributing to NumPy</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("dev/underthehood") }}">Under-the-hood docs</a><br/> + <span class="linkdescr">Specialized, in-depth documentation</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("docs/index") }}">Building and Extending the Documentation</a><br/> + <span class="linkdescr">How to contribute to this documentation (user and API)</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("docs/howto_document") }}">The numpydoc docstring guide</a><br/> + <span class="linkdescr">How to write docstrings in the numpydoc format</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("benchmarking") }}">Benchmarking</a><br/> + <span class="linkdescr">benchmarking NumPy</span></p> + <p class="biglink"><a class="biglink" href="https://www.numpy.org/neps/index.html">NumPy Enhancement Proposals</a><br/> </td></tr> </table> @@ -37,11 +45,9 @@ <table class="contentstable" align="center"><tr> <td width="50%"> <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">Reporting bugs</a></p> - <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">About NumPy</a></p> - <p class="biglink"><a class="biglink" href="https://www.numpy.org/neps/index.html"> - NumPy Enhancement Proposals</a><br/> - </td><td width="50%"> <p class="biglink"><a class="biglink" href="{{ pathto("release") }}">Release Notes</a></p> + </td><td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">About NumPy</a></p> <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">License of NumPy</a></p> </td></tr> </table> @@ -56,7 +62,7 @@ </p> <p> The preferred way to update the documentation is by submitting a pull - request on Github (see the <a href="{{ pathto("docs/index") }}">Documentation Index</a>. + request on Github (see the <a href="{{ pathto("docs/index") }}">Documentation Index</a>). Please help us to further improve the NumPy documentation! </p> {% endblock %} diff --git a/doc/source/contents.rst b/doc/source/contents.rst index 019dcc71d..c89153aa7 100644 --- a/doc/source/contents.rst +++ b/doc/source/contents.rst @@ -1,16 +1,27 @@ +.. _manual: + ##################### NumPy manual contents ##################### .. toctree:: - user/index + user/setting-up + user/quickstart + user/absolute_beginners + user/tutorials_index + user/howtos_index reference/index + user/explanations_index f2py/index + glossary dev/index + dev/underthehood docs/index + docs/howto_document + benchmarking + bugs release about - bugs license - glossary + diff --git a/doc/source/dev/underthehood.rst b/doc/source/dev/underthehood.rst new file mode 100644 index 000000000..4dae48689 --- /dev/null +++ b/doc/source/dev/underthehood.rst @@ -0,0 +1,7 @@ +.. _underthehood: + +=========================================== +Under-the-hood Documentation for developers +=========================================== + +To be completed. diff --git a/doc/source/f2py/getting-started.rst b/doc/source/f2py/f2py.getting-started.rst index 27ddbb005..27ddbb005 100644 --- a/doc/source/f2py/getting-started.rst +++ b/doc/source/f2py/f2py.getting-started.rst diff --git a/doc/source/f2py/index.rst b/doc/source/f2py/index.rst index d6773a76f..492139651 100644 --- a/doc/source/f2py/index.rst +++ b/doc/source/f2py/index.rst @@ -19,7 +19,7 @@ from Python. .. toctree:: :maxdepth: 2 - getting-started + f2py.getting-started signature-file python-usage usage diff --git a/doc/source/reference/arrays.nditer.cython.rst b/doc/source/reference/arrays.nditer.cython.rst new file mode 100644 index 000000000..2cc7763ed --- /dev/null +++ b/doc/source/reference/arrays.nditer.cython.rst @@ -0,0 +1,147 @@ +Putting the Inner Loop in Cython +================================ + +Those who want really good performance out of their low level operations +should strongly consider directly using the iteration API provided +in C, but for those who are not comfortable with C or C++, Cython +is a good middle ground with reasonable performance tradeoffs. For +the :class:`nditer` object, this means letting the iterator take care +of broadcasting, dtype conversion, and buffering, while giving the inner +loop to Cython. + +For our example, we'll create a sum of squares function. To start, +let's implement this function in straightforward Python. We want to +support an 'axis' parameter similar to the numpy :func:`sum` function, +so we will need to construct a list for the `op_axes` parameter. +Here's how this looks. + +.. admonition:: Example + + >>> def axis_to_axeslist(axis, ndim): + ... if axis is None: + ... return [-1] * ndim + ... else: + ... if type(axis) is not tuple: + ... axis = (axis,) + ... axeslist = [1] * ndim + ... for i in axis: + ... axeslist[i] = -1 + ... ax = 0 + ... for i in range(ndim): + ... if axeslist[i] != -1: + ... axeslist[i] = ax + ... ax += 1 + ... return axeslist + ... + >>> def sum_squares_py(arr, axis=None, out=None): + ... axeslist = axis_to_axeslist(axis, arr.ndim) + ... it = np.nditer([arr, out], flags=['reduce_ok', + ... 'buffered', 'delay_bufalloc'], + ... op_flags=[['readonly'], ['readwrite', 'allocate']], + ... op_axes=[None, axeslist], + ... op_dtypes=['float64', 'float64']) + ... with it: + ... it.operands[1][...] = 0 + ... it.reset() + ... for x, y in it: + ... y[...] += x*x + ... return it.operands[1] + ... + >>> a = np.arange(6).reshape(2,3) + >>> sum_squares_py(a) + array(55.0) + >>> sum_squares_py(a, axis=-1) + array([ 5., 50.]) + +To Cython-ize this function, we replace the inner loop (y[...] += x*x) with +Cython code that's specialized for the float64 dtype. With the +'external_loop' flag enabled, the arrays provided to the inner loop will +always be one-dimensional, so very little checking needs to be done. + +Here's the listing of sum_squares.pyx:: + + import numpy as np + cimport numpy as np + cimport cython + + def axis_to_axeslist(axis, ndim): + if axis is None: + return [-1] * ndim + else: + if type(axis) is not tuple: + axis = (axis,) + axeslist = [1] * ndim + for i in axis: + axeslist[i] = -1 + ax = 0 + for i in range(ndim): + if axeslist[i] != -1: + axeslist[i] = ax + ax += 1 + return axeslist + + @cython.boundscheck(False) + def sum_squares_cy(arr, axis=None, out=None): + cdef np.ndarray[double] x + cdef np.ndarray[double] y + cdef int size + cdef double value + + axeslist = axis_to_axeslist(axis, arr.ndim) + it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop', + 'buffered', 'delay_bufalloc'], + op_flags=[['readonly'], ['readwrite', 'allocate']], + op_axes=[None, axeslist], + op_dtypes=['float64', 'float64']) + with it: + it.operands[1][...] = 0 + it.reset() + for xarr, yarr in it: + x = xarr + y = yarr + size = x.shape[0] + for i in range(size): + value = x[i] + y[i] = y[i] + value * value + return it.operands[1] + +On this machine, building the .pyx file into a module looked like the +following, but you may have to find some Cython tutorials to tell you +the specifics for your system configuration.:: + + $ cython sum_squares.pyx + $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -I/usr/include/python2.7 -fno-strict-aliasing -o sum_squares.so sum_squares.c + +Running this from the Python interpreter produces the same answers +as our native Python/NumPy code did. + +.. admonition:: Example + + >>> from sum_squares import sum_squares_cy + >>> a = np.arange(6).reshape(2,3) + >>> sum_squares_cy(a) + array(55.0) + >>> sum_squares_cy(a, axis=-1) + array([ 5., 50.]) + +Doing a little timing in IPython shows that the reduced overhead and +memory allocation of the Cython inner loop is providing a very nice +speedup over both the straightforward Python code and an expression +using NumPy's built-in sum function.:: + + >>> a = np.random.rand(1000,1000) + + >>> timeit sum_squares_py(a, axis=-1) + 10 loops, best of 3: 37.1 ms per loop + + >>> timeit np.sum(a*a, axis=-1) + 10 loops, best of 3: 20.9 ms per loop + + >>> timeit sum_squares_cy(a, axis=-1) + 100 loops, best of 3: 11.8 ms per loop + + >>> np.all(sum_squares_cy(a, axis=-1) == np.sum(a*a, axis=-1)) + True + + >>> np.all(sum_squares_py(a, axis=-1) == np.sum(a*a, axis=-1)) + True diff --git a/doc/source/reference/arrays.nditer.rst b/doc/source/reference/arrays.nditer.rst index 7dab09a71..2db12a408 100644 --- a/doc/source/reference/arrays.nditer.rst +++ b/doc/source/reference/arrays.nditer.rst @@ -1,5 +1,9 @@ .. currentmodule:: numpy +.. for doctests + The last section on Cython is 'included' at the end of this file. The tests + for that section are disabled. + .. _arrays.nditer: ********************* @@ -218,21 +222,21 @@ produce identical results to the ones in the previous section. >>> it = np.nditer(a, flags=['f_index']) >>> while not it.finished: ... print("%d <%d>" % (it[0], it.index), end=' ') - ... it.iternext() + ... is_not_finished = it.iternext() ... 0 <0> 1 <2> 2 <4> 3 <1> 4 <3> 5 <5> >>> it = np.nditer(a, flags=['multi_index']) >>> while not it.finished: ... print("%d <%s>" % (it[0], it.multi_index), end=' ') - ... it.iternext() + ... is_not_finished = it.iternext() ... 0 <(0, 0)> 1 <(0, 1)> 2 <(0, 2)> 3 <(1, 0)> 4 <(1, 1)> 5 <(1, 2)> >>> with np.nditer(a, flags=['multi_index'], op_flags=['writeonly']) as it: ... while not it.finished: ... it[0] = it.multi_index[1] - it.multi_index[0] - ... it.iternext() + ... is_not_finished = it.iternext() ... >>> a array([[ 0, 1, 2], @@ -316,12 +320,13 @@ specified as an iterator flag. ... op_dtypes=['complex128']): ... print(np.sqrt(x), end=' ') ... - 1.73205080757j 1.41421356237j 1j 0j (1+0j) (1.41421356237+0j) + 1.7320508075688772j 1.4142135623730951j 1j 0j (1+0j) (1.4142135623730951+0j) >>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['complex128']): ... print(np.sqrt(x), end=' ') ... - 1.73205080757j 1.41421356237j 1j 0j (1+0j) (1.41421356237+0j) + 1.7320508075688772j 1.4142135623730951j 1j 0j (1+0j) (1.4142135623730951+0j) + The iterator uses NumPy's casting rules to determine whether a specific conversion is permitted. By default, it enforces 'safe' casting. This means, @@ -405,8 +410,8 @@ which includes the input shapes to help diagnose the problem. ... print("%d:%d" % (x,y), end=' ') ... Traceback (most recent call last): - File "<stdin>", line 1, in <module> - ValueError: operands could not be broadcast together with shapes (2) (2,3) + ... + ValueError: operands could not be broadcast together with shapes (2,) (2,3) Iterator-Allocated Output Arrays -------------------------------- @@ -482,9 +487,9 @@ reasons. >>> square(np.arange(6).reshape(2,3), out=b) Traceback (most recent call last): - File "<stdin>", line 1, in <module> - File "<stdin>", line 4, in square - ValueError: non-broadcastable output operand with shape (3) doesn't match the broadcast shape (2,3) + ... + ValueError: non-broadcastable output operand with shape (3,) doesn't + match the broadcast shape (2,3) Outer Product Iteration ----------------------- @@ -550,7 +555,7 @@ For a simple example, consider taking the sum of all elements in an array. >>> a = np.arange(24).reshape(2,3,4) >>> b = np.array(0) - >>> with np.nditer([a, b], flags=['reduce_ok', 'external_loop'], + >>> with np.nditer([a, b], flags=['reduce_ok'], ... op_flags=[['readonly'], ['readwrite']]) as it: ... for x,y in it: ... y[...] += x @@ -568,7 +573,7 @@ sums along the last axis of `a`. .. admonition:: Example >>> a = np.arange(24).reshape(2,3,4) - >>> it = np.nditer([a, None], flags=['reduce_ok', 'external_loop'], + >>> it = np.nditer([a, None], flags=['reduce_ok'], ... op_flags=[['readonly'], ['readwrite', 'allocate']], ... op_axes=[None, [0,1,-1]]) >>> with it: @@ -602,7 +607,7 @@ buffering. .. admonition:: Example >>> a = np.arange(24).reshape(2,3,4) - >>> it = np.nditer([a, None], flags=['reduce_ok', 'external_loop', + >>> it = np.nditer([a, None], flags=['reduce_ok', ... 'buffered', 'delay_bufalloc'], ... op_flags=[['readonly'], ['readwrite', 'allocate']], ... op_axes=[None, [0,1,-1]]) @@ -617,150 +622,8 @@ buffering. array([[ 6, 22, 38], [54, 70, 86]]) -Putting the Inner Loop in Cython -================================ - -Those who want really good performance out of their low level operations -should strongly consider directly using the iteration API provided -in C, but for those who are not comfortable with C or C++, Cython -is a good middle ground with reasonable performance tradeoffs. For -the :class:`nditer` object, this means letting the iterator take care -of broadcasting, dtype conversion, and buffering, while giving the inner -loop to Cython. - -For our example, we'll create a sum of squares function. To start, -let's implement this function in straightforward Python. We want to -support an 'axis' parameter similar to the numpy :func:`sum` function, -so we will need to construct a list for the `op_axes` parameter. -Here's how this looks. - -.. admonition:: Example - - >>> def axis_to_axeslist(axis, ndim): - ... if axis is None: - ... return [-1] * ndim - ... else: - ... if type(axis) is not tuple: - ... axis = (axis,) - ... axeslist = [1] * ndim - ... for i in axis: - ... axeslist[i] = -1 - ... ax = 0 - ... for i in range(ndim): - ... if axeslist[i] != -1: - ... axeslist[i] = ax - ... ax += 1 - ... return axeslist - ... - >>> def sum_squares_py(arr, axis=None, out=None): - ... axeslist = axis_to_axeslist(axis, arr.ndim) - ... it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop', - ... 'buffered', 'delay_bufalloc'], - ... op_flags=[['readonly'], ['readwrite', 'allocate']], - ... op_axes=[None, axeslist], - ... op_dtypes=['float64', 'float64']) - ... with it: - ... it.operands[1][...] = 0 - ... it.reset() - ... for x, y in it: - ... y[...] += x*x - ... return it.operands[1] - ... - >>> a = np.arange(6).reshape(2,3) - >>> sum_squares_py(a) - array(55.0) - >>> sum_squares_py(a, axis=-1) - array([ 5., 50.]) - -To Cython-ize this function, we replace the inner loop (y[...] += x*x) with -Cython code that's specialized for the float64 dtype. With the -'external_loop' flag enabled, the arrays provided to the inner loop will -always be one-dimensional, so very little checking needs to be done. - -Here's the listing of sum_squares.pyx:: - - import numpy as np - cimport numpy as np - cimport cython - - def axis_to_axeslist(axis, ndim): - if axis is None: - return [-1] * ndim - else: - if type(axis) is not tuple: - axis = (axis,) - axeslist = [1] * ndim - for i in axis: - axeslist[i] = -1 - ax = 0 - for i in range(ndim): - if axeslist[i] != -1: - axeslist[i] = ax - ax += 1 - return axeslist - - @cython.boundscheck(False) - def sum_squares_cy(arr, axis=None, out=None): - cdef np.ndarray[double] x - cdef np.ndarray[double] y - cdef int size - cdef double value - - axeslist = axis_to_axeslist(axis, arr.ndim) - it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop', - 'buffered', 'delay_bufalloc'], - op_flags=[['readonly'], ['readwrite', 'allocate']], - op_axes=[None, axeslist], - op_dtypes=['float64', 'float64']) - with it: - it.operands[1][...] = 0 - it.reset() - for xarr, yarr in it: - x = xarr - y = yarr - size = x.shape[0] - for i in range(size): - value = x[i] - y[i] = y[i] + value * value - return it.operands[1] - -On this machine, building the .pyx file into a module looked like the -following, but you may have to find some Cython tutorials to tell you -the specifics for your system configuration.:: - - $ cython sum_squares.pyx - $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -I/usr/include/python2.7 -fno-strict-aliasing -o sum_squares.so sum_squares.c - -Running this from the Python interpreter produces the same answers -as our native Python/NumPy code did. - -.. admonition:: Example - - >>> from sum_squares import sum_squares_cy - >>> a = np.arange(6).reshape(2,3) - >>> sum_squares_cy(a) - array(55.0) - >>> sum_squares_cy(a, axis=-1) - array([ 5., 50.]) - -Doing a little timing in IPython shows that the reduced overhead and -memory allocation of the Cython inner loop is providing a very nice -speedup over both the straightforward Python code and an expression -using NumPy's built-in sum function.:: - - >>> a = np.random.rand(1000,1000) - - >>> timeit sum_squares_py(a, axis=-1) - 10 loops, best of 3: 37.1 ms per loop - - >>> timeit np.sum(a*a, axis=-1) - 10 loops, best of 3: 20.9 ms per loop - - >>> timeit sum_squares_cy(a, axis=-1) - 100 loops, best of 3: 11.8 ms per loop - - >>> np.all(sum_squares_cy(a, axis=-1) == np.sum(a*a, axis=-1)) - True +.. for doctests + Include Cython section separately. Those tests are skipped entirely via an + entry in RST_SKIPLIST - >>> np.all(sum_squares_py(a, axis=-1) == np.sum(a*a, axis=-1)) - True +.. include:: arrays.nditer.cython.rst diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst index 46af1b45b..22b15fc57 100644 --- a/doc/source/reference/c-api/array.rst +++ b/doc/source/reference/c-api/array.rst @@ -834,7 +834,7 @@ General check of Python Type .. c:function:: PyArray_IsPythonScalar(op) Evaluates true if *op* is a builtin Python scalar object (int, - float, complex, str, unicode, long, bool). + float, complex, bytes, str, long, bool). .. c:function:: PyArray_IsAnyScalar(op) diff --git a/doc/source/reference/c-api/index.rst b/doc/source/reference/c-api/index.rst index 56fe8e473..bb1ed154e 100644 --- a/doc/source/reference/c-api/index.rst +++ b/doc/source/reference/c-api/index.rst @@ -21,7 +21,7 @@ experience at first. Be assured that the task becomes easier with practice, and you may be surprised at how simple the C-code can be to understand. Even if you don't think you can write C-code from scratch, it is much easier to understand and modify already-written source code -then create it *de novo*. +than create it *de novo*. Python extensions are especially straightforward to understand because they all have a very similar structure. Admittedly, NumPy is not a diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 6742d605a..d042a1849 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -12,7 +12,7 @@ NumPy Reference This reference manual details functions, modules, and objects included in NumPy, describing what they are and what they do. -For learning how to use NumPy, see also :ref:`user`. +For learning how to use NumPy, see the :ref:`complete documentation <manual>`. .. toctree:: diff --git a/doc/source/reference/maskedarray.baseclass.rst b/doc/source/reference/maskedarray.baseclass.rst index 9864f21ea..57bbaa8f8 100644 --- a/doc/source/reference/maskedarray.baseclass.rst +++ b/doc/source/reference/maskedarray.baseclass.rst @@ -125,7 +125,6 @@ Conversion MaskedArray.__float__ MaskedArray.__int__ - MaskedArray.__long__ MaskedArray.view MaskedArray.astype diff --git a/doc/source/user/absolute_beginners.rst b/doc/source/user/absolute_beginners.rst index 021f49bcb..ad2cd2d80 100644 --- a/doc/source/user/absolute_beginners.rst +++ b/doc/source/user/absolute_beginners.rst @@ -1576,6 +1576,10 @@ If you created this array "a" :: ... [ 0.76989341, 0.81299683, -0.95068423, 0.11769564], ... [ 0.20484034, 0.34784527, 1.96979195, 0.51992837]]) +.. for doctests + The continuous integration truncates dataframe display without this setting. + >>> pd.set_option('max_columns', 10) + You could create a Pandas dataframe :: >>> df = pd.DataFrame(a) diff --git a/doc/source/user/explanations_index.rst b/doc/source/user/explanations_index.rst new file mode 100644 index 000000000..f515e36b1 --- /dev/null +++ b/doc/source/user/explanations_index.rst @@ -0,0 +1,14 @@ +.. _explanations: + +################ +Explanations +################ + +These documents are intended to explain in detail the concepts and techniques +used in NumPy. For the reference documentation of the functions and classes +contained in the package, see the :ref:`API reference <reference>`. + +.. toctree:: + :maxdepth: 1 + + basics.broadcasting diff --git a/doc/source/user/howtos_index.rst b/doc/source/user/howtos_index.rst new file mode 100644 index 000000000..c052286b9 --- /dev/null +++ b/doc/source/user/howtos_index.rst @@ -0,0 +1,14 @@ +.. _howtos: + +################ +NumPy How Tos +################ + +These documents are intended as recipes to common tasks using NumPy. For +detailed reference documentation of the functions and classes contained in +the package, see the :ref:`API reference <reference>`. + +.. toctree:: + :maxdepth: 1 + + ionumpy diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst deleted file mode 100644 index d506a5a98..000000000 --- a/doc/source/user/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _user: - -################ -NumPy User Guide -################ - -This guide is intended as an introductory overview of NumPy and -explains how to install and make use of the most important features of -NumPy. For detailed reference documentation of the functions and -classes contained in the package, see the :ref:`reference`. - -.. toctree:: - :maxdepth: 1 - - setting-up - quickstart - absolute_beginners - basics - misc - numpy-for-matlab-users - tutorial-svd - building - c-info diff --git a/doc/source/user/ionumpy.rst b/doc/source/user/ionumpy.rst new file mode 100644 index 000000000..a31720322 --- /dev/null +++ b/doc/source/user/ionumpy.rst @@ -0,0 +1,20 @@ +================================================ +How to read and write data using NumPy +================================================ + +.. currentmodule:: numpy + +.. testsetup:: + + import numpy as np + np.random.seed(1) + +**Objectives** + +- Writing NumPy arrays to files +- Reading NumPy arrays from files +- Dealing with encoding and dtype issues + +**Content** + +To be completed. diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index 05a247f8a..bea07debf 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -21,6 +21,24 @@ If you wish to work the examples in this tutorial, you must also have some software installed on your computer. Please see https://scipy.org/install.html for instructions. +**Learner profile** + +This tutorial is intended as a quick overview of +algebra and arrays in NumPy and want to understand how n-dimensional +(:math:`n>=2`) arrays are represented and can be manipulated. In particular, if +you don't know how to apply common functions to n-dimensional arrays (without +using for-loops), or if you want to understand axis and shape properties for +n-dimensional arrays, this tutorial might be of help. + +**Learning Objectives** + +After this tutorial, you should be able to: + +- Understand the difference between one-, two- and n-dimensional arrays in + NumPy; +- Understand how to apply some linear algebra operations to n-dimensional + arrays without using for-loops; +- Understand axis and shape properties for n-dimensional arrays. .. _quickstart.the-basics: @@ -129,8 +147,8 @@ rather than providing a single sequence as an argument. >>> a = np.array(1,2,3,4) # WRONG Traceback (most recent call last): - ... - ValueError: only 2 non-keyword arguments accepted + ... + TypeError: array() takes from 1 to 2 positional arguments but 4 were given >>> a = np.array([1,2,3,4]) # RIGHT ``array`` transforms sequences of sequences into two-dimensional arrays, diff --git a/doc/source/user/tutorials_index.rst b/doc/source/user/tutorials_index.rst new file mode 100644 index 000000000..c5e859fad --- /dev/null +++ b/doc/source/user/tutorials_index.rst @@ -0,0 +1,19 @@ +.. _tutorials: + +################ +NumPy Tutorials +################ + +These documents are intended as an introductory overview of NumPy and its +features. For detailed reference documentation of the functions and +classes contained in the package, see the :ref:`API reference <reference>`. + +.. toctree:: + :maxdepth: 1 + + basics + misc + numpy-for-matlab-users + tutorial-svd + building + c-info |