diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/contents.rst | 8 | ||||
| -rw-r--r-- | doc/source/dev/conduct/code_of_conduct.rst | 4 | ||||
| -rw-r--r-- | doc/source/dev/governance/people.rst | 4 | ||||
| -rw-r--r-- | doc/source/dev/howto-docs.rst | 149 | ||||
| -rw-r--r-- | doc/source/dev/index.rst | 3 | ||||
| -rw-r--r-- | doc/source/reference/global_state.rst | 85 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 3 | ||||
| -rw-r--r-- | doc/source/reference/random/index.rst | 3 | ||||
| -rw-r--r-- | doc/source/reference/random/new-or-different.rst | 12 | ||||
| -rw-r--r-- | doc/source/release.rst | 1 | ||||
| -rw-r--r-- | doc/source/release/1.18.4-notes.rst | 38 | ||||
| -rw-r--r-- | doc/source/user/quickstart.rst | 2 | ||||
| -rw-r--r-- | doc/source/user/setting-up.rst | 1 | ||||
| -rw-r--r-- | doc/source/user/troubleshooting-importerror.rst | 134 |
14 files changed, 437 insertions, 10 deletions
diff --git a/doc/source/contents.rst b/doc/source/contents.rst index c89153aa7..baea7784c 100644 --- a/doc/source/contents.rst +++ b/doc/source/contents.rst @@ -1,8 +1,8 @@ -.. _manual: +.. _numpy_docs_mainpage: -##################### -NumPy manual contents -##################### +################### +NumPy Documentation +################### .. toctree:: diff --git a/doc/source/dev/conduct/code_of_conduct.rst b/doc/source/dev/conduct/code_of_conduct.rst index aca39d8a7..f2f0a536d 100644 --- a/doc/source/dev/conduct/code_of_conduct.rst +++ b/doc/source/dev/conduct/code_of_conduct.rst @@ -113,8 +113,8 @@ You can report issues to the NumPy Code of Conduct committee, at numpy-conduct@googlegroups.com. Currently, the committee consists of: - Stefan van der Walt -- Nathaniel J. Smith -- Ralf Gommers +- Melissa Weber Mendonça +- Anirudh Subramanian If your report involves any members of the committee, or if they feel they have a conflict of interest in handling it, then they will recuse themselves from diff --git a/doc/source/dev/governance/people.rst b/doc/source/dev/governance/people.rst index 10af7f221..db2704d09 100644 --- a/doc/source/dev/governance/people.rst +++ b/doc/source/dev/governance/people.rst @@ -56,7 +56,7 @@ NumFOCUS Subcommittee Institutional Partners ---------------------- -* UC Berkeley (Stefan van der Walt, Matti Picus, Tyler Reddy, Sebastian Berg) +* UC Berkeley (Stefan van der Walt, Sebastian Berg, Warren Weckesser, Ross Barnowski) -* Quansight (Ralf Gommers, Hameer Abbasi) +* Quansight (Ralf Gommers, Hameer Abbasi, Melissa Weber Mendonça, Mars Lee, Matti Picus) diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst new file mode 100644 index 000000000..0e2e03e0b --- /dev/null +++ b/doc/source/dev/howto-docs.rst @@ -0,0 +1,149 @@ +.. _howto-docs: + +############################################ +How to contribute to the NumPy documentation +############################################ + +The *Documentation* for a software project is the set of reference, +instructional, educational, informative material generated by the project +developers and contributors, as well as discussions, presentations, videos and +other user-generated content. It may include learning-oriented content (such as +tutorials and how-tos), use-cases or in-depth explanations and reference for +developers. + +If you're reading this page, you probably want to help. This guide is meant to +help you decide which kind of content you'll write, as well as give you some +tips and instructions for submitting it to the official NumPy documentation +(that is, the documentation that ships with NumPy and lives on the +:ref:`official project pages <numpy_docs_mainpage>`). Keep in mind that if you +don't want to do this, writing a tutorial on your own blog, creating a YouTube +video or answering questions on social media or Stack Overflow are also great +contributions! + +NumPy has a Documentation Team. We have open meetings on Zoom every three weeks +and invite everyone to join. Don't hesitate to reach out if you have questions +or just need someone to guide you through your first steps - we're always happy +to help. Meetings are usually announced on the `numpy-discussion mailing list +<https://mail.python.org/mailman/listinfo/numpy-discussion>`__. Meeting minutes +are taken `on hackmd.io <https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg>`__ and stored +in the `NumPy Archive repository <https://github.com/numpy/archive>`__. + +You can find larger planned and in-progress documentation improvement ideas `at +our GitHub project <https://github.com/orgs/numpy/projects/2>`__. + +Current vision for the documentation: NEP 44 +-------------------------------------------- + +Recently, the NumPy community approved a *NumPy Enhancement Proposal (NEP)* +about documentation, `NEP 44 - Restructuring the NumPy Documentation +<https://www.numpy.org/neps/nep-0044-restructuring-numpy-docs>`__. + +**Where is the documentation?** + +The main page for the :ref:`NumPy Documentation <numpy_docs_mainpage>` lists +several categories. The documents mentioned there live in different places. + +- **Tutorials, How-Tos, Explanations:** These documents are stored in the NumPy + source code tree, which means that in order to add them to the official + documentation, you have to download the NumPy source code, + :ref:`build it <howto-build-docs>` and submit your changes via a + :ref:`GitHub pull request <devindex>`. + +- **API Reference:** These are mainly the result of rendering the NumPy code + `docstrings <https://www.python.org/dev/peps/pep-0257/>`__ into formatted + documents. They are automatically generated when the NumPy documentation is + :ref:`built from source<howto-build-docs>`. + +**Datasets** + +If you are writing a tutorial or how-to, we encourage you to use real images and +data (provided they are appropriately licensed and available). This makes the +material more engaging for readers, and choosing the right data can add +pedagogical value to your content. + +*Note: currently we cannot easily use data in other packages (except, e.g., from +SciPy or Matplotlib). We plan to create a dedicated datasets package, but that's +not ready yet - please discuss with us if you have data sources in mind.* + +Creating new content +-------------------- + +The documentation is written in restructuredText, which is the format required +by Sphinx, the tool most Python projects use to automatically build and link the +documentation within the project. You can read the +`Quick reStructuredText Guide +<https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__ or the +`reStructuredText Primer +<http://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html>`__ for +more information. + +If you have already decided which type of document you want to write, you can +check out the following specific guides: + +- Guide to writing Tutorials (TODO) +- :ref:`Guide to writing reference (API) documentation: the numpydoc docstring + guide <howto-document>` + +Major additions to the documentation (e.g. new tutorials) should be proposed to +the `mailing list +<https://mail.python.org/mailman/listinfo/numpy-discussion>`__. + +Other ways to contribute +------------------------ + +Correcting technical inaccuracies in the documentation are high priority. For +example, if a docstring is missing a parameter or the description of a +fuction/parameter/method etc. is incorrect. Other "structural" defects like +broken links are also high priority. + +Proposals for changes that improve the clarity of the documentation are welcome. +However, "clarity" is a bit subjective, so such proposals are best made by +raising issues that describe what could be improved in the current +documentation. Proposals that include specific suggestions for the improvement +are encouraged as the proposed changes helps frame the discussion. + +Based on the above characterization, "high-priority" changes (i.e. fixing +technical inaccuracies, broken links, etc.) can be proposed via pull requests +directly as they are straightforward to review. Other changes should be raised +as issues first so that the discussion can happen before you make major +modifications, which in principle saves you from wasting your time on +undesired changes. + +If you see a good tutorial, how-to or explanation that is not included in the +official documentation, you can suggest it to be added by `opening an issue on +GitHub <https://github.com/numpy/numpy/issues>`__. Similarly, opening issues to +suggest a tutorial, how-to or explanation that you can't find anywhere is a +great way to help the documentation team direct efforts towards what users are +looking for. `See this issue <https://github.com/numpy/numpy/issues/15760>`__ +for an example of how to do this. + +Finally, if you detect a typo or an error in the documentation, or would like to +suggest a different approach, you can also open an issue or submit a pull +request with your suggestion. Keep in mind that changes fixing +grammatical/spelling errors are welcome but not necessarily the highest +priority. "Grammatical correctness" often gets confused with "style" which can +result in unfruitful discussions that don't necessarily improve anything. +Changes that modify wording or rearrange phrasing without changing the technical +content are discouraged. If you think that a different wording improves clarity, +you should open an issue as noted above, but again, changes along these lines +very often tend to be highly subjective and not necessarily do much to improve +the quality of the documentation. + +**Final tips** + +- Don't worry if English is not your first language. Do your best - we'll revise + your content and make sure we fix any issues with the code or text. +- If you are unsure whether your tutorial is useful to the community, consider + submitting an issue on GitHub suggesting it, or asking on the mailing + list or Stack Overflow. +- If you are unfamiliar with git/GitHub or the process of submitting a pull + request (PR), check our :ref:`Contributor Guide <devindex>`. + +**Other interesting material** + +- `writethedocs.org <https://www.writethedocs.org/>`__ has a lot of interesting + resources for technical writing. +- Google offers two free `Technical Writing Courses + <https://developers.google.com/tech-writing>`__ +- `Software Carpentry <https://software-carpentry.org/software>`__ has a lot of + nice recommendations for creating educational material. diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index dc6099992..5270bfb77 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -1,3 +1,5 @@ +.. _devindex: + ##################### Contributing to NumPy ##################### @@ -284,6 +286,7 @@ The rest of the story style_guide releasing governance/index + howto-docs NumPy-specific workflow is in :ref:`numpy-development-workflow <development-workflow>`. diff --git a/doc/source/reference/global_state.rst b/doc/source/reference/global_state.rst new file mode 100644 index 000000000..2a163390e --- /dev/null +++ b/doc/source/reference/global_state.rst @@ -0,0 +1,85 @@ +.. _global_state: + +************ +Global State +************ + +NumPy has a few import-time, compile-time, or runtime options +which change the global behaviour. +Most of these are related to performance or for debugging +purposes and will not be interesting to the vast majority +of users. + + +Performance-Related Options +=========================== + +Number of Threads used for Linear Algebra +----------------------------------------- + +NumPy itself is normally intentionally limited to a single thread +during function calls, however it does support multiple Python +threads running at the same time. +Note that for performant linear algebra NumPy uses a BLAS backend +such as OpenBLAS or MKL, which may use multiple threads that may +be controlled by environment variables such as ``OMP_NUM_THREADS`` +depending on what is used. +One way to control the number of threads is the package +`threadpoolctl <https://pypi.org/project/threadpoolctl/>`_ + + +Madvise Hugepage on Linux +------------------------- + +When working with very large arrays on modern Linux kernels, +you can experience a significant speedup when +`transparent hugepage <https://www.kernel.org/doc/html/latest/admin-guide/mm/transhuge.html>`_ +is used. +The current system policy for transparent hugepages can be seen by:: + + cat /sys/kernel/mm/transparent_hugepage/enabled + +When set to ``madvise`` NumPy will typically use hugepages for a performance +boost. This behaviour can be modified by setting the environment variable:: + + NUMPY_MADVISE_HUGEPAGE=0 + +or setting it to ``1`` to always enable it. When not set, the default +is to use madvise on Kernels 4.6 and newer. These kernels presumably +experience a large speedup with hugepage support. +This flag is checked at import time. + + +Interoperability-Related Options +================================ + +The array function protocol which allows array-like objects to +hook into the NumPy API is currently enabled by default. +This option exists since NumPy 1.16 and is enabled by default since +NumPy 1.17. It can be disabled using:: + + NUMPY_EXPERIMENTAL_ARRAY_FUNCTION=0 + +See also :py:meth:`numpy.class.__array_function__` for more information. +This flag is checked at import time. + + +Debugging-Related Options +========================= + +Relaxed Strides Checking +------------------------ + +The *compile-time* environment variables:: + + NPY_RELAXED_STRIDES_DEBUG=0 + NPY_RELAXED_STRIDES_CHECKING=1 + +control how NumPy reports contiguity for arrays. +The default that it is enabled and the debug mode is disabled. +This setting should always be enabled. Setting the +debug option can be interesting for testing code written +in C which iterates through arrays that may or may not be +contiguous in memory. +Most users will have no reason to change these, for details +please see the `memory layout <memory-layout>`_ documentation. diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index d042a1849..2e1dcafa2 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 the :ref:`complete documentation <manual>`. +For learning how to use NumPy, see the :ref:`complete documentation <numpy_docs_mainpage>`. .. toctree:: @@ -22,6 +22,7 @@ For learning how to use NumPy, see the :ref:`complete documentation <manual>`. constants ufuncs routines + global_state distutils distutils_guide c-api/index diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst index bda9c4d96..d559f2327 100644 --- a/doc/source/reference/random/index.rst +++ b/doc/source/reference/random/index.rst @@ -168,6 +168,9 @@ What's New or Different Python's `random.random`. * All BitGenerators in numpy use `SeedSequence` to convert seeds into initialized states. +* The addition of an ``axis`` keyword argument to methods such as + `Generator.choice`, `Generator.permutation`, and `Generator.shuffle` + improves support for sampling from and shuffling multi-dimensional arrays. See :ref:`new-or-different` for a complete list of improvements and differences from the traditional ``Randomstate``. diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst index 1d6b09faf..03e7775a0 100644 --- a/doc/source/reference/random/new-or-different.rst +++ b/doc/source/reference/random/new-or-different.rst @@ -115,3 +115,15 @@ And in more detail: rg.random(out=existing[:2]) print(existing) +* Optional ``axis`` argument for methods like `~.Generator.choice`, + `~.Generator.permutation` and `~.Generator.shuffle` that controls which + axis an operation is performed over for multi-dimensional arrays. + +.. ipython:: python + + rg = Generator(PCG64(123456789)) + a = np.arange(12).reshape((3, 4)) + a + rg.choice(a, axis=1, size=5) + rg.shuffle(a, axis=1) # Shuffle in-place + a diff --git a/doc/source/release.rst b/doc/source/release.rst index 0a1402bf7..1e5697828 100644 --- a/doc/source/release.rst +++ b/doc/source/release.rst @@ -6,6 +6,7 @@ Release Notes :maxdepth: 3 1.19.0 <release/1.19.0-notes> + 1.18.4 <release/1.18.4-notes> 1.18.3 <release/1.18.3-notes> 1.18.2 <release/1.18.2-notes> 1.18.1 <release/1.18.1-notes> diff --git a/doc/source/release/1.18.4-notes.rst b/doc/source/release/1.18.4-notes.rst new file mode 100644 index 000000000..25ef1d127 --- /dev/null +++ b/doc/source/release/1.18.4-notes.rst @@ -0,0 +1,38 @@ +.. currentmodule:: numpy + +========================== +NumPy 1.18.4 Release Notes +========================== + +This is the last planned release in the 1.18.x series. It reverts the +``bool("0")`` behavior introduced in 1.18.3 and fixes a bug in +``Generator.integers``. There is also a link to a new troubleshooting section +in the documentation included in the error message emitted when numpy import +fails. + +The Python versions supported in this release are 3.5-3.8. Downstream +developers should use Cython >= 0.29.15 for Python 3.8 support and +OpenBLAS >= 3.7 to avoid errors on the Skylake architecture. + +Contributors +============ + +A total of 4 people contributed to this release. People with a "+" by their +names contributed a patch for the first time. + +* Charles Harris +* Matti Picus +* Sebastian Berg +* Warren Weckesser + +Pull requests merged +==================== + +A total of 6 pull requests were merged for this release. + +* `#16055 <https://github.com/numpy/numpy/pull/16055>`__: BLD: add i686 for 1.18 builds +* `#16090 <https://github.com/numpy/numpy/pull/16090>`__: BUG: random: ``Generator.integers(2**32)`` always returned 0. +* `#16091 <https://github.com/numpy/numpy/pull/16091>`__: BLD: fix path to libgfortran on macOS +* `#16109 <https://github.com/numpy/numpy/pull/16109>`__: REV: Reverts side-effect changes to casting +* `#16114 <https://github.com/numpy/numpy/pull/16114>`__: BLD: put openblas library in local directory on windows +* `#16132 <https://github.com/numpy/numpy/pull/16132>`__: DOC: Change import error "howto" to link to new troubleshooting... diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index 6ad0e52f9..29a4d80ca 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -760,7 +760,7 @@ stacks 1D arrays as columns into a 2D array. It is equivalent to [2., 8.]]) >>> np.hstack((a,b)) # the result is different array([4., 2., 3., 8.]) - >>> a[:,newaxis] # this allows to have a 2D columns vector + >>> a[:,newaxis] # view `a` as a 2D column vector array([[4.], [2.]]) >>> np.column_stack((a[:,newaxis],b[:,newaxis])) diff --git a/doc/source/user/setting-up.rst b/doc/source/user/setting-up.rst index f70dacf82..7ca3a365c 100644 --- a/doc/source/user/setting-up.rst +++ b/doc/source/user/setting-up.rst @@ -7,3 +7,4 @@ Setting up whatisnumpy install + troubleshooting-importerror diff --git a/doc/source/user/troubleshooting-importerror.rst b/doc/source/user/troubleshooting-importerror.rst new file mode 100644 index 000000000..131e698dd --- /dev/null +++ b/doc/source/user/troubleshooting-importerror.rst @@ -0,0 +1,134 @@ +*************************** +Troubleshooting ImportError +*************************** + +.. note:: + + Since this information may be updated regularly, please ensure you are + viewing the most `up-to-date version <https://numpy.org/devdocs/user/troubleshooting-importerror.html>`_. + + +ImportError +=========== + +In certain cases a failed installation or setup issue can cause you to +see the following error message:: + + IMPORTANT: PLEASE READ THIS FOR ADVICE ON HOW TO SOLVE THIS ISSUE! + + Importing the numpy c-extensions failed. This error can happen for + different reasons, often due to issues with your setup. + +The error also has additional information to help you troubleshoot: + +* Your Python version +* Your NumPy version + +Please check both of these carefully to see if they are what you expect. +You may need to check your ``PATH`` or ``PYTHONPATH`` environment variables +(see `Check Environment Variables`_ below). + +The following sections list commonly reported issues depending on your setup. +If you have an issue/solution that you think should appear please open a +NumPy issue so that it will be added. + +There are a few commonly reported issues depending on your system/setup. +If none of the following tips help you, please be sure to note the following: + +* how you installed Python +* how you installed NumPy +* your operating system +* whether or not you have multiple versions of Python installed +* if you built from source, your compiler versions and ideally a build log + +when investigating further and asking for support. + + +Using Python from ``conda`` (Anaconda) +-------------------------------------- + +Please make sure that you have activated your conda environment. +See also the `conda user-guide <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment>`_. +If you use an external editor/development environment it will have to be set +up correctly. See below for solutions for some common setups. + +Using PyCharm with Anaconda/conda Python +---------------------------------------- + +There are fairly common issues when using PyCharm together with Anaconda, +please see the `PyCharm support <https://www.jetbrains.com/help/pycharm/conda-support-creating-conda-virtual-environment.html>`_ + +Using VSCode with Anaconda/conda Python (or environments) +--------------------------------------------------------- + +A commonly reported issue is related to the environment activation within +VSCode. Please see the `VSCode support <https://code.visualstudio.com/docs/python/environments>`_ +for information on how to correctly set up VSCode with virtual environments +or conda. + + +Raspberry Pi +------------ + +There are sometimes issues reported on Raspberry Pi setups when installing +using ``pip3 install`` (or ``pip`` install). These will typically mention:: + + libf77blas.so.3: cannot open shared object file: No such file or directory + + +The solution will be to either:: + + sudo apt-get install libatlas-base-dev + +to install the missing libraries expected by the self-compiled NumPy +(ATLAS is a possible provider of linear algebra). + +*Alternatively* use the NumPy provided by Raspbian. In which case run:: + + pip3 uninstall numpy # remove previously installed version + apt install python3-numpy + + +Debug build on Windows +---------------------- + +Rather than building your project in ``DEBUG`` mode on windows, try +building in ``RELEASE`` mode with debug symbols and no optimization. +Full ``DEBUG`` mode on windows changes the names of the DLLs python +expects to find, so if you wish to truly work in ``DEBUG`` mode you will +need to recompile the entire stack of python modules you work with +including NumPy + + +All Setups +---------- + +Occasionally there may be simple issues with old or bad installations +of NumPy. In this case you may just try to uninstall and reinstall NumPy. +Make sure that NumPy is not found after uninstalling. + + +Development Setup +----------------- + +If you are using a development setup, make sure to run ``git clean -xdf`` +to delete all files not under version control (be careful not to lose +any modifications you made, e.g. ``site.cfg``). +In many cases files from old builds may lead to incorrect builds. + + +Check Environment Variables +--------------------------- + +In general how to set and check your environment variables depends on +your system. If you can open a correct python shell, you can also run the +following in python:: + + import os + PYTHONPATH = os.environ['PYTHONPATH'].split(os.pathsep) + print("The PYTHONPATH is:", PYTHONPATH) + PATH = os.environ['PATH'].split(os.pathsep) + print("The PATH is:", PATH) + +This may mainly help you if you are not running the python and/or NumPy +version you are expecting to run. |