diff options
Diffstat (limited to 'doc')
24 files changed, 542 insertions, 25 deletions
diff --git a/doc/TESTS.rst.txt b/doc/TESTS.rst.txt index 007840b39..af47fe99c 100644 --- a/doc/TESTS.rst.txt +++ b/doc/TESTS.rst.txt @@ -256,7 +256,7 @@ section of your setup.py:: ... def configuration(parent_package='', top_path=None): ... - config.add_data_dir('tests') + config.add_subpackage('tests') return config ... diff --git a/doc/changelog/1.18.4-changelog.rst b/doc/changelog/1.18.4-changelog.rst new file mode 100644 index 000000000..f3524b5f5 --- /dev/null +++ b/doc/changelog/1.18.4-changelog.rst @@ -0,0 +1,23 @@ + +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/neps/nep-0040-legacy-datatype-impl.rst b/doc/neps/nep-0040-legacy-datatype-impl.rst index c9a4fd7c8..c247e3d62 100644 --- a/doc/neps/nep-0040-legacy-datatype-impl.rst +++ b/doc/neps/nep-0040-legacy-datatype-impl.rst @@ -16,7 +16,8 @@ NEP 40 — Legacy Datatype Implementation in NumPy This NEP is part of a series of NEPs encompassing first information about the previous dtype implementation and issues with it in NEP 40 (this document). - `NEP 41 <NEP41>`_ then provides an overview and generic design choices for the refactor. + :ref:`NEP 41 <NEP41>` then provides an overview and generic design choices + for the refactor. Further NEPs 42 and 43 go into the technical details of the datatype and universal function related internal and external API changes. In some cases it may be necessary to consult the other NEPs for a full @@ -31,7 +32,7 @@ As a preparation to further NumPy enhancement proposals 41, 42, and 43. This NEP details the current status of NumPy datatypes as of NumPy 1.18. It describes some of the technical aspects and concepts that motivated the other proposals. -For more general information most readers should begin by reading `NEP 41 <NEP41>`_ +For more general information most readers should begin by reading :ref:`NEP 41 <NEP41>` and use this document only as a reference or for additional details. diff --git a/doc/neps/nep-0041-improved-dtype-support.rst b/doc/neps/nep-0041-improved-dtype-support.rst index 6310741e0..294f52746 100644 --- a/doc/neps/nep-0041-improved-dtype-support.rst +++ b/doc/neps/nep-0041-improved-dtype-support.rst @@ -8,16 +8,16 @@ NEP 41 — First step towards a new Datatype System :Author: Sebastian Berg :Author: Stéfan van der Walt :Author: Matti Picus -:Status: Draft +:Status: Accepted :Type: Standard Track :Created: 2020-02-03 - +:Resolution: https://mail.python.org/pipermail/numpy-discussion/2020-April/080573.html and https://mail.python.org/pipermail/numpy-discussion/2020-March/080495.html .. note:: This NEP is part of a series of NEPs encompassing first information about the previous dtype implementation and issues with it in - `NEP 40 <NEP40>`_. + :ref:`NEP 40 <NEP40>`. NEP 41 (this document) then provides an overview and generic design choices for the refactor. Further NEPs 42 and 43 go into the technical details of the datatype @@ -29,7 +29,7 @@ NEP 41 — First step towards a new Datatype System Abstract -------- -`Datatypes <data-type-objects-dtype>` in NumPy describe how to interpret each +:ref:`Datatypes <arrays.dtypes>` in NumPy describe how to interpret each element in arrays. NumPy provides ``int``, ``float``, and ``complex`` numerical types, as well as string, datetime, and structured datatype capabilities. The growing Python community, however, has need for more diverse datatypes. @@ -61,7 +61,8 @@ Motivation One of the main issues with the current API is the definition of typical functions such as addition and multiplication for parametric datatypes -(see also `NEP 40 <NEP40>`_) which require additional steps to determine the output type. +(see also :ref:`NEP 40 <NEP40>`) +which require additional steps to determine the output type. For example when adding two strings of length 4, the result is a string of length 8, which is different from the input. Similarly, a datatype which embeds a physical unit must calculate the new unit @@ -144,7 +145,8 @@ in more details in the detailed description section: Storage information such as itemsize and byteorder can differ between different dtype instances (e.g. "S3" vs. "S8") and will remain part of the instance. This means that in the long run the current lowlevel access to dtype methods - will be removed (see ``PyArray_ArrFuncs`` in `NEP 40 <NEP40>`_). + will be removed (see ``PyArray_ArrFuncs`` in + :ref:`NEP 40 <NEP40>`). 2. The current NumPy scalars will *not* change, they will not be instances of datatypes. This will also be true for new datatypes, scalars will not be @@ -225,7 +227,7 @@ Simple Numerical Types """""""""""""""""""""" Mainly used where memory is a consideration, lower-precision numeric types -such as :ref:```bfloat16`` <https://en.wikipedia.org/wiki/Bfloat16_floating-point_format>` +such as `bfloat16 <https://en.wikipedia.org/wiki/Bfloat16_floating-point_format>`_ are common in other computational frameworks. For these types the definitions of things such as ``np.common_type`` and ``np.can_cast`` are some of the most important interfaces. Once they @@ -583,7 +585,8 @@ Organizing these methods and information in a more Pythonic way provides a solid foundation for refining and extending the API in the future. The current API cannot be extended due to how it is exposed publically. This means for example that the methods currently stored in ``PyArray_ArrFuncs`` -on each datatype (see `NEP 40 <NEP40>`_) will be defined differently in the future and +on each datatype (see :ref:`NEP 40 <NEP40>`) +will be defined differently in the future and deprecated in the long run. The most prominent visible side effect of this will be that @@ -601,12 +604,22 @@ Inheritance, however, appears problematic and a complexity best avoided Further, subclasses may be more interesting for interoperability for example with GPU backends (CuPy) storing additional methods related to the GPU rather than as a mechanism to define new datatypes. -A class hierarchy does provides value, this may be achieved by +A class hierarchy does provides value, and one can be achieved by allowing the creation of *abstract* datatypes. An example for an abstract datatype would be the datatype equivalent of ``np.floating``, representing any floating point number. These can serve the same purpose as Python's abstract base classes. +This NEP chooses to duplicate the scalar hierarchy fully or in part. +The main reason is to uncouple the implementation of the DType and scalar. +To add a DType to NumPy, in theory the scalar will not need to be +modified or know about NumPy. Also note that the categorical DType as +currently implemented in pandas does not have a scalar correspondence +making it less straight forward to rely on scalars to implement behaviour. +While DType and Scalar describe the same concept/type (e.g. an `int64`), +it seems practical to split out the information and functionality necessary +for numpy into the DType class. + Scalars should not be instances of the datatypes (2) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -684,8 +697,9 @@ C-API Changes to the UFunc Machinery (4) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Proposed changes to the UFunc machinery will be part of NEP 43. -However, the following changes will be necessary (see `NEP 40 <NEP40>`_ for a detailed -description of the current implementation and its issues): +However, the following changes will be necessary +(see :ref:`NEP 40 <NEP40>` +for a detailed description of the current implementation and its issues): * The current UFunc type resolution must be adapted to allow better control for user-defined dtypes as well as resolve current inconsistencies. @@ -704,7 +718,15 @@ functions after handling the unit related computations. Discussion ---------- -See `NEP 40 <NEP40>`_ for a list of previous meetings and discussions. +See :ref:`NEP 40 <NEP40>` +for a list of previous meetings and discussions. + +Additional discussion around this specific NEP has occured on both +the mailing list and the pull request: + +* `Mailing list discussion <https://mail.python.org/pipermail/numpy-discussion/2020-March/080481.html>`_ +* `NEP 41 pull request <https://github.com/numpy/numpy/pull/15506>`_ +* `Pull request thread on Dtype hierarchy and Scalars <https://github.com/numpy/numpy/pull/15506#discussion_r390016298>`_ References diff --git a/doc/release/13421.improvement.rst b/doc/release/upcoming_changes/13421.improvement.rst index 6d4573aa3..6d4573aa3 100644 --- a/doc/release/13421.improvement.rst +++ b/doc/release/upcoming_changes/13421.improvement.rst diff --git a/doc/release/upcoming_changes/14924.compatibility.rst b/doc/release/upcoming_changes/14924.compatibility.rst new file mode 100644 index 000000000..8b42437fd --- /dev/null +++ b/doc/release/upcoming_changes/14924.compatibility.rst @@ -0,0 +1,7 @@ +Changed random variate stream from `numpy.random.Generator.dirichlet` +--------------------------------------------------------------------- +A bug in the generation of random variates for the Dirichlet distribution +with small `alpha` values was fixed by using a different algorithm when +``max(alpha) < 0.1``. Because of the change, the stream of variates +generated by `dirichlet` in this case will be different from previous +releases. diff --git a/doc/release/upcoming_changes/15715.new_feature.rst b/doc/release/upcoming_changes/15715.new_feature.rst new file mode 100644 index 000000000..a568aee64 --- /dev/null +++ b/doc/release/upcoming_changes/15715.new_feature.rst @@ -0,0 +1,5 @@ +`numpy.linalg.multi_dot` now accepts an ``out`` argument +-------------------------------------------------------- + +``out`` can be used to avoid creating unnecessary copies of the final product +computed by `numpy.linalg.multidot`. diff --git a/doc/release/upcoming_changes/15769.improvement.rst b/doc/release/upcoming_changes/15769.improvement.rst new file mode 100644 index 000000000..3f70058f6 --- /dev/null +++ b/doc/release/upcoming_changes/15769.improvement.rst @@ -0,0 +1,15 @@ +Ability to disable madvise hugepages +------------------------------------ + +On Linux NumPy has previously added support for madavise +hugepages which can improve performance for very large arrays. +Unfortunately, on older Kernel versions this led to peformance +regressions, thus by default the support has been disabled on +kernels before version 4.6. To override the default, you can +use the environment variable:: + + NUMPY_MADVISE_HUGEPAGE=0 + +or set it to 1 to force enabling support. Note that this only makes +a difference if the operating system is set up to use madvise +transparent hugepage. diff --git a/doc/release/upcoming_changes/16068.compatibility.rst b/doc/release/upcoming_changes/16068.compatibility.rst new file mode 100644 index 000000000..6fe693386 --- /dev/null +++ b/doc/release/upcoming_changes/16068.compatibility.rst @@ -0,0 +1,11 @@ +C-Level string to datetime casts changed +---------------------------------------- +The C-level casts from strings were simplified. This changed +also fixes string to datetime and timedelta casts to behave +correctly (i.e. like Python casts using ``string_arr.astype("M8")`` +while previously the cast would behave like +``string_arr.astype(np.int_).astype("M8")``. +This only affects code using low-level C-API to do manual casts +(not full array casts) of single scalar values or using e.g. +``PyArray_GetCastFunc``, and should thus not affect the vast majority +of users. diff --git a/doc/release/upcoming_changes/16128.new_feature.rst b/doc/release/upcoming_changes/16128.new_feature.rst new file mode 100644 index 000000000..03b061c07 --- /dev/null +++ b/doc/release/upcoming_changes/16128.new_feature.rst @@ -0,0 +1,6 @@ +``equal_nan`` parameter for `numpy.array_equal` +------------------------------------------------ +The keyword argument ``equal_nan`` was added to `numpy.array_equal`. +``equal_nan`` is a boolean value that toggles whether or not ``nan`` values +are considered equal in comparison (default is ``False``). This matches API +used in related functions such as `numpy.isclose` and `numpy.allclose`. 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. |