diff options
Diffstat (limited to 'doc/source/user')
| -rw-r--r-- | doc/source/user/absolute_beginners.rst | 4 | ||||
| -rw-r--r-- | doc/source/user/basics.creation.rst | 6 | ||||
| -rw-r--r-- | doc/source/user/basics.dispatch.rst | 4 | ||||
| -rw-r--r-- | doc/source/user/basics.indexing.rst | 13 | ||||
| -rw-r--r-- | doc/source/user/basics.rec.rst | 5 | ||||
| -rw-r--r-- | doc/source/user/building.rst | 29 | ||||
| -rw-r--r-- | doc/source/user/how-to-index.rst | 26 | ||||
| -rw-r--r-- | doc/source/user/how-to-verify-bug.rst | 2 | ||||
| -rw-r--r-- | doc/source/user/howtos_index.rst | 2 | ||||
| -rw-r--r-- | doc/source/user/quickstart.rst | 2 | ||||
| -rw-r--r-- | doc/source/user/theory.broadcasting.rst | 2 | ||||
| -rw-r--r-- | doc/source/user/troubleshooting-importerror.rst | 68 |
12 files changed, 119 insertions, 44 deletions
diff --git a/doc/source/user/absolute_beginners.rst b/doc/source/user/absolute_beginners.rst index dae2c4f06..dfcdc669b 100644 --- a/doc/source/user/absolute_beginners.rst +++ b/doc/source/user/absolute_beginners.rst @@ -64,8 +64,8 @@ To access NumPy and its functions import it in your Python code like this:: import numpy as np We shorten the imported name to ``np`` for better readability of code using -NumPy. This is a widely adopted convention that you should follow so that -anyone working with your code can easily understand it. +NumPy. This is a widely adopted convention that makes your code more readable +for everyone working on it. We recommend to always use import numpy as ``np``. Reading the example code ------------------------ diff --git a/doc/source/user/basics.creation.rst b/doc/source/user/basics.creation.rst index a97d69d8b..3ee501889 100644 --- a/doc/source/user/basics.creation.rst +++ b/doc/source/user/basics.creation.rst @@ -75,8 +75,8 @@ the computation, here ``uint32`` and ``int32`` can both be represented in as ``int64``. The default NumPy behavior is to create arrays in either 32 or 64-bit signed -integers (platform dependent and matches C int size) or double precision -floating point numbers, int32/int64 and float, respectively. If you expect your +integers (platform dependent and matches C ``long`` size) or double precision +floating point numbers. If you expect your integer arrays to be a specific type, then you need to specify the dtype while you create the array. @@ -352,7 +352,7 @@ and :func:`numpy.genfromtxt`. These functions have more involved use cases in 2, 4 3, 9 -Importing ``simple.csv`` is accomplished using :func:`loadtxt`:: +Importing ``simple.csv`` is accomplished using :func:`numpy.loadtxt`:: >>> np.loadtxt('simple.csv', delimiter = ',', skiprows = 1) # doctest: +SKIP array([[0., 0.], diff --git a/doc/source/user/basics.dispatch.rst b/doc/source/user/basics.dispatch.rst index 7c30272ad..a493ef769 100644 --- a/doc/source/user/basics.dispatch.rst +++ b/doc/source/user/basics.dispatch.rst @@ -281,14 +281,14 @@ Numpy provides some utilities to aid testing of custom array containers that implement the ``__array_ufunc__`` and ``__array_function__`` protocols in the ``numpy.testing.overrides`` namespace. -To check if a Numpy function can be overriden via ``__array_ufunc__``, you can +To check if a Numpy function can be overridden via ``__array_ufunc__``, you can use :func:`~numpy.testing.overrides.allows_array_ufunc_override`: >>> from np.testing.overrides import allows_array_ufunc_override >>> allows_array_ufunc_override(np.add) True -Similarly, you can check if a function can be overriden via +Similarly, you can check if a function can be overridden via ``__array_function__`` using :func:`~numpy.testing.overrides.allows_array_function_override`. diff --git a/doc/source/user/basics.indexing.rst b/doc/source/user/basics.indexing.rst index b140e223a..17fc9c0cc 100644 --- a/doc/source/user/basics.indexing.rst +++ b/doc/source/user/basics.indexing.rst @@ -481,12 +481,13 @@ tuple (of length :attr:`obj.ndim <ndarray.ndim>`) of integer index arrays showing the :py:data:`True` elements of *obj*. However, it is faster when ``obj.shape == x.shape``. -If ``obj.ndim == x.ndim``, ``x[obj]`` returns a 1-dimensional array -filled with the elements of *x* corresponding to the :py:data:`True` -values of *obj*. The search order will be :term:`row-major`, -C-style. If *obj* has :py:data:`True` values at entries that are outside -of the bounds of *x*, then an index error will be raised. If *obj* is -smaller than *x* it is identical to filling it with :py:data:`False`. +If ``obj.ndim == x.ndim``, ``x[obj]`` +returns a 1-dimensional array filled with the elements of *x* +corresponding to the :py:data:`True` values of *obj*. The search order +will be :term:`row-major`, C-style. An index error will be raised if +the shape of *obj* does not match the corresponding dimensions of *x*, +regardless of whether those values are :py:data:`True` or +:py:data:`False`. A common use case for this is filtering for desired element values. For example, one may wish to select all entries from an array which diff --git a/doc/source/user/basics.rec.rst b/doc/source/user/basics.rec.rst index b56b4d177..640cfaa8b 100644 --- a/doc/source/user/basics.rec.rst +++ b/doc/source/user/basics.rec.rst @@ -166,6 +166,11 @@ attribute of the dtype object:: >>> d.names ('x', 'y') +The dtype of each individual field can be looked up by name:: + + >>> d['x'] + dtype('int64') + The field names may be modified by assigning to the ``names`` attribute using a sequence of strings of the same length. diff --git a/doc/source/user/building.rst b/doc/source/user/building.rst index d01b6c44e..442bda4b3 100644 --- a/doc/source/user/building.rst +++ b/doc/source/user/building.rst @@ -3,31 +3,14 @@ Building from source ==================== -There are two options for building NumPy- building with Gitpod or locally from -source. Your choice depends on your operating system and familiarity with the -command line. - -Gitpod ------- - -Gitpod is an open-source platform that automatically creates -the correct development environment right in your browser, reducing the need to -install local development environments and deal with incompatible dependencies. - -If you are a Windows user, unfamiliar with using the command line or building -NumPy for the first time, it is often faster to build with Gitpod. Here are the -in-depth instructions for building NumPy with `building NumPy with Gitpod`_. - -.. _building NumPy with Gitpod: https://numpy.org/devdocs/dev/development_gitpod.html - -Building locally ----------------- - -Building locally on your machine gives you -more granular control. If you are a MacOS or Linux user familiar with using the +Building locally on your machine gives you complete control over build options. +If you are a MacOS or Linux user familiar with using the command line, you can continue with building NumPy locally by following the instructions below. +.. note:: If you want to build NumPy for development purposes, please refer to + :ref:`development-environment` for additional information. + .. This page is referenced from numpy/numpy/__init__.py. Please keep its location in sync with the link there. @@ -37,7 +20,7 @@ Prerequisites Building NumPy requires the following software installed: -1) Python 3.8.x or newer +1) Python 3.9.x or newer Please note that the Python development headers also need to be installed, e.g., on Debian/Ubuntu one needs to install both `python3` and diff --git a/doc/source/user/how-to-index.rst b/doc/source/user/how-to-index.rst index e47e9a204..97c451260 100644 --- a/doc/source/user/how-to-index.rst +++ b/doc/source/user/how-to-index.rst @@ -309,6 +309,30 @@ result as dimensions with size one:: array([[[2, 2, 2, 2, 2]], <BLANKLINE> [[2, 2, 2, 2, 2]]]) + +To get the indices of each maximum or minimum value for each +(N-1)-dimensional array in an N-dimensional array, use :meth:`reshape` +to reshape the array to a 2D array, apply :meth:`argmax` or :meth:`argmin` +along ``axis=1`` and use :meth:`unravel_index` to recover the index of the +values per slice:: + + >>> x = np.arange(2*2*3).reshape(2, 2, 3) % 7 # 3D example array + >>> x + array([[[0, 1, 2], + [3, 4, 5]], + <BLANKLINE> + [[6, 0, 1], + [2, 3, 4]]]) + >>> x_2d = np.reshape(x, (x.shape[0], -1)) + >>> indices_2d = np.argmax(x_2d, axis=1) + >>> indices_2d + array([5, 0]) + >>> np.unravel_index(indices_2d, x.shape[1:]) + (array([1, 0]), array([2, 0])) + +The first array returned contains the indices along axis 1 in the original +array, the second array contains the indices along axis 2. The highest +value in ``x[0]`` is therefore ``x[0, 1, 2]``. Index the same ndarray multiple times efficiently ================================================= @@ -348,4 +372,4 @@ Exercises `6`_, `8`_, `10`_, `15`_, `16`_, `19`_, `20`_, `45`_, `59`_, .. _87: https://github.com/rougier/numpy-100/blob/master/100_Numpy_exercises_with_solutions.md#87-consider-a-16x16-array-how-to-get-the-block-sum-block-size-is-4x4- .. _90: https://github.com/rougier/numpy-100/blob/master/100_Numpy_exercises_with_solutions.md#90-given-an-arbitrary-number-of-vectors-build-the-cartesian-product-every-combinations-of-every-item- .. _93: https://github.com/rougier/numpy-100/blob/master/100_Numpy_exercises_with_solutions.md#93-consider-two-arrays-a-and-b-of-shape-83-and-22-how-to-find-rows-of-a-that-contain-elements-of-each-row-of-b-regardless-of-the-order-of-the-elements-in-b- -.. _94: https://github.com/rougier/numpy-100/blob/master/100_Numpy_exercises_with_solutions.md#94-considering-a-10x3-matrix-extract-rows-with-unequal-values-eg-223-
\ No newline at end of file +.. _94: https://github.com/rougier/numpy-100/blob/master/100_Numpy_exercises_with_solutions.md#94-considering-a-10x3-matrix-extract-rows-with-unequal-values-eg-223- diff --git a/doc/source/user/how-to-verify-bug.rst b/doc/source/user/how-to-verify-bug.rst index 4fc58c707..6e76f453a 100644 --- a/doc/source/user/how-to-verify-bug.rst +++ b/doc/source/user/how-to-verify-bug.rst @@ -76,7 +76,7 @@ The report references NumPy version 1.18.4, so that is the version you need to install in this case. Since this bug is tied to a release and not a specific commit, a pre-built wheel -installed in your virtual environment via `pip` will suffice:: +installed in your virtual environment via ``pip`` will suffice:: pip install numpy==1.18.4 diff --git a/doc/source/user/howtos_index.rst b/doc/source/user/howtos_index.rst index 4a0a22900..ca30f7e91 100644 --- a/doc/source/user/howtos_index.rst +++ b/doc/source/user/howtos_index.rst @@ -1,7 +1,7 @@ .. _howtos: ################ -NumPy How Tos +NumPy how-tos ################ These documents are intended as recipes to common tasks using NumPy. For diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index d138242d7..783d5a447 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -1482,7 +1482,7 @@ Further reading - The `Python tutorial <https://docs.python.org/tutorial/>`__ - :ref:`reference` -- `SciPy Tutorial <https://docs.scipy.org/doc/scipy/reference/tutorial/index.html>`__ +- `SciPy Tutorial <https://docs.scipy.org/doc/scipy/tutorial/index.html>`__ - `SciPy Lecture Notes <https://scipy-lectures.org>`__ - A `matlab, R, IDL, NumPy/SciPy dictionary <http://mathesaurus.sf.net/>`__ - :doc:`tutorial-svd <numpy-tutorials:content/tutorial-svd>` diff --git a/doc/source/user/theory.broadcasting.rst b/doc/source/user/theory.broadcasting.rst index a4973e4e6..f277d4afd 100644 --- a/doc/source/user/theory.broadcasting.rst +++ b/doc/source/user/theory.broadcasting.rst @@ -1,7 +1,7 @@ :orphan: =========================== -Array Broadcasting in Numpy +Array broadcasting in Numpy =========================== .. diff --git a/doc/source/user/troubleshooting-importerror.rst b/doc/source/user/troubleshooting-importerror.rst index 2227d7b07..552748a6a 100644 --- a/doc/source/user/troubleshooting-importerror.rst +++ b/doc/source/user/troubleshooting-importerror.rst @@ -6,9 +6,9 @@ to this page. -*************************** -Troubleshooting ImportError -*************************** +*************** +Troubleshooting +*************** .. note:: @@ -183,3 +183,65 @@ that usually works is to upgrade the NumPy version:: pip install numpy --upgrade +Segfaults or crashes +==================== + +NumPy tries to use advanced CPU features (SIMD) to speed up operations. If you +are getting an "illegal instruction" error or a segfault, one cause could be +that the environment claims it can support one or more of these features but +actually cannot. This can happen inside a docker image or a VM (qemu, VMWare, +...) + +You can use the output of ``np.show_runtime()`` to show which SIMD features are +detected. For instance:: + + >>> np.show_runtime() + WARNING: `threadpoolctl` not found in system! Install it by `pip install \ + threadpoolctl`. Once installed, try `np.show_runtime` again for more detailed + build information + [{'simd_extensions': {'baseline': ['SSE', 'SSE2', 'SSE3'], + 'found': ['SSSE3', + 'SSE41', + 'POPCNT', + 'SSE42', + 'AVX', + 'F16C', + 'FMA3', + 'AVX2'], + 'not_found': ['AVX512F', + 'AVX512CD', + 'AVX512_KNL', + 'AVX512_KNM', + 'AVX512_SKX', + 'AVX512_CLX', + 'AVX512_CNL', + 'AVX512_ICL']}}] + +In this case, it shows AVX2 and FMA3 under the ``found`` section, so you can +try disabling them by setting ``NPY_DISABLE_CPU_FEATURES="AVX2,FMA3"`` in your +environment before running python (for cmd.exe on windows):: + + >SET NPY_DISABLE_CPU_FEATURES="AVX2,FMA3" + >python <myprogram.py> + +By installing threadpoolctl ``np.show_runtime()`` will show additional information:: + + ... + {'architecture': 'Zen', + 'filepath': '/tmp/venv3/lib/python3.9/site-packages/numpy.libs/libopenblas64_p-r0-15028c96.3.21.so', + 'internal_api': 'openblas', + 'num_threads': 24, + 'prefix': 'libopenblas', + 'threading_layer': 'pthreads', + 'user_api': 'blas', + 'version': '0.3.21'}] + +If you use the wheel from PyPI, it contains code from the OpenBLAS project to +speed up matrix operations. This code too can try to use SIMD instructions. It +has a different mechanism for choosing which to use, based on a CPU +architecture, You can override this architecture by setting +``OPENBLAS_CORETYPE``: a minimal value for ``x86_64`` is +``OPENBLAS_CORETYPE=Haswell``. This too needs to be set before running your +python (this time for posix):: + + $ OPENBLAS_CORETYPE=Haswell python <myprogram.py> |