diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/_templates/indexcontent.html | 68 | ||||
| -rw-r--r-- | doc/source/contents.rst | 17 | ||||
| -rw-r--r-- | doc/source/dev/index.rst | 17 | ||||
| -rw-r--r-- | doc/source/dev/underthehood.rst | 7 | ||||
| -rw-r--r-- | doc/source/f2py/f2py.getting-started.rst (renamed from doc/source/f2py/getting-started.rst) | 0 | ||||
| -rw-r--r-- | doc/source/f2py/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/arrays.nditer.cython.rst | 147 | ||||
| -rw-r--r-- | doc/source/reference/arrays.nditer.rst | 181 | ||||
| -rw-r--r-- | doc/source/reference/c-api/array.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/c-api/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/maskedarray.baseclass.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/routines.ma.rst | 1 | ||||
| -rw-r--r-- | doc/source/user/absolute_beginners.rst | 4 | ||||
| -rw-r--r-- | doc/source/user/explanations_index.rst | 14 | ||||
| -rw-r--r-- | doc/source/user/howtos_index.rst | 14 | ||||
| -rw-r--r-- | doc/source/user/index.rst | 23 | ||||
| -rw-r--r-- | doc/source/user/ionumpy.rst | 20 | ||||
| -rw-r--r-- | doc/source/user/quickstart.rst | 22 | ||||
| -rw-r--r-- | doc/source/user/tutorials_index.rst | 19 |
20 files changed, 331 insertions, 232 deletions
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/index.rst b/doc/source/dev/index.rst index b5c7d297b..c3f880a35 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -10,24 +10,23 @@ we list them in alphabetical order): - Community coordination - DevOps - Developing educational content & narrative documentation -- Writing technical documentation - Fundraising -- Project management - Marketing +- Project management - Translating content - Website design and development +- Writing technical documentation The rest of this document discusses working on the NumPy code base and documentation. We're in the process of updating our descriptions of other activities and roles. If you are interested in these other activities, please contact us! You can do this via -the `numpy-discussion mailing list <https://scipy.org/scipylib/mailing-lists.html>`__, -or on GitHub (open an issue or comment on a relevant issue). These are our preferred -communication channels (open source is open by nature!), however if you prefer -to discuss in private first, please reach out to our community coordinators -at `numpy-team@googlegroups.com` or `numpy-team.slack.com` (send an email to -`numpy-team@googlegroups.com` for an invite the first time). - +the `numpy-discussion mailing list <https://mail.python.org/mailman/listinfo/numpy-discussion>`__, +or on `GitHub <https://github.com/numpy/numpy>`__ (open an issue or comment on a +relevant issue). These are our preferred communication channels (open source is open +by nature!), however if you prefer to discuss in private first, please reach out to +our community coordinators at `numpy-team@googlegroups.com` or `numpy-team.slack.com` +(send an email to `numpy-team@googlegroups.com` for an invite the first time). Development process - summary ============================= 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/reference/routines.ma.rst b/doc/source/reference/routines.ma.rst index 5b2098c7a..346ce2a1b 100644 --- a/doc/source/reference/routines.ma.rst +++ b/doc/source/reference/routines.ma.rst @@ -396,6 +396,7 @@ Miscellanea ma.allequal ma.allclose ma.apply_along_axis + ma.apply_over_axes ma.arange ma.choose ma.ediff1d 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 |