diff options
Diffstat (limited to 'doc/source')
88 files changed, 1723 insertions, 1123 deletions
diff --git a/doc/source/conf.py b/doc/source/conf.py index 9546db5f2..ed5c11781 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -62,6 +62,13 @@ def replace_scalar_type_names(): replace_scalar_type_names() + +# As of NumPy 1.25, a deprecation of `str`/`bytes` attributes happens. +# For some reasons, the doc build accesses these, so ignore them. +import warnings +warnings.filterwarnings("ignore", "In the future.*NumPy scalar", FutureWarning) + + # ----------------------------------------------------------------------------- # General configuration # ----------------------------------------------------------------------------- @@ -156,7 +163,6 @@ def setup(app): # If we deemed it desirable, we could in future make these real modules, which # would make `from numpy.char import split` work. sys.modules['numpy.char'] = numpy.char -sys.modules['numpy.testing.dec'] = numpy.testing.dec # ----------------------------------------------------------------------------- # HTML output @@ -248,25 +254,39 @@ latex_documents = [ #latex_use_parts = False latex_elements = { - 'fontenc': r'\usepackage[LGR,T1]{fontenc}' } # Additional stuff for the LaTeX preamble. latex_elements['preamble'] = r''' +\newfontfamily\FontForChinese{FandolSong-Regular}[Extension=.otf] +\catcode`琴\active\protected\def琴{{\FontForChinese\string琴}} +\catcode`春\active\protected\def春{{\FontForChinese\string春}} +\catcode`鈴\active\protected\def鈴{{\FontForChinese\string鈴}} +\catcode`猫\active\protected\def猫{{\FontForChinese\string猫}} +\catcode`傅\active\protected\def傅{{\FontForChinese\string傅}} +\catcode`立\active\protected\def立{{\FontForChinese\string立}} +\catcode`业\active\protected\def业{{\FontForChinese\string业}} +\catcode`（\active\protected\def（{{\FontForChinese\string（}} +\catcode`）\active\protected\def）{{\FontForChinese\string）}} + % In the parameters section, place a newline after the Parameters -% header -\usepackage{xcolor} +% header. This is default with Sphinx 5.0.0+, so no need for +% the old hack then. +% Unfortunately sphinx.sty 5.0.0 did not bump its version date +% so we check rather sphinxpackagefootnote.sty (which exists +% since Sphinx 4.0.0). +\makeatletter +\@ifpackagelater{sphinxpackagefootnote}{2022/02/12} + {}% Sphinx >= 5.0.0, nothing to do + {% \usepackage{expdlist} \let\latexdescription=\description \def\description{\latexdescription{}{} \breaklabel} % but expdlist old LaTeX package requires fixes: % 1) remove extra space \usepackage{etoolbox} -\makeatletter \patchcmd\@item{{\@breaklabel} }{{\@breaklabel}}{}{} -\makeatother % 2) fix bug in expdlist's way of breaking the line after long item label -\makeatletter \def\breaklabel{% \def\@breaklabel{% \leavevmode\par @@ -274,6 +294,7 @@ latex_elements['preamble'] = r''' \def\leavevmode{\def\leavevmode{\unhbox\voidb@x}}% }% } + }% Sphinx < 5.0.0 (and assumed >= 4.0.0) \makeatother % Make Examples/etc section headers smaller and more compact diff --git a/doc/source/dev/alignment.rst b/doc/source/dev/alignment.rst index bb1198ebf..f2321d17b 100644 --- a/doc/source/dev/alignment.rst +++ b/doc/source/dev/alignment.rst @@ -3,7 +3,7 @@ .. _alignment: **************** -Memory Alignment +Memory alignment **************** NumPy alignment goals diff --git a/doc/source/dev/depending_on_numpy.rst b/doc/source/dev/depending_on_numpy.rst index 0582048cb..868b44162 100644 --- a/doc/source/dev/depending_on_numpy.rst +++ b/doc/source/dev/depending_on_numpy.rst @@ -48,70 +48,80 @@ job, either all warnings or otherwise at least ``DeprecationWarning`` and adapt your code. +.. _depending_on_numpy: + Adding a dependency on NumPy ---------------------------- Build-time dependency ~~~~~~~~~~~~~~~~~~~~~ +.. note:: + + Before NumPy 1.25, the NumPy C-API was *not* backwards compatible. This + means that when compiling with a NumPy version earlier than 1.25 you + have to compile with the oldest version you wish to support. + This can be done by using + `oldest-supported-numpy <https://github.com/scipy/oldest-supported-numpy/>`__. + Please see the NumPy 1.24 documentation at + `https://numpy.org/doc/1.24/dev/depending_on_numpy.html`__. + + If a package either uses the NumPy C API directly or it uses some other tool that depends on it like Cython or Pythran, NumPy is a *build-time* dependency -of the package. Because the NumPy ABI is only forward compatible, you must -build your own binaries (wheels or other package formats) against the lowest -NumPy version that you support (or an even older version). - -Picking the correct NumPy version to build against for each Python version and -platform can get complicated. There are a couple of ways to do this. -Build-time dependencies are specified in ``pyproject.toml`` (see PEP 517), -which is the file used to build wheels by PEP 517 compliant tools (e.g., -when using ``pip wheel``). - -You can specify everything manually in ``pyproject.toml``, or you can instead -rely on the `oldest-supported-numpy <https://github.com/scipy/oldest-supported-numpy/>`__ -metapackage. ``oldest-supported-numpy`` will specify the correct NumPy version -at build time for wheels, taking into account Python version, Python -implementation (CPython or PyPy), operating system and hardware platform. It -will specify the oldest NumPy version that supports that combination of -characteristics. Note: for platforms for which NumPy provides wheels on PyPI, -it will be the first version with wheels (even if some older NumPy version -happens to build). - -For conda-forge it's a little less complicated: there's dedicated handling for -NumPy in build-time and runtime dependencies, so typically this is enough -(see `here <https://conda-forge.org/docs/maintainer/knowledge_base.html#building-against-numpy>`__ for docs):: +of the package. - host: - - numpy - run: - - {{ pin_compatible('numpy') }} +By default, NumPy will expose an API that is backwards compatible with the +oldest NumPy version that supports the currently oldest compatible Python +version. NumPy 1.25.0 supports Python 3.9 and higher and NumPy 1.19 is the +first version to support Python 3.9. Thus, we guarantee that, when using +defaults, NumPy 1.25 will expose a C-API compatible with NumPy 1.19. +(the exact version is set within NumPy-internal header files). -.. note:: +NumPy is also forward compatible for all minor releases, but a major release +will require recompilation. + +The default behavior can be customized for example by adding:: - ``pip`` has ``--no-use-pep517`` and ``--no-build-isolation`` flags that may - ignore ``pyproject.toml`` or treat it differently - if users use those - flags, they are responsible for installing the correct build dependencies - themselves. + #define NPY_TARGET_VERSION NPY_1_22_API_VERSION - ``conda`` will always use ``-no-build-isolation``; dependencies for conda - builds are given in the conda recipe (``meta.yaml``), the ones in - ``pyproject.toml`` have no effect. +before including any NumPy headers (or the equivalent ``-D`` compiler flag) in +every extension module that requires the NumPy C-API. +This is mainly useful if you need to use newly added API at the cost of not +being compatible with older versions. - Please do not use ``setup_requires`` (it is deprecated and may invoke - ``easy_install``). +If for some reason you wish to compile for the currently installed NumPy +version by default you can add:: -Because for NumPy you have to care about ABI compatibility, you -specify the version with ``==`` to the lowest supported version. For your other -build dependencies you can probably be looser, however it's still important to -set lower and upper bounds for each dependency. It's fine to specify either a -range or a specific version for a dependency like ``wheel`` or ``setuptools``. + #ifndef NPY_TARGET_VERSION + #define NPY_TARGET_VERSION NPY_API_VERSION + #endif -.. warning:: +Which allows a user to override the default via ``-DNPY_TARGET_VERSION``. +This define must be consistent for each extension module (use of +``import_array()``) and also applies to the umath module. + +When you compile against NumPy, you should add the proper version restrictions +to your ``pyproject.toml`` (see PEP 517). Since your extension will not be +compatible with a new major release of NumPy and may not be compatible with +very old versions. + +For conda-forge packages, please see +`here <https://conda-forge.org/docs/maintainer/knowledge_base.html#building-against-numpy>`__. + +as of now, it is usually as easy as including:: + + host: + - numpy + run: + - {{ pin_compatible('numpy') }} + +.. note:: - Note that ``setuptools`` does major releases often and those may contain - changes that break ``numpy.distutils``, which will *not* be updated anymore - for new ``setuptools`` versions. It is therefore recommended to set an - upper version bound in your build configuration for the last known version - of ``setuptools`` that works with your build. + At the time of NumPy 1.25, NumPy 2.0 is expected to be the next release + of NumPy. The NumPy 2.0 release is expected to require a different pin, + since NumPy 2+ will be needed in order to be compatible with both NumPy + 1.x and 2.x. Runtime dependency & version ranges diff --git a/doc/source/dev/development_environment.rst b/doc/source/dev/development_environment.rst index 0ac02271d..aedc489d6 100644 --- a/doc/source/dev/development_environment.rst +++ b/doc/source/dev/development_environment.rst @@ -18,15 +18,36 @@ sources needs some additional steps, which are explained below. For the rest of this chapter we assume that you have set up your git repo as described in :ref:`using-git`. -.. note:: If you are having trouble building NumPy from source or setting up - your local development environment, you can try - to :ref:`build NumPy with Gitpod <development-gitpod>`. +.. note:: + + If you are having trouble building NumPy from source or setting up your + local development environment, you can try to build NumPy with GitHub + Codespaces. It allows you to create the correct development environment + right in your browser, reducing the need to install local development + environments and deal with incompatible dependencies. + + If you have good internet connectivity and want a temporary set-up, it is + often faster to work on NumPy in a Codespaces environment. For documentation + on how to get started with Codespaces, see + `the Codespaces docs <https://docs.github.com/en/codespaces>`__. + When creating a codespace for the ``numpy/numpy`` repository, the default + 2-core machine type works; 4-core will build and work a bit faster (but of + course at a cost of halving your number of free usage hours). Once your + codespace has started, you can run ``conda activate numpy-dev`` and your + development environment is completely set up - you can then follow the + relevant parts of the NumPy documentation to build, test, develop, write + docs, and contribute to NumPy. + .. _testing-builds: Testing builds -------------- +Before running the tests, first install the test dependencies:: + + $ python -m pip install -r test_requirements.txt + To build the development version of NumPy and run tests, spawn interactive shells with the Python import paths properly set up etc., do one of:: diff --git a/doc/source/dev/development_gitpod.rst b/doc/source/dev/development_gitpod.rst deleted file mode 100644 index 4e386867d..000000000 --- a/doc/source/dev/development_gitpod.rst +++ /dev/null @@ -1,271 +0,0 @@ -.. _development-gitpod: - - -Using Gitpod for NumPy development -================================== - -This section of the documentation will guide you through: - -* using GitPod for your NumPy development environment -* creating a personal fork of the NumPy repository on GitHub -* a quick tour of Gitpod and VSCode -* working on the NumPy documentation in Gitpod - -Gitpod ------- - -`Gitpod`_ is an open-source platform for automated and ready-to-code -development environments. It enables developers to describe their dev -environment as code and start instant and fresh development environments for -each new task directly from your browser. This reduces the need to install local -development environments and deal with incompatible dependencies. - -Gitpod GitHub integration -------------------------- - -To be able to use Gitpod, you will need to have the Gitpod app installed on your -GitHub account, so if -you do not have an account yet, you will need to create one first. - -Head over to the `Gitpod`_ website and click on the **Continue with GitHub** -button. You will be redirected to the GitHub authentication page. -You will then be asked to install the `Gitpod GitHub app <https://github.com/marketplace/gitpod-io>`_. - -Make sure to select **All repositories** access option to avoid issues with -permissions later on. Click on the green **Install** button - -.. image:: ./gitpod-imgs/installing-gitpod-io.png - :alt: Gitpod repository access and installation screenshot - -This will install the necessary hooks for the integration. - -Forking the NumPy repository ----------------------------- - -The best way to work on NumPy as a contributor is by making a fork of the -repository first. - -#. Browse to the `NumPy repository on GitHub`_ and `create your own fork`_. -#. Browse to your fork. Your fork will have a URL like - https://github.com/melissawm/NumPy, except with your GitHub username in place of ``melissawm``. - -Starting Gitpod ---------------- -Once you have authenticated to Gitpod through GitHub, you can install the -`Gitpod browser extension <https://www.gitpod.io/docs/browser-extension>`_ -which will add a **Gitpod** button next to the **Code** button in the -repository: - -.. image:: ./gitpod-imgs/NumPy-github.png - :alt: NumPy repository with Gitpod button screenshot - -#. If you install the extension - you can click the **Gitpod** button to start - a new workspace. - -#. Alternatively, if you do not want to install the browser extension, you can - visit https://gitpod.io/#https://github.com/USERNAME/NumPy replacing - ``USERNAME`` with your GitHub username. - -#. In both cases, this will open a new tab on your web browser and start - building your development environment. Please note this can take a few - minutes. - -#. Once the build is complete, you will be directed to your workspace, - including the VSCode editor and all the dependencies you need to work on - NumPy. The first time you start your workspace, you will notice that there - might be some actions running. This will ensure that you have a development - version of NumPy installed and that the docs are being pre-built for you. - -#. When your workspace is ready, you can :ref:`test the build<testing-builds>` by - entering:: - - $ python runtests.py -v - -``runtests.py`` is another script in the NumPy root directory. It runs a suite -of tests that make sure NumPy is working as it should, and ``-v`` activates the -``--verbose`` option to show all the test output. - -Quick workspace tour --------------------- -Gitpod uses VSCode as the editor. If you have not used this editor before, you -can check the Getting started `VSCode docs`_ to familiarize yourself with it. - -Your workspace will look similar to the image below: - -.. image:: ./gitpod-imgs/gitpod-workspace.png - :alt: Gitpod workspace screenshot - -.. note:: By default, VSCode initializes with a light theme. You can change to - a dark theme by with the keyboard shortcut :kbd:`Cmd-K Cmd-T` in Mac or - :kbd:`Ctrl-K Ctrl-T` in Linux and Windows. - -We have marked some important sections in the editor: - -#. Your current Python interpreter - by default, this is ``numpy-dev`` and - should be displayed in the status bar and on your terminal. You do not need - to activate the conda environment as this will always be activated for you. -#. Your current branch is always displayed in the status bar. You can also use - this button to change or create branches. -#. GitHub Pull Requests extension - you can use this to work with Pull Requests - from your workspace. -#. Marketplace extensions - we have added some essential extensions to the NumPy - Gitpod. Still, you can also install other extensions or syntax highlighting - themes for your user, and these will be preserved for you. -#. Your workspace directory - by default, it is ``/workspace/numpy``. **Do not - change this** as this is the only directory preserved in Gitpod. - -We have also pre-installed a few tools and VSCode extensions to help with the -development experience: - -* `GitHub CLI <https://cli.github.com/>`_ -* `VSCode rst extension <https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext>`_ -* `VSCode Live server extension <https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer>`_ -* `VSCode Gitlens extension <https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens>`_ -* `VSCode autodocstrings extension <https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring>`_ -* `VSCode Git Graph extension <https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph>`_ - -Development workflow with Gitpod --------------------------------- -The :ref:`development-workflow` section of this documentation contains -information regarding the NumPy development workflow. Make sure to check this -before working on your contributions. - -When using Gitpod, git is pre configured for you: - -#. You do not need to configure your git username, and email as this should be - done for you as you authenticated through GitHub. You can check the git - configuration with the command ``git config --list`` in your terminal. -#. As you started your workspace from your own NumPy fork, you will by default - have both ``upstream`` and ``origin`` added as remotes. You can verify this by - typing ``git remote`` on your terminal or by clicking on the **branch name** - on the status bar (see image below). - - .. image:: ./gitpod-imgs/NumPy-gitpod-branches.png - :alt: Gitpod workspace branches plugin screenshot - -Rendering the NumPy documentation ---------------------------------- -You can find the detailed documentation on how rendering the documentation with -Sphinx works in the :ref:`howto-build-docs` section. - -The documentation is pre-built during your workspace initialization. So once -this task is completed, you have two main options to render the documentation -in Gitpod. - -Option 1: Using Liveserve -~~~~~~~~~~~~~~~~~~~~~~~~~ - -#. View the documentation in ``NumPy/doc/build/html``. You can start with - ``index.html`` and browse, or you can jump straight to the file you're - interested in. -#. To see the rendered version of a page, you can right-click on the ``.html`` - file and click on **Open with Live Serve**. Alternatively, you can open the - file in the editor and click on the **Go live** button on the status bar. - - .. image:: ./gitpod-imgs/vscode-statusbar.png - :alt: Gitpod workspace VSCode start live serve screenshot - -#. A simple browser will open to the right-hand side of the editor. We recommend - closing it and click on the **Open in browser** button in the pop-up. -#. To stop the server click on the **Port: 5500** button on the status bar. - -Option 2: Using the rst extension -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A quick and easy way to see live changes in a ``.rst`` file as you work on it -uses the rst extension with docutils. - -.. note:: This will generate a simple live preview of the document without the - ``html`` theme, and some backlinks might not be added correctly. But it is an - easy and lightweight way to get instant feedback on your work. - -#. Open any of the source documentation files located in ``doc/source`` in the - editor. -#. Open VSCode Command Palette with :kbd:`Cmd-Shift-P` in Mac or - :kbd:`Ctrl-Shift-P` in Linux and Windows. Start typing "restructured" - and choose either "Open preview" or "Open preview to the Side". - - .. image:: ./gitpod-imgs/vscode-rst.png - :alt: Gitpod workspace VSCode open rst screenshot - -#. As you work on the document, you will see a live rendering of it on the editor. - - .. image:: ./gitpod-imgs/rst-rendering.png - :alt: Gitpod workspace VSCode rst rendering screenshot - -If you want to see the final output with the ``html`` theme you will need to -rebuild the docs with ``make html`` and use Live Serve as described in option 1. - -FAQ's and troubleshooting -------------------------- - -How long is my Gitpod workspace kept for? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Your stopped workspace will be kept for 14 days and deleted afterwards if you do -not use them. - -Can I come back to a previous workspace? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Yes, let's say you stepped away for a while and you want to carry on working on -your NumPy contributions. You need to visit https://gitpod.io/workspaces and -click on the workspace you want to spin up again. All your changes will be there -as you last left them. - -Can I install additional VSCode extensions? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Absolutely! Any extensions you installed will be installed in your own workspace -and preserved. - -I registered on Gitpod but I still cannot see a ``Gitpod`` button in my repositories. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Head to https://gitpod.io/integrations and make sure you are logged in. -Hover over GitHub and click on the three buttons that appear on the right. -Click on edit permissions and make sure you have ``user:email``, -``read:user``, and ``public_repo`` checked. Click on **Update Permissions** -and confirm the changes in the GitHub application page. - -.. image:: ./gitpod-imgs/gitpod-edit-permissions-gh.png - :alt: Gitpod integrations - edit GH permissions screenshot - -How long does my workspace stay active if I'm not using it? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you keep your workspace open in a browser tab but don't interact with it, -it will shut down after 30 minutes. If you close the browser tab, it will -shut down after 3 minutes. - -My terminal is blank - there is no cursor and it's completely unresponsive -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unfortunately this is a known-issue on Gitpod's side. You can sort this -issue in two ways: - -#. Create a new Gitpod workspace altogether. -#. Head to your `Gitpod dashboard <https://gitpod.io/workspaces>`_ and locate - the running workspace. Hover on it and click on the **three dots menu** - and then click on **Stop**. When the workspace is completely stopped you - can click on its name to restart it again. - -.. image:: ./gitpod-imgs/gitpod-dashboard-stop.png - :alt: Gitpod dashboard and workspace menu screenshot - -I authenticated through GitHub but I still cannot commit to the repository through Gitpod. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Head to https://gitpod.io/integrations and make sure you are logged in. -Hover over GitHub and click on the three buttons that appear on the right. -Click on edit permissions and make sure you have ``public_repo`` checked. -Click on **Update Permissions** and confirm the changes in the -GitHub application page. - -.. image:: ./gitpod-imgs/gitpod-edit-permissions-repo.png - :alt: Gitpod integrations - edit GH repository permissions screenshot - -.. _Gitpod: https://www.gitpod.io/ -.. _NumPy repository on GitHub: https://github.com/NumPy/NumPy -.. _create your own fork: https://help.github.com/en/articles/fork-a-repo -.. _VSCode docs: https://code.visualstudio.com/docs/getstarted/tips-and-tricks diff --git a/doc/source/dev/development_workflow.rst b/doc/source/dev/development_workflow.rst index 33bd0126d..9fa9c5809 100644 --- a/doc/source/dev/development_workflow.rst +++ b/doc/source/dev/development_workflow.rst @@ -200,12 +200,46 @@ sequences. In such cases you may explicitly skip CI by including one of these fragments in your commit message: * ``[skip ci]``: skip all CI -* ``[skip github]``: skip GitHub Actions "build numpy and run tests" jobs -* ``[skip actions]``: skip all GitHub Actions + + Only recommended if you are still not ready for the checks to run on your PR + (for example, if this is only a draft.) + +* ``[skip actions]``: skip GitHub Actions jobs + + `GitHub Actions <https://docs.github.com/actions>`__ is where most of the CI + checks are run, including the linter, benchmarking, running basic tests for + most architectures and OSs, and several compiler and CPU optimization + settings. + `See the configuration files for these checks. <https://github.com/numpy/numpy/tree/main/.github/workflows>`__ + * ``[skip travis]``: skip TravisCI jobs + + `TravisCI <https://www.travis-ci.com/>`__ will test your changes against + Python 3.9 on the PowerPC and s390x architectures. + `See the configuration file for these checks. <https://github.com/numpy/numpy/blob/main/.travis.yml>`__ + * ``[skip azp]``: skip Azure jobs + + `Azure <https://azure.microsoft.com/en-us/products/devops/pipelines>`__ is + where all comprehensive tests are run. This is an expensive run, and one you + could typically skip if you do documentation-only changes, for example. + `See the main configuration file for these checks. <https://github.com/numpy/numpy/blob/main/azure-pipelines.yml>`__ + * ``[skip circle]``: skip CircleCI jobs + `CircleCI <https://circleci.com/>`__ is where we build the documentation and + store the generated artifact for preview in each PR. This check will also run + all the docstrings examples and verify their results. If you don't make + documentation changes, but you make changes to a function's API, for example, + you may need to run these tests to verify that the doctests are still valid. + `See the configuration file for these checks. <https://github.com/numpy/numpy/blob/main/.circleci/config.yml>`__ + +* ``[skip cirrus]``: skip Cirrus jobs + + `CirrusCI <https://cirrus-ci.org/>`__ mostly triggers Linux aarch64 and MacOS Arm64 wheels + uploads. + `See the configuration file for these checks. <https://github.com/numpy/numpy/blob/main/.cirrus.star>`__ + Test building wheels ~~~~~~~~~~~~~~~~~~~~ @@ -481,6 +515,28 @@ usual:: git commit -am 'ENH - much better code' git push origin my-feature-branch # pushes directly into your repo + +Checkout changes from an existing pull request +============================================== + +If you want to test the changes in a pull request or continue the work in a +new pull request, the commits are to be cloned into a local branch in your +forked repository + +First ensure your upstream points to the main repo, as from :ref:`linking-to-upstream` + +Then, fetch the changes and create a local branch. Assuming ``$ID`` is the pull request number +and ``$BRANCHNAME`` is the name of the *new local* branch you wish to create:: + + git fetch upstream pull/$ID/head:$BRANCHNAME + +Checkout the newly created branch:: + + git checkout $BRANCHNAME + +You now have the changes in the pull request. + + Exploring your repository ========================= diff --git a/doc/source/dev/gitpod-imgs/NumPy-github.png b/doc/source/dev/gitpod-imgs/NumPy-github.png Binary files differdeleted file mode 100644 index 010b0fc5e..000000000 --- a/doc/source/dev/gitpod-imgs/NumPy-github.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/NumPy-gitpod-branches.png b/doc/source/dev/gitpod-imgs/NumPy-gitpod-branches.png Binary files differdeleted file mode 100644 index 3ee6c5f20..000000000 --- a/doc/source/dev/gitpod-imgs/NumPy-gitpod-branches.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/gitpod-dashboard-stop.png b/doc/source/dev/gitpod-imgs/gitpod-dashboard-stop.png Binary files differdeleted file mode 100644 index 40f137745..000000000 --- a/doc/source/dev/gitpod-imgs/gitpod-dashboard-stop.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-gh.png b/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-gh.png Binary files differdeleted file mode 100644 index 8955e907a..000000000 --- a/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-gh.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-repo.png b/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-repo.png Binary files differdeleted file mode 100644 index 8bfaff81c..000000000 --- a/doc/source/dev/gitpod-imgs/gitpod-edit-permissions-repo.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/gitpod-workspace.png b/doc/source/dev/gitpod-imgs/gitpod-workspace.png Binary files differdeleted file mode 100644 index a65c9bd7e..000000000 --- a/doc/source/dev/gitpod-imgs/gitpod-workspace.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/installing-gitpod-io.png b/doc/source/dev/gitpod-imgs/installing-gitpod-io.png Binary files differdeleted file mode 100644 index 97319a729..000000000 --- a/doc/source/dev/gitpod-imgs/installing-gitpod-io.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/rst-rendering.png b/doc/source/dev/gitpod-imgs/rst-rendering.png Binary files differdeleted file mode 100644 index 41cc305f3..000000000 --- a/doc/source/dev/gitpod-imgs/rst-rendering.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/vscode-rst.png b/doc/source/dev/gitpod-imgs/vscode-rst.png Binary files differdeleted file mode 100644 index 5b574c115..000000000 --- a/doc/source/dev/gitpod-imgs/vscode-rst.png +++ /dev/null diff --git a/doc/source/dev/gitpod-imgs/vscode-statusbar.png b/doc/source/dev/gitpod-imgs/vscode-statusbar.png Binary files differdeleted file mode 100644 index 3febbcee0..000000000 --- a/doc/source/dev/gitpod-imgs/vscode-statusbar.png +++ /dev/null diff --git a/doc/source/dev/gitwash/development_setup.rst b/doc/source/dev/gitwash/development_setup.rst index 4cb6c8358..75b7fb2f8 100644 --- a/doc/source/dev/gitwash/development_setup.rst +++ b/doc/source/dev/gitwash/development_setup.rst @@ -107,6 +107,10 @@ Make the local copy git submodule update --init +#. Pull from upstream to get latest tag information: :: + + git pull + ****************************************************************************** Look it over ****************************************************************************** diff --git a/doc/source/dev/gitwash/git_resources.rst b/doc/source/dev/gitwash/git_resources.rst index c41af762c..b6930f394 100644 --- a/doc/source/dev/gitwash/git_resources.rst +++ b/doc/source/dev/gitwash/git_resources.rst @@ -1,7 +1,7 @@ .. _git-resources: ========================= -Additional Git_ Resources +Additional Git_ resources ========================= Tutorials and summaries diff --git a/doc/source/dev/howto_build_docs.rst b/doc/source/dev/howto_build_docs.rst index 02a8820c9..b3d2e3055 100644 --- a/doc/source/dev/howto_build_docs.rst +++ b/doc/source/dev/howto_build_docs.rst @@ -14,22 +14,13 @@ in several different formats. Development environments ======================== -Before proceeding further it should be noted that the documentation is built with the ``make`` tool, -which is not natively available on Windows. MacOS or Linux users can jump -to :ref:`how-todoc.prerequisites`. It is recommended for Windows users to set up their development -environment on :ref:`Gitpod <development-gitpod>` or `Windows Subsystem -for Linux (WSL) <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. WSL is a good option -for a persistent local set-up. - -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 have good internet connectivity and want a temporary set-up, -it is often faster to build with Gitpod. Here are the in-depth instructions for -:ref:`building NumPy with Gitpod <development-gitpod>`. +Before proceeding further it should be noted that the documentation is built +with the ``make`` tool, which is not natively available on Windows. MacOS or +Linux users can jump to :ref:`how-todoc.prerequisites`. It is recommended for +Windows users to set up their development environment on +GitHub Codespaces (see :ref:`recommended-development-setup`) or +`Windows Subsystem for Linux (WSL) <https://learn.microsoft.com/en-us/windows/wsl/install>`_. +WSL is a good option for a persistent local set-up. .. _how-todoc.prerequisites: @@ -44,7 +35,8 @@ NumPy Since large parts of the main documentation are obtained from NumPy via ``import numpy`` and examining the docstrings, you will need to first -:ref:`build <building-from-source>` and install it so that the correct version is imported. +:ref:`build <development-environment>` and install it so that the correct version is +imported. NumPy has to be re-built and re-installed every time you fetch the latest version of the repository, before generating the documentation. This ensures that the NumPy version and the git repository version are in sync. diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index 93b57f7e2..b4479fa0d 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -45,7 +45,7 @@ Here's the short summary, complete TOC links are below: * Clone the project to your local computer:: - git clone https://github.com/your-username/numpy.git + git clone --recurse-submodules https://github.com/your-username/numpy.git * Change the directory:: @@ -60,12 +60,16 @@ Here's the short summary, complete TOC links are below: - ``upstream``, which refers to the ``numpy`` repository - ``origin``, which refers to your personal fork -2. Develop your contribution: - - * Pull the latest changes from upstream:: + * Pull the latest changes from upstream, including tags:: git checkout main - git pull upstream main + git pull upstream main --tags + + * Initialize numpy's submodules:: + + git submodule update --init + +2. Develop your contribution: * Create a branch for the feature you want to work on. Since the branch name will appear in the merge message, use a sensible name @@ -180,7 +184,7 @@ Guidelines get no response to your pull request within a week. .. _stylistic-guidelines: - + Stylistic Guidelines -------------------- @@ -210,7 +214,7 @@ Running NumPy's test suite locally requires some additional packages, such as in ``test_requirements.txt`` in the top-level directory, and can conveniently be installed with:: - pip install -r test_requirements.txt + $ python -m pip install -r test_requirements.txt Tests for a module should ideally cover all code in that module, i.e., statement coverage should be at 100%. @@ -258,7 +262,6 @@ The rest of the story Git Basics <gitwash/index> development_environment - development_gitpod howto_build_docs development_workflow development_advanced_debugging diff --git a/doc/source/dev/reviewer_guidelines.rst b/doc/source/dev/reviewer_guidelines.rst index 8d938319e..0ed9bf2e5 100644 --- a/doc/source/dev/reviewer_guidelines.rst +++ b/doc/source/dev/reviewer_guidelines.rst @@ -1,7 +1,7 @@ .. _reviewer-guidelines: =================== -Reviewer Guidelines +Reviewer guidelines =================== Reviewing open pull requests (PRs) helps move the project forward. We encourage @@ -101,7 +101,34 @@ For maintainers If a PR becomes inactive, maintainers may make larger changes. Remember, a PR is a collaboration between a contributor and a reviewer/s, sometimes a direct push is the best way to finish it. - + +API Changes +----------- +As mentioned most public API changes should be discussed ahead of time and +often with a wider audience (on the mailing list, or even through a NEP). + +For changes in the public C-API be aware that the NumPy C-API is backwards +compatible so that any addition must be ABI compatible with previous versions. +When it is not the case, you must add a guard. + +For example ``PyUnicodeScalarObject`` struct contains the following:: + + #if NPY_FEATURE_VERSION >= NPY_1_20_API_VERSION + char *buffer_fmt; + #endif + +Because the ``buffer_fmt`` field was added to its end in NumPy 1.20 (all +previous fields remained ABI compatible). +Similarly, any function added to the API table in +``numpy/core/code_generators/numpy_api.py`` must use the ``MinVersion`` +annotation. +For example:: + + 'PyDataMem_SetHandler': (304, MinVersion("1.22")), + +Header only functionality (such as a new macro) typically does not need to be +guarded. + GitHub Workflow --------------- diff --git a/doc/source/f2py/buildtools/cmake.rst b/doc/source/f2py/buildtools/cmake.rst index 8c654c73e..db64453b4 100644 --- a/doc/source/f2py/buildtools/cmake.rst +++ b/doc/source/f2py/buildtools/cmake.rst @@ -18,7 +18,7 @@ but this `extensive CMake collection`_ of resources is great. ``f2py`` is not particularly native or pleasant; and a more natural approach is to consider :ref:`f2py-skbuild` -Fibonacci Walkthrough (F77) +Fibonacci walkthrough (F77) =========================== Returning to the ``fib`` example from :ref:`f2py-getting-started` section. diff --git a/doc/source/f2py/buildtools/meson.rst b/doc/source/f2py/buildtools/meson.rst index 6b4392880..23b454ee5 100644 --- a/doc/source/f2py/buildtools/meson.rst +++ b/doc/source/f2py/buildtools/meson.rst @@ -23,7 +23,7 @@ build system like ``meson``. We will acquire this by: .. code-block:: bash - python -n numpy.f2py fib1.f -m fib2 + python -m numpy.f2py fib1.f -m fib2 Now, consider the following ``meson.build`` file for the ``fib`` and ``scalar`` examples from :ref:`f2py-getting-started` section: @@ -57,7 +57,7 @@ to lowercase the original Fortran file with say: .. code-block:: bash tr "[:upper:]" "[:lower:]" < fib1.f > fib1.f - python -n numpy.f2py fib1.f -m fib2 + python -m numpy.f2py fib1.f -m fib2 meson --wipe builddir meson compile -C builddir cd builddir @@ -68,7 +68,7 @@ possible. The easiest way to solve this is to let ``f2py`` deal with it: .. code-block:: bash - python -n numpy.f2py fib1.f -m fib2 --lower + python -m numpy.f2py fib1.f -m fib2 --lower meson --wipe builddir meson compile -C builddir cd builddir diff --git a/doc/source/f2py/code/ftype.f b/doc/source/f2py/code/ftype.f index cabbb9e2d..67d5a224b 100644 --- a/doc/source/f2py/code/ftype.f +++ b/doc/source/f2py/code/ftype.f @@ -4,6 +4,6 @@ C FILE: FTYPE.F Cf2py integer optional,intent(in) :: n = 13 REAL A,X COMMON /DATA/ A,X(3) - PRINT*, "IN FOO: N=",N," A=",A," X=[",X(1),X(2),X(3),"]" +C PRINT*, "IN FOO: N=",N," A=",A," X=[",X(1),X(2),X(3),"]" END C END OF FTYPE.F diff --git a/doc/source/f2py/f2py.getting-started.rst b/doc/source/f2py/f2py.getting-started.rst index da88b46f5..e96564814 100644 --- a/doc/source/f2py/f2py.getting-started.rst +++ b/doc/source/f2py/f2py.getting-started.rst @@ -18,6 +18,7 @@ following steps: * F2PY reads a signature file and writes a Python C/API module containing Fortran/C/Python bindings. + * F2PY compiles all sources and builds an extension module containing the wrappers. @@ -26,6 +27,13 @@ following steps: Fortran, SGI MIPSpro, Absoft, NAG, Compaq etc. For different build systems, see :ref:`f2py-bldsys`. + * Depending on your operating system, you may need to install the Python + development headers (which provide the file ``Python.h``) separately. In + Linux Debian-based distributions this package should be called ``python3-dev``, + in Fedora-based distributions it is ``python3-devel``. For macOS, depending + how Python was installed, your mileage may vary. In Windows, the headers are + typically installed already. + Depending on the situation, these steps can be carried out in a single composite command or step-by-step; in which case some steps can be omitted or combined with others. diff --git a/doc/source/f2py/windows/index.rst b/doc/source/f2py/windows/index.rst index c1e6b4128..980346667 100644 --- a/doc/source/f2py/windows/index.rst +++ b/doc/source/f2py/windows/index.rst @@ -56,7 +56,7 @@ PGI Compilers (commercial) Windows support`_. Cygwin (FOSS) - Can also be used for ``gfortran``. Howeve, the POSIX API compatibility layer provided by + Can also be used for ``gfortran``. However, the POSIX API compatibility layer provided by Cygwin is meant to compile UNIX software on Windows, instead of building native Windows programs. This means cross compilation is required. diff --git a/doc/source/f2py/windows/pgi.rst b/doc/source/f2py/windows/pgi.rst index 644259abe..28e25f016 100644 --- a/doc/source/f2py/windows/pgi.rst +++ b/doc/source/f2py/windows/pgi.rst @@ -22,7 +22,5 @@ as classic Flang requires a custom LLVM and compilation from sources. As of 29-01-2022, `PGI compiler toolchains`_ have been superseded by the Nvidia HPC SDK, with no `native Windows support`_. -However, - .. _PGI compiler toolchains: https://www.pgroup.com/index.html .. _native Windows support: https://developer.nvidia.com/nvidia-hpc-sdk-downloads#collapseFour diff --git a/doc/source/index.rst b/doc/source/index.rst index f31e730d7..5e31ec0a4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,7 +17,6 @@ NumPy documentation **Version**: |version| **Download documentation**: -`PDF Version <https://numpy.org/doc/stable/numpy-user.pdf>`_ | `Historical versions of documentation <https://numpy.org/doc/>`_ **Useful links**: diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 2f40423ee..34da83670 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -71,10 +71,11 @@ NumPy provides several hooks that classes can customize: The method should return either the result of the operation, or :obj:`NotImplemented` if the operation requested is not implemented. - If one of the input or output arguments has a :func:`__array_ufunc__` + If one of the input, output, or ``where`` arguments has a :func:`__array_ufunc__` method, it is executed *instead* of the ufunc. If more than one of the arguments implements :func:`__array_ufunc__`, they are tried in the - order: subclasses before superclasses, inputs before outputs, otherwise + order: subclasses before superclasses, inputs before outputs, + outputs before ``where``, otherwise left to right. The first routine returning something other than :obj:`NotImplemented` determines the result. If all of the :func:`__array_ufunc__` operations return :obj:`NotImplemented`, a @@ -162,15 +163,6 @@ NumPy provides several hooks that classes can customize: .. versionadded:: 1.16 - .. note:: - - - In NumPy 1.17, the protocol is enabled by default, but can be disabled - with ``NUMPY_EXPERIMENTAL_ARRAY_FUNCTION=0``. - - In NumPy 1.16, you need to set the environment variable - ``NUMPY_EXPERIMENTAL_ARRAY_FUNCTION=1`` before importing NumPy to use - NumPy function overrides. - - Eventually, expect to ``__array_function__`` to always be enabled. - - ``func`` is an arbitrary callable exposed by NumPy's public API, which was called in the form ``func(*args, **kwargs)``. - ``types`` is a collection :py:class:`collections.abc.Collection` diff --git a/doc/source/reference/arrays.dtypes.rst b/doc/source/reference/arrays.dtypes.rst index 8606bc8f1..f4218ce86 100644 --- a/doc/source/reference/arrays.dtypes.rst +++ b/doc/source/reference/arrays.dtypes.rst @@ -188,10 +188,10 @@ Built-in Python types (all others) :class:`object_` ================ =============== - Note that ``str`` refers to either null terminated bytes or unicode strings - depending on the Python version. In code targeting both Python 2 and 3 - ``np.unicode_`` should be used as a dtype for strings. - See :ref:`Note on string types<string-dtype-note>`. + Note that ``str`` corresponds to UCS4 encoded unicode strings, while + ``string`` is an alias to ``bytes_``. The name ``np.unicode_`` is also + available as an alias to ``np.str_``, see :ref:`Note on string + types<string-dtype-note>`. .. admonition:: Example @@ -263,11 +263,11 @@ Array-protocol type strings (see :ref:`arrays.interface`) .. admonition:: Note on string types - For backward compatibility with Python 2 the ``S`` and ``a`` typestrings - remain zero-terminated bytes and `numpy.string_` continues to alias - `numpy.bytes_`. To use actual strings in Python 3 use ``U`` or `numpy.str_`. - For signed bytes that do not need zero-termination ``b`` or ``i1`` can be - used. + For backward compatibility with existing code originally written to support + Python 2, ``S`` and ``a`` typestrings are zero-terminated bytes and + `numpy.string_` continues to alias `numpy.bytes_`. For unicode strings, + use ``U``, `numpy.str_`, or `numpy.unicode_`. For signed bytes that do not + need zero-termination ``b`` or ``i1`` can be used. String with comma-separated fields A short-hand notation for specifying the format of a structured data type is diff --git a/doc/source/reference/arrays.nditer.rst b/doc/source/reference/arrays.nditer.rst index 8cabc1a06..fb1c91a07 100644 --- a/doc/source/reference/arrays.nditer.rst +++ b/doc/source/reference/arrays.nditer.rst @@ -3,7 +3,7 @@ .. _arrays.nditer: ********************* -Iterating Over Arrays +Iterating over arrays ********************* .. note:: @@ -23,7 +23,7 @@ can accelerate the inner loop in Cython. Since the Python exposure of iterator API, these ideas will also provide help working with array iteration from C or C++. -Single Array Iteration +Single array iteration ====================== The most basic task that can be done with the :class:`nditer` is to @@ -64,7 +64,7 @@ namely the order they are stored in memory, whereas the elements of `a.T.copy(order='C')` get visited in a different order because they have been put into a different memory layout. -Controlling Iteration Order +Controlling iteration order --------------------------- There are times when it is important to visit the elements of an array @@ -88,7 +88,7 @@ order='C' for C order and order='F' for Fortran order. .. _nditer-context-manager: -Modifying Array Values +Modifying array values ---------------------- By default, the :class:`nditer` treats the input operand as a read-only @@ -128,7 +128,7 @@ note that prior to 1.15, :class:`nditer` was not a context manager and did not have a `close` method. Instead it relied on the destructor to initiate the writeback of the buffer. -Using an External Loop +Using an external loop ---------------------- In all the examples so far, the elements of `a` are provided by the @@ -161,7 +161,7 @@ elements each. ... [0 3] [1 4] [2 5] -Tracking an Index or Multi-Index +Tracking an index or multi-index -------------------------------- During iteration, you may want to use the index of the current @@ -210,7 +210,7 @@ raise an exception. File "<stdin>", line 1, in <module> ValueError: Iterator flag EXTERNAL_LOOP cannot be used if an index or multi-index is being tracked -Alternative Looping and Element Access +Alternative looping and element access -------------------------------------- To make its properties more readily accessible during iteration, @@ -246,7 +246,7 @@ produce identical results to the ones in the previous section. array([[ 0, 1, 2], [-1, 0, 1]]) -Buffering the Array Elements +Buffering the array elements ---------------------------- When forcing an iteration order, we observed that the external loop @@ -274,7 +274,7 @@ is enabled. ... [0 3 1 4 2 5] -Iterating as a Specific Data Type +Iterating as a specific data type --------------------------------- There are times when it is necessary to treat an array as a different @@ -382,7 +382,7 @@ would violate the casting rule. File "<stdin>", line 2, in <module> TypeError: Iterator requested dtype could not be cast from dtype('float64') to dtype('int64'), the operand 0 dtype, according to the rule 'same_kind' -Broadcasting Array Iteration +Broadcasting array iteration ============================ NumPy has a set of rules for dealing with arrays that have differing @@ -417,7 +417,7 @@ which includes the input shapes to help diagnose the problem. ... ValueError: operands could not be broadcast together with shapes (2,) (2,3) -Iterator-Allocated Output Arrays +Iterator-allocated output arrays -------------------------------- A common case in NumPy functions is to have outputs allocated based diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst index 30d7be9f9..4dba54d6b 100644 --- a/doc/source/reference/arrays.scalars.rst +++ b/doc/source/reference/arrays.scalars.rst @@ -293,6 +293,10 @@ elements the data type consists of.) :members: __init__ :exclude-members: __init__ +.. autoclass:: numpy.character + :members: __init__ + :exclude-members: __init__ + .. autoclass:: numpy.bytes_ :members: __init__ :exclude-members: __init__ @@ -333,8 +337,6 @@ are also provided. .. note that these are documented with ..attribute because that is what autoclass does for aliases under the hood. -.. autoclass:: numpy.bool8 - .. attribute:: int8 int16 int32 diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst index 8772b494c..038702bcf 100644 --- a/doc/source/reference/c-api/array.rst +++ b/doc/source/reference/c-api/array.rst @@ -423,7 +423,7 @@ From other objects :c:data:`NPY_ARRAY_FORCECAST` is present in ``flags``, this call will generate an error if the data type cannot be safely obtained from the object. If you want to use - ``NULL`` for the *dtype* and ensure the array is notswapped then + ``NULL`` for the *dtype* and ensure the array is not swapped then use :c:func:`PyArray_CheckFromAny`. A value of 0 for either of the depth parameters causes the parameter to be ignored. Any of the following array flags can be added (*e.g.* using \|) to get the @@ -548,22 +548,6 @@ From other objects :c:data:`NPY_ARRAY_F_CONTIGUOUS` \| :c:data:`NPY_ARRAY_WRITEABLE` \| :c:data:`NPY_ARRAY_ALIGNED` \| :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` -.. c:function:: int PyArray_GetArrayParamsFromObject( \ - PyObject* op, PyArray_Descr* requested_dtype, npy_bool writeable, \ - PyArray_Descr** out_dtype, int* out_ndim, npy_intp* out_dims, \ - PyArrayObject** out_arr, PyObject* context) - - .. deprecated:: NumPy 1.19 - - Unless NumPy is made aware of an issue with this, this function - is scheduled for rapid removal without replacement. - - .. versionchanged:: NumPy 1.19 - - `context` is never used. Its use results in an error. - - .. versionadded:: 1.6 - .. c:function:: PyObject* PyArray_CheckFromAny( \ PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, \ int requirements, PyObject* context) @@ -1165,29 +1149,13 @@ Converting data types .. versionadded:: 1.6 - This applies type promotion to all the inputs, - using the NumPy rules for combining scalars and arrays, to - determine the output type of a set of operands. This is the - same result type that ufuncs produce. The specific algorithm - used is as follows. - - Categories are determined by first checking which of boolean, - integer (int/uint), or floating point (float/complex) the maximum - kind of all the arrays and the scalars are. + This applies type promotion to all the input arrays and dtype + objects, using the NumPy rules for combining scalars and arrays, to + determine the output type for an operation with the given set of + operands. This is the same result type that ufuncs produce. - If there are only scalars or the maximum category of the scalars - is higher than the maximum category of the arrays, - the data types are combined with :c:func:`PyArray_PromoteTypes` - to produce the return value. - - Otherwise, PyArray_MinScalarType is called on each array, and - the resulting data types are all combined with - :c:func:`PyArray_PromoteTypes` to produce the return value. - - The set of int values is not a subset of the uint values for types - with the same number of bits, something not reflected in - :c:func:`PyArray_MinScalarType`, but handled as a special case in - PyArray_ResultType. + See the documentation of :func:`numpy.result_type` for more + detail about the type promotion algorithm. .. c:function:: int PyArray_ObjectType(PyObject* op, int mintype) @@ -1202,17 +1170,6 @@ Converting data types return value is the enumerated typenumber that represents the data-type that *op* should have. -.. c:function:: void PyArray_ArrayType( \ - PyObject* op, PyArray_Descr* mintype, PyArray_Descr* outtype) - - This function is superseded by :c:func:`PyArray_ResultType`. - - This function works similarly to :c:func:`PyArray_ObjectType` (...) - except it handles flexible arrays. The *mintype* argument can have - an itemsize member and the *outtype* argument will have an - itemsize member at least as big but perhaps bigger depending on - the object *op*. - .. c:function:: PyArrayObject** PyArray_ConvertToCommonType( \ PyObject* op, int* n) @@ -1490,7 +1447,7 @@ of the constant names is deprecated in 1.7. :c:func:`PyArray_FromAny` and a copy had to be made of some other array (and the user asked for this flag to be set in such a situation). The base attribute then points to the "misbehaved" - array (which is set read_only). :c:func`PyArray_ResolveWritebackIfCopy` + array (which is set read_only). :c:func:`PyArray_ResolveWritebackIfCopy` will copy its contents back to the "misbehaved" array (casting if necessary) and will reset the "misbehaved" array to :c:data:`NPY_ARRAY_WRITEABLE`. If the "misbehaved" array was not @@ -2276,7 +2233,7 @@ Array Functions output array must have the correct shape, type, and be C-contiguous, or an exception is raised. -.. c:function:: PyObject* PyArray_EinsteinSum( \ +.. c:function:: PyArrayObject* PyArray_EinsteinSum( \ char* subscripts, npy_intp nop, PyArrayObject** op_in, \ PyArray_Descr* dtype, NPY_ORDER order, NPY_CASTING casting, \ PyArrayObject* out) @@ -2475,9 +2432,9 @@ As of NumPy 1.6.0, these array iterators are superseded by the new array iterator, :c:type:`NpyIter`. An array iterator is a simple way to access the elements of an -N-dimensional array quickly and efficiently. Section `2 -<#sec-array-iterator>`__ provides more description and examples of -this useful approach to looping over an array. +N-dimensional array quickly and efficiently, as seen in :ref:`the +example <iteration-example>` which provides more description +of this useful approach to looping over an array from C. .. c:function:: PyObject* PyArray_IterNew(PyObject* arr) @@ -3378,7 +3335,7 @@ Memory management .. c:function:: int PyArray_ResolveWritebackIfCopy(PyArrayObject* obj) - If ``obj.flags`` has :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, this function + If ``obj->flags`` has :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, this function clears the flags, `DECREF` s `obj->base` and makes it writeable, and sets ``obj->base`` to NULL. It then copies ``obj->data`` to `obj->base->data`, and returns the error state of @@ -3608,29 +3565,17 @@ Miscellaneous Macros Returns the reference count of any Python object. -.. c:function:: void PyArray_DiscardWritebackIfCopy(PyObject* obj) +.. c:function:: void PyArray_DiscardWritebackIfCopy(PyArrayObject* obj) - If ``obj.flags`` has :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, this function + If ``obj->flags`` has :c:data:`NPY_ARRAY_WRITEBACKIFCOPY`, this function clears the flags, `DECREF` s `obj->base` and makes it writeable, and sets ``obj->base`` to NULL. In - contrast to :c:func:`PyArray_DiscardWritebackIfCopy` it makes no attempt - to copy the data from `obj->base` This undoes + contrast to :c:func:`PyArray_ResolveWritebackIfCopy` it makes no attempt + to copy the data from `obj->base`. This undoes :c:func:`PyArray_SetWritebackIfCopyBase`. Usually this is called after an error when you are finished with ``obj``, just before ``Py_DECREF(obj)``. It may be called multiple times, or with ``NULL`` input. -.. c:function:: void PyArray_XDECREF_ERR(PyObject* obj) - - Deprecated in 1.14, use :c:func:`PyArray_DiscardWritebackIfCopy` - followed by ``Py_XDECREF`` - - DECREF's an array object which may have the - :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` - flag set without causing the contents to be copied back into the - original array. Resets the :c:data:`NPY_ARRAY_WRITEABLE` flag on the base - object. This is useful for recovering from an error condition when - writeback semantics are used, but will lead to wrong results. - Enumerated Types ~~~~~~~~~~~~~~~~ diff --git a/doc/source/reference/c-api/data_memory.rst b/doc/source/reference/c-api/data_memory.rst index 2084ab5d0..cab587efc 100644 --- a/doc/source/reference/c-api/data_memory.rst +++ b/doc/source/reference/c-api/data_memory.rst @@ -159,3 +159,87 @@ A better technique would be to use a ``PyCapsule`` as a base object: return NULL; } ... + +Example of memory tracing with ``np.lib.tracemalloc_domain`` +------------------------------------------------------------ + +Note that since Python 3.6 (or newer), the builtin ``tracemalloc`` module can be used to +track allocations inside NumPy. NumPy places its CPU memory allocations into the +``np.lib.tracemalloc_domain`` domain. +For additional information, check: `https://docs.python.org/3/library/tracemalloc.html`. + +Here is an example on how to use ``np.lib.tracemalloc_domain``: + +.. code-block:: python + + """ + The goal of this example is to show how to trace memory + from an application that has NumPy and non-NumPy sections. + We only select the sections using NumPy related calls. + """ + + import tracemalloc + import numpy as np + + # Flag to determine if we select NumPy domain + use_np_domain = True + + nx = 300 + ny = 500 + + # Start to trace memory + tracemalloc.start() + + # Section 1 + # --------- + + # NumPy related call + a = np.zeros((nx,ny)) + + # non-NumPy related call + b = [i**2 for i in range(nx*ny)] + + snapshot1 = tracemalloc.take_snapshot() + # We filter the snapshot to only select NumPy related calls + np_domain = np.lib.tracemalloc_domain + dom_filter = tracemalloc.DomainFilter(inclusive=use_np_domain, + domain=np_domain) + snapshot1 = snapshot1.filter_traces([dom_filter]) + top_stats1 = snapshot1.statistics('traceback') + + print("================ SNAPSHOT 1 =================") + for stat in top_stats1: + print(f"{stat.count} memory blocks: {stat.size / 1024:.1f} KiB") + print(stat.traceback.format()[-1]) + + # Clear traces of memory blocks allocated by Python + # before moving to the next section. + tracemalloc.clear_traces() + + # Section 2 + #---------- + + # We are only using NumPy + c = np.sum(a*a) + + snapshot2 = tracemalloc.take_snapshot() + top_stats2 = snapshot2.statistics('traceback') + + print() + print("================ SNAPSHOT 2 =================") + for stat in top_stats2: + print(f"{stat.count} memory blocks: {stat.size / 1024:.1f} KiB") + print(stat.traceback.format()[-1]) + + tracemalloc.stop() + + print() + print("============================================") + print("\nTracing Status : ", tracemalloc.is_tracing()) + + try: + print("\nTrying to Take Snapshot After Tracing is Stopped.") + snap = tracemalloc.take_snapshot() + except Exception as e: + print("Exception : ", e) + diff --git a/doc/source/reference/c-api/deprecations.rst b/doc/source/reference/c-api/deprecations.rst index 5b1abc6f2..d805421f2 100644 --- a/doc/source/reference/c-api/deprecations.rst +++ b/doc/source/reference/c-api/deprecations.rst @@ -58,3 +58,7 @@ On compilers which support a #warning mechanism, NumPy issues a compiler warning if you do not define the symbol NPY_NO_DEPRECATED_API. This way, the fact that there are deprecations will be flagged for third-party developers who may not have read the release notes closely. + +Note that defining NPY_NO_DEPRECATED_API is not sufficient to make your +extension ABI compatible with a given NumPy version. See +:ref:`for-downstream-package-authors`. diff --git a/doc/source/reference/c-api/dtype.rst b/doc/source/reference/c-api/dtype.rst index 642f62749..bdd5a6f55 100644 --- a/doc/source/reference/c-api/dtype.rst +++ b/doc/source/reference/c-api/dtype.rst @@ -25,161 +25,161 @@ select the precision desired. Enumerated Types ---------------- -.. c:enumerator:: NPY_TYPES +.. c:enum:: NPY_TYPES -There is a list of enumerated types defined providing the basic 24 -data types plus some useful generic names. Whenever the code requires -a type number, one of these enumerated types is requested. The types -are all called ``NPY_{NAME}``: + There is a list of enumerated types defined providing the basic 24 + data types plus some useful generic names. Whenever the code requires + a type number, one of these enumerated types is requested. The types + are all called ``NPY_{NAME}``: -.. c:enumerator:: NPY_BOOL + .. c:enumerator:: NPY_BOOL - The enumeration value for the boolean type, stored as one byte. - It may only be set to the values 0 and 1. + The enumeration value for the boolean type, stored as one byte. + It may only be set to the values 0 and 1. -.. c:enumerator:: NPY_BYTE -.. c:enumerator:: NPY_INT8 + .. c:enumerator:: NPY_BYTE + .. c:enumerator:: NPY_INT8 - The enumeration value for an 8-bit/1-byte signed integer. + The enumeration value for an 8-bit/1-byte signed integer. -.. c:enumerator:: NPY_SHORT -.. c:enumerator:: NPY_INT16 + .. c:enumerator:: NPY_SHORT + .. c:enumerator:: NPY_INT16 - The enumeration value for a 16-bit/2-byte signed integer. + The enumeration value for a 16-bit/2-byte signed integer. -.. c:enumerator:: NPY_INT -.. c:enumerator:: NPY_INT32 + .. c:enumerator:: NPY_INT + .. c:enumerator:: NPY_INT32 - The enumeration value for a 32-bit/4-byte signed integer. + The enumeration value for a 32-bit/4-byte signed integer. -.. c:enumerator:: NPY_LONG + .. c:enumerator:: NPY_LONG - Equivalent to either NPY_INT or NPY_LONGLONG, depending on the - platform. + Equivalent to either NPY_INT or NPY_LONGLONG, depending on the + platform. -.. c:enumerator:: NPY_LONGLONG -.. c:enumerator:: NPY_INT64 + .. c:enumerator:: NPY_LONGLONG + .. c:enumerator:: NPY_INT64 - The enumeration value for a 64-bit/8-byte signed integer. + The enumeration value for a 64-bit/8-byte signed integer. -.. c:enumerator:: NPY_UBYTE -.. c:enumerator:: NPY_UINT8 + .. c:enumerator:: NPY_UBYTE + .. c:enumerator:: NPY_UINT8 - The enumeration value for an 8-bit/1-byte unsigned integer. + The enumeration value for an 8-bit/1-byte unsigned integer. -.. c:enumerator:: NPY_USHORT -.. c:enumerator:: NPY_UINT16 + .. c:enumerator:: NPY_USHORT + .. c:enumerator:: NPY_UINT16 - The enumeration value for a 16-bit/2-byte unsigned integer. + The enumeration value for a 16-bit/2-byte unsigned integer. -.. c:enumerator:: NPY_UINT -.. c:enumerator:: NPY_UINT32 + .. c:enumerator:: NPY_UINT + .. c:enumerator:: NPY_UINT32 - The enumeration value for a 32-bit/4-byte unsigned integer. + The enumeration value for a 32-bit/4-byte unsigned integer. -.. c:enumerator:: NPY_ULONG + .. c:enumerator:: NPY_ULONG - Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on the - platform. + Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on the + platform. -.. c:enumerator:: NPY_ULONGLONG -.. c:enumerator:: NPY_UINT64 + .. c:enumerator:: NPY_ULONGLONG + .. c:enumerator:: NPY_UINT64 - The enumeration value for a 64-bit/8-byte unsigned integer. + The enumeration value for a 64-bit/8-byte unsigned integer. -.. c:enumerator:: NPY_HALF -.. c:enumerator:: NPY_FLOAT16 + .. c:enumerator:: NPY_HALF + .. c:enumerator:: NPY_FLOAT16 - The enumeration value for a 16-bit/2-byte IEEE 754-2008 compatible floating - point type. + The enumeration value for a 16-bit/2-byte IEEE 754-2008 compatible floating + point type. -.. c:enumerator:: NPY_FLOAT -.. c:enumerator:: NPY_FLOAT32 + .. c:enumerator:: NPY_FLOAT + .. c:enumerator:: NPY_FLOAT32 - The enumeration value for a 32-bit/4-byte IEEE 754 compatible floating - point type. + The enumeration value for a 32-bit/4-byte IEEE 754 compatible floating + point type. -.. c:enumerator:: NPY_DOUBLE -.. c:enumerator:: NPY_FLOAT64 + .. c:enumerator:: NPY_DOUBLE + .. c:enumerator:: NPY_FLOAT64 - The enumeration value for a 64-bit/8-byte IEEE 754 compatible floating - point type. + The enumeration value for a 64-bit/8-byte IEEE 754 compatible floating + point type. -.. c:enumerator:: NPY_LONGDOUBLE + .. c:enumerator:: NPY_LONGDOUBLE - The enumeration value for a platform-specific floating point type which is - at least as large as NPY_DOUBLE, but larger on many platforms. + The enumeration value for a platform-specific floating point type which is + at least as large as NPY_DOUBLE, but larger on many platforms. -.. c:enumerator:: NPY_CFLOAT -.. c:enumerator:: NPY_COMPLEX64 + .. c:enumerator:: NPY_CFLOAT + .. c:enumerator:: NPY_COMPLEX64 - The enumeration value for a 64-bit/8-byte complex type made up of - two NPY_FLOAT values. + The enumeration value for a 64-bit/8-byte complex type made up of + two NPY_FLOAT values. -.. c:enumerator:: NPY_CDOUBLE -.. c:enumerator:: NPY_COMPLEX128 + .. c:enumerator:: NPY_CDOUBLE + .. c:enumerator:: NPY_COMPLEX128 - The enumeration value for a 128-bit/16-byte complex type made up of - two NPY_DOUBLE values. + The enumeration value for a 128-bit/16-byte complex type made up of + two NPY_DOUBLE values. -.. c:enumerator:: NPY_CLONGDOUBLE + .. c:enumerator:: NPY_CLONGDOUBLE - The enumeration value for a platform-specific complex floating point - type which is made up of two NPY_LONGDOUBLE values. + The enumeration value for a platform-specific complex floating point + type which is made up of two NPY_LONGDOUBLE values. -.. c:enumerator:: NPY_DATETIME + .. c:enumerator:: NPY_DATETIME - The enumeration value for a data type which holds dates or datetimes with - a precision based on selectable date or time units. + The enumeration value for a data type which holds dates or datetimes with + a precision based on selectable date or time units. -.. c:enumerator:: NPY_TIMEDELTA + .. c:enumerator:: NPY_TIMEDELTA - The enumeration value for a data type which holds lengths of times in - integers of selectable date or time units. + The enumeration value for a data type which holds lengths of times in + integers of selectable date or time units. -.. c:enumerator:: NPY_STRING + .. c:enumerator:: NPY_STRING - The enumeration value for ASCII strings of a selectable size. The - strings have a fixed maximum size within a given array. + The enumeration value for ASCII strings of a selectable size. The + strings have a fixed maximum size within a given array. -.. c:enumerator:: NPY_UNICODE + .. c:enumerator:: NPY_UNICODE - The enumeration value for UCS4 strings of a selectable size. The - strings have a fixed maximum size within a given array. + The enumeration value for UCS4 strings of a selectable size. The + strings have a fixed maximum size within a given array. -.. c:enumerator:: NPY_OBJECT + .. c:enumerator:: NPY_OBJECT - The enumeration value for references to arbitrary Python objects. + The enumeration value for references to arbitrary Python objects. -.. c:enumerator:: NPY_VOID + .. c:enumerator:: NPY_VOID - Primarily used to hold struct dtypes, but can contain arbitrary - binary data. + Primarily used to hold struct dtypes, but can contain arbitrary + binary data. -Some useful aliases of the above types are + Some useful aliases of the above types are -.. c:enumerator:: NPY_INTP + .. c:enumerator:: NPY_INTP - The enumeration value for a signed integer type which is the same - size as a (void \*) pointer. This is the type used by all - arrays of indices. + The enumeration value for a signed integer type which is the same + size as a (void \*) pointer. This is the type used by all + arrays of indices. -.. c:enumerator:: NPY_UINTP + .. c:enumerator:: NPY_UINTP - The enumeration value for an unsigned integer type which is the - same size as a (void \*) pointer. + The enumeration value for an unsigned integer type which is the + same size as a (void \*) pointer. -.. c:enumerator:: NPY_MASK + .. c:enumerator:: NPY_MASK - The enumeration value of the type used for masks, such as with - the :c:data:`NPY_ITER_ARRAYMASK` iterator flag. This is equivalent - to :c:data:`NPY_UINT8`. + The enumeration value of the type used for masks, such as with + the :c:data:`NPY_ITER_ARRAYMASK` iterator flag. This is equivalent + to :c:data:`NPY_UINT8`. -.. c:enumerator:: NPY_DEFAULT_TYPE + .. c:enumerator:: NPY_DEFAULT_TYPE - The default type to use when no dtype is explicitly specified, for - example when calling np.zero(shape). This is equivalent to - :c:data:`NPY_DOUBLE`. + The default type to use when no dtype is explicitly specified, for + example when calling np.zero(shape). This is equivalent to + :c:data:`NPY_DOUBLE`. Other useful related constants are diff --git a/doc/source/reference/c-api/iterator.rst b/doc/source/reference/c-api/iterator.rst index 09c61e5fc..92e3e435b 100644 --- a/doc/source/reference/c-api/iterator.rst +++ b/doc/source/reference/c-api/iterator.rst @@ -26,8 +26,10 @@ which may be of interest for those using this C API. In many instances, testing out ideas by creating the iterator in Python is a good idea before writing the C iteration code. +.. _iteration-example: + Iteration Example ------------------------- +----------------- The best way to become familiar with the iterator is to look at its usage within the NumPy codebase itself. For example, here is a slightly diff --git a/doc/source/reference/c-api/types-and-structures.rst b/doc/source/reference/c-api/types-and-structures.rst index 34437bd30..cff1b3d38 100644 --- a/doc/source/reference/c-api/types-and-structures.rst +++ b/doc/source/reference/c-api/types-and-structures.rst @@ -122,7 +122,7 @@ PyArray_Type and PyArrayObject ``ndarraytypes.h`` points to this data member. :c:data:`NPY_MAXDIMS` is the largest number of dimensions for any array. - .. c:member:: npy_intp dimensions + .. c:member:: npy_intp *dimensions An array of integers providing the shape in each dimension as long as nd :math:`\geq` 1. The integer is always large enough @@ -225,7 +225,7 @@ PyArrayDescr_Type and PyArray_Descr - Never declare a non-pointer instance of the struct - Never perform pointer arithmetic - - Never use ``sizof(PyArray_Descr)`` + - Never use ``sizeof(PyArray_Descr)`` It has the following structure: @@ -285,83 +285,16 @@ PyArrayDescr_Type and PyArray_Descr array like behavior. Each bit in this member is a flag which are named as: - .. c:member:: int alignment - - Non-NULL if this type is an array (C-contiguous) of some other type - - -.. - dedented to allow internal linking, pending a refactoring - -.. c:macro:: NPY_ITEM_REFCOUNT - - Indicates that items of this data-type must be reference - counted (using :c:func:`Py_INCREF` and :c:func:`Py_DECREF` ). - - .. c:macro:: NPY_ITEM_HASOBJECT - - Same as :c:data:`NPY_ITEM_REFCOUNT`. - -.. - dedented to allow internal linking, pending a refactoring - -.. c:macro:: NPY_LIST_PICKLE - - Indicates arrays of this data-type must be converted to a list - before pickling. - -.. c:macro:: NPY_ITEM_IS_POINTER - - Indicates the item is a pointer to some other data-type - -.. c:macro:: NPY_NEEDS_INIT - - Indicates memory for this data-type must be initialized (set - to 0) on creation. - -.. c:macro:: NPY_NEEDS_PYAPI - - Indicates this data-type requires the Python C-API during - access (so don't give up the GIL if array access is going to - be needed). - -.. c:macro:: NPY_USE_GETITEM - - On array access use the ``f->getitem`` function pointer - instead of the standard conversion to an array scalar. Must - use if you don't define an array scalar to go along with - the data-type. - -.. c:macro:: NPY_USE_SETITEM - - When creating a 0-d array from an array scalar use - ``f->setitem`` instead of the standard copy from an array - scalar. Must use if you don't define an array scalar to go - along with the data-type. - - .. c:macro:: NPY_FROM_FIELDS - - The bits that are inherited for the parent data-type if these - bits are set in any field of the data-type. Currently ( - :c:data:`NPY_NEEDS_INIT` \| :c:data:`NPY_LIST_PICKLE` \| - :c:data:`NPY_ITEM_REFCOUNT` \| :c:data:`NPY_NEEDS_PYAPI` ). - - .. c:macro:: NPY_OBJECT_DTYPE_FLAGS - - Bits set for the object data-type: ( :c:data:`NPY_LIST_PICKLE` - \| :c:data:`NPY_USE_GETITEM` \| :c:data:`NPY_ITEM_IS_POINTER` \| - :c:data:`NPY_ITEM_REFCOUNT` \| :c:data:`NPY_NEEDS_INIT` \| - :c:data:`NPY_NEEDS_PYAPI`). - - .. c:function:: int PyDataType_FLAGCHK(PyArray_Descr *dtype, int flags) - - Return true if all the given flags are set for the data-type - object. - - .. c:function:: int PyDataType_REFCHK(PyArray_Descr *dtype) - - Equivalent to :c:func:`PyDataType_FLAGCHK` (*dtype*, - :c:data:`NPY_ITEM_REFCOUNT`). + * :c:macro:`NPY_ITEM_REFCOUNT` + * :c:macro:`NPY_ITEM_HASOBJECT` + * :c:macro:`NPY_LIST_PICKLE` + * :c:macro:`NPY_ITEM_IS_POINTER` + * :c:macro:`NPY_NEEDS_INIT` + * :c:macro:`NPY_NEEDS_PYAPI` + * :c:macro:`NPY_USE_GETITEM` + * :c:macro:`NPY_USE_SETITEM` + * :c:macro:`NPY_FROM_FIELDS` + * :c:macro:`NPY_OBJECT_DTYPE_FLAGS` .. c:member:: int type_num @@ -452,6 +385,73 @@ PyArrayDescr_Type and PyArray_Descr Currently unused. Reserved for future use in caching hash values. +.. c:macro:: NPY_ITEM_REFCOUNT + + Indicates that items of this data-type must be reference + counted (using :c:func:`Py_INCREF` and :c:func:`Py_DECREF` ). + +.. c:macro:: NPY_ITEM_HASOBJECT + + Same as :c:data:`NPY_ITEM_REFCOUNT`. + +.. c:macro:: NPY_LIST_PICKLE + + Indicates arrays of this data-type must be converted to a list + before pickling. + +.. c:macro:: NPY_ITEM_IS_POINTER + + Indicates the item is a pointer to some other data-type + +.. c:macro:: NPY_NEEDS_INIT + + Indicates memory for this data-type must be initialized (set + to 0) on creation. + +.. c:macro:: NPY_NEEDS_PYAPI + + Indicates this data-type requires the Python C-API during + access (so don't give up the GIL if array access is going to + be needed). + +.. c:macro:: NPY_USE_GETITEM + + On array access use the ``f->getitem`` function pointer + instead of the standard conversion to an array scalar. Must + use if you don't define an array scalar to go along with + the data-type. + +.. c:macro:: NPY_USE_SETITEM + + When creating a 0-d array from an array scalar use + ``f->setitem`` instead of the standard copy from an array + scalar. Must use if you don't define an array scalar to go + along with the data-type. + +.. c:macro:: NPY_FROM_FIELDS + + The bits that are inherited for the parent data-type if these + bits are set in any field of the data-type. Currently ( + :c:data:`NPY_NEEDS_INIT` \| :c:data:`NPY_LIST_PICKLE` \| + :c:data:`NPY_ITEM_REFCOUNT` \| :c:data:`NPY_NEEDS_PYAPI` ). + +.. c:macro:: NPY_OBJECT_DTYPE_FLAGS + + Bits set for the object data-type: ( :c:data:`NPY_LIST_PICKLE` + \| :c:data:`NPY_USE_GETITEM` \| :c:data:`NPY_ITEM_IS_POINTER` \| + :c:data:`NPY_ITEM_REFCOUNT` \| :c:data:`NPY_NEEDS_INIT` \| + :c:data:`NPY_NEEDS_PYAPI`). + +.. c:function:: int PyDataType_FLAGCHK(PyArray_Descr *dtype, int flags) + + Return true if all the given flags are set for the data-type + object. + +.. c:function:: int PyDataType_REFCHK(PyArray_Descr *dtype) + + Equivalent to :c:func:`PyDataType_FLAGCHK` (*dtype*, + :c:data:`NPY_ITEM_REFCOUNT`). + .. c:type:: PyArray_ArrFuncs Functions implementing internal features. Not all of these @@ -973,7 +973,7 @@ PyUFunc_Type and PyUFuncObject Some fallback support for this slot exists, but will be removed eventually. A universal function that relied on this will have to be ported eventually. - See ref:`NEP 41 <NEP41>` and ref:`NEP 43 <NEP43>` + See :ref:`NEP 41 <NEP41>` and :ref:`NEP 43 <NEP43>` .. c:member:: void *reserved2 @@ -997,10 +997,14 @@ PyUFunc_Type and PyUFuncObject .. c:member:: npy_uint32 *core_dim_flags - For each distinct core dimension, a set of ``UFUNC_CORE_DIM*`` flags + For each distinct core dimension, a set of flags ( + :c:macro:`UFUNC_CORE_DIM_CAN_IGNORE` and + :c:macro:`UFUNC_CORE_DIM_SIZE_INFERRED`) + + .. c:member:: PyObject *identity_value -.. - dedented to allow internal linking, pending a refactoring + Identity for reduction, when :c:member:`PyUFuncObject.identity` + is equal to :c:data:`PyUFunc_IdentityValue`. .. c:macro:: UFUNC_CORE_DIM_CAN_IGNORE @@ -1011,11 +1015,6 @@ PyUFunc_Type and PyUFuncObject if the dim size will be determined from the operands and not from a :ref:`frozen <frozen>` signature - .. c:member:: PyObject *identity_value - - Identity for reduction, when :c:member:`PyUFuncObject.identity` - is equal to :c:data:`PyUFunc_IdentityValue`. - PyArrayIter_Type and PyArrayIterObject -------------------------------------- @@ -1253,7 +1252,7 @@ ScalarArrayTypes ---------------- There is a Python type for each of the different built-in data types -that can be present in the array Most of these are simple wrappers +that can be present in the array. Most of these are simple wrappers around the corresponding data type in C. The C-names for these types are ``Py{TYPE}ArrType_Type`` where ``{TYPE}`` can be @@ -1457,22 +1456,6 @@ memory management. These types are not accessible directly from Python, and are not exposed to the C-API. They are included here only for completeness and assistance in understanding the code. - -.. c:type:: PyUFuncLoopObject - - A loose wrapper for a C-structure that contains the information - needed for looping. This is useful if you are trying to understand - the ufunc looping code. The :c:type:`PyUFuncLoopObject` is the associated - C-structure. It is defined in the ``ufuncobject.h`` header. - -.. c:type:: PyUFuncReduceObject - - A loose wrapper for the C-structure that contains the information - needed for reduce-like methods of ufuncs. This is useful if you are - trying to understand the reduce, accumulate, and reduce-at - code. The :c:type:`PyUFuncReduceObject` is the associated C-structure. It - is defined in the ``ufuncobject.h`` header. - .. c:type:: PyUFunc_Loop1d A simple linked-list of C-structures containing the information needed @@ -1483,8 +1466,12 @@ for completeness and assistance in understanding the code. Advanced indexing is handled with this Python type. It is simply a loose wrapper around the C-structure containing the variables - needed for advanced array indexing. The associated C-structure, - ``PyArrayMapIterObject``, is useful if you are trying to + needed for advanced array indexing. + +.. c:type:: PyArrayMapIterObject + + The C-structure associated with :c:var:`PyArrayMapIter_Type`. + This structure is useful if you are trying to understand the advanced-index mapping code. It is defined in the ``arrayobject.h`` header. This type is not exposed to Python and could be replaced with a C-structure. As a Python type it takes diff --git a/doc/source/reference/distutils_guide.rst b/doc/source/reference/distutils_guide.rst index a72a9c4d6..6f927c231 100644 --- a/doc/source/reference/distutils_guide.rst +++ b/doc/source/reference/distutils_guide.rst @@ -1,6 +1,6 @@ .. _distutils-user-guide: -NumPy Distutils - Users Guide +NumPy distutils - users guide ============================= .. warning:: diff --git a/doc/source/reference/distutils_status_migration.rst b/doc/source/reference/distutils_status_migration.rst index eda4790b5..67695978c 100644 --- a/doc/source/reference/distutils_status_migration.rst +++ b/doc/source/reference/distutils_status_migration.rst @@ -83,7 +83,7 @@ present in ``setuptools``: - Support for a few other scientific libraries, like FFTW and UMFPACK - Better MinGW support - Per-compiler build flag customization (e.g. `-O3` and `SSE2` flags are default) -- a simple user build config system, see [site.cfg.example](https://github.com/numpy/numpy/blob/master/site.cfg.example) +- a simple user build config system, see `site.cfg.example <https://github.com/numpy/numpy/blob/master/site.cfg.example>`__ - SIMD intrinsics support The most widely used feature is nested ``setup.py`` files. This feature will diff --git a/doc/source/reference/figures/dtype-hierarchy.dia b/doc/source/reference/figures/dtype-hierarchy.dia Binary files differindex 62e925cfd..d5c01bf27 100644 --- a/doc/source/reference/figures/dtype-hierarchy.dia +++ b/doc/source/reference/figures/dtype-hierarchy.dia diff --git a/doc/source/reference/figures/dtype-hierarchy.pdf b/doc/source/reference/figures/dtype-hierarchy.pdf Binary files differindex 6ce496a3e..b2375e152 100644 --- a/doc/source/reference/figures/dtype-hierarchy.pdf +++ b/doc/source/reference/figures/dtype-hierarchy.pdf diff --git a/doc/source/reference/figures/dtype-hierarchy.png b/doc/source/reference/figures/dtype-hierarchy.png Binary files differindex 6c45758b1..891de096c 100644 --- a/doc/source/reference/figures/dtype-hierarchy.png +++ b/doc/source/reference/figures/dtype-hierarchy.png diff --git a/doc/source/reference/global_state.rst b/doc/source/reference/global_state.rst index 81685ec7d..a898450af 100644 --- a/doc/source/reference/global_state.rst +++ b/doc/source/reference/global_state.rst @@ -1,7 +1,7 @@ .. _global_state: ************ -Global State +Global state ************ NumPy has a few import-time, compile-time, or runtime options @@ -11,10 +11,10 @@ purposes and will not be interesting to the vast majority of users. -Performance-Related Options +Performance-related options =========================== -Number of Threads used for Linear Algebra +Number of threads used for Linear Algebra ----------------------------------------- NumPy itself is normally intentionally limited to a single thread @@ -49,25 +49,17 @@ 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. +SIMD feature selection +---------------------- -Interoperability-Related Options -================================ +Setting ``NPY_DISABLE_CPU_FEATURES`` will exclude simd features at runtime. +See :ref:`runtime-simd-dispatch`. -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 +Debugging-related options ========================= -Relaxed Strides Checking +Relaxed strides checking ------------------------ The *compile-time* environment variable:: @@ -90,3 +82,17 @@ memory allocation policy, the default will be to call ``free``. If ``NUMPY_WARN_IF_NO_MEM_POLICY`` is set to ``"1"``, a ``RuntimeWarning`` will be emitted. A better alternative is to use a ``PyCapsule`` with a deallocator and set the ``ndarray.base``. + + +Testing planned future behavior +=============================== + +NumPy has some code paths which are planned to be activated in the future +but are not yet the default behavior. +You can try testing some of these which may be shipped with a new "major" +release (NumPy 2.0) by setting an environment before importing NumPy: + + NPY_NUMPY_2_BEHAVIOR=1 + +By default this will also activate the :ref:`NEP 50 <NEP50>` related setting +``NPY_PROMOTION_STATE`` (please see the NEP for details on this). diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 8e4a81436..4756af5fa 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -3,7 +3,7 @@ .. _reference: ############### -NumPy Reference +NumPy reference ############### :Release: |version| diff --git a/doc/source/reference/internals.code-explanations.rst b/doc/source/reference/internals.code-explanations.rst index d34314610..db3b3b452 100644 --- a/doc/source/reference/internals.code-explanations.rst +++ b/doc/source/reference/internals.code-explanations.rst @@ -1,7 +1,7 @@ :orphan: ************************* -NumPy C Code Explanations +NumPy C code explanations ************************* .. This document has been moved to ../dev/internals.code-explanations.rst. diff --git a/doc/source/reference/maskedarray.baseclass.rst b/doc/source/reference/maskedarray.baseclass.rst index fcd310faa..7121914b9 100644 --- a/doc/source/reference/maskedarray.baseclass.rst +++ b/doc/source/reference/maskedarray.baseclass.rst @@ -72,19 +72,19 @@ Attributes and properties of masked arrays .. seealso:: :ref:`Array Attributes <arrays.ndarray.attributes>` -.. autoattribute:: MaskedArray.data +.. autoattribute:: numpy::ma.MaskedArray.data -.. autoattribute:: MaskedArray.mask +.. autoattribute:: numpy::ma.MaskedArray.mask -.. autoattribute:: MaskedArray.recordmask +.. autoattribute:: numpy::ma.MaskedArray.recordmask -.. autoattribute:: MaskedArray.fill_value +.. autoattribute:: numpy::ma.MaskedArray.fill_value -.. autoattribute:: MaskedArray.baseclass +.. autoattribute:: numpy::ma.MaskedArray.baseclass -.. autoattribute:: MaskedArray.sharedmask +.. autoattribute:: numpy::ma.MaskedArray.sharedmask -.. autoattribute:: MaskedArray.hardmask +.. autoattribute:: numpy::ma.MaskedArray.hardmask As :class:`MaskedArray` is a subclass of :class:`~numpy.ndarray`, a masked array also inherits all the attributes and properties of a :class:`~numpy.ndarray` instance. diff --git a/doc/source/reference/random/bit_generators/index.rst b/doc/source/reference/random/bit_generators/index.rst index d93f38d0b..e523b4339 100644 --- a/doc/source/reference/random/bit_generators/index.rst +++ b/doc/source/reference/random/bit_generators/index.rst @@ -1,5 +1,7 @@ .. currentmodule:: numpy.random +.. _random-bit-generators: + Bit Generators ============== @@ -50,6 +52,8 @@ The included BitGenerators are: Philox <philox> SFC64 <sfc64> +.. _seeding_and_entropy: + Seeding and Entropy =================== @@ -127,6 +131,16 @@ of 12 instances: .. end_block +If you already have an initial random generator instance, you can shorten +the above by using the `~BitGenerator.spawn` method: + +.. code-block:: python + + from numpy.random import PCG64, SeedSequence + # High quality initial entropy + entropy = 0x87351080e25cb0fad77a44a3be03b491 + base_bitgen = PCG64(entropy) + generators = base_bitgen.spawn(12) An alternative way is to use the fact that a `~SeedSequence` can be initialized by a tuple of elements. Here we use a base entropy value and an integer diff --git a/doc/source/reference/random/compatibility.rst b/doc/source/reference/random/compatibility.rst new file mode 100644 index 000000000..138f03ca3 --- /dev/null +++ b/doc/source/reference/random/compatibility.rst @@ -0,0 +1,87 @@ +.. _random-compatibility: + +.. currentmodule:: numpy.random + +Compatibility Policy +==================== + +`numpy.random` has a somewhat stricter compatibility policy than the rest of +NumPy. Users of pseudorandomness often have use cases for being able to +reproduce runs in fine detail given the same seed (so-called "stream +compatibility"), and so we try to balance those needs with the flexibility to +enhance our algorithms. :ref:`NEP 19 <NEP19>` describes the evolution of this +policy. + +The main kind of compatibility that we enforce is stream-compatibility from run +to run under certain conditions. If you create a `Generator` with the same +`BitGenerator`, with the same seed, perform the same sequence of method calls +with the same arguments, on the same build of ``numpy``, in the same +environment, on the same machine, you should get the same stream of numbers. +Note that these conditions are very strict. There are a number of factors +outside of NumPy's control that limit our ability to guarantee much more than +this. For example, different CPUs implement floating point arithmetic +differently, and this can cause differences in certain edge cases that cascade +to the rest of the stream. `Generator.multivariate_normal`, for another +example, uses a matrix decomposition from ``numpy.linalg``. Even on the same +platform, a different build of ``numpy`` may use a different version of this +matrix decomposition algorithm from the LAPACK that it links to, causing +`Generator.multivariate_normal` to return completely different (but equally +valid!) results. We strive to prefer algorithms that are more resistant to +these effects, but this is always imperfect. + +.. note:: + + Most of the `Generator` methods allow you to draw multiple values from + a distribution as arrays. The requested size of this array is a parameter, + for the purposes of the above policy. Calling ``rng.random()`` 5 times is + not *guaranteed* to give the same numbers as ``rng.random(5)``. We reserve + the ability to decide to use different algorithms for different-sized + blocks. In practice, this happens rarely. + +Like the rest of NumPy, we generally maintain API source +compatibility from version to version. If we *must* make an API-breaking +change, then we will only do so with an appropriate deprecation period and +warnings, according to :ref:`general NumPy policy <NEP23>`. + +Breaking stream-compatibility in order to introduce new features or +improve performance in `Generator` or `default_rng` will be *allowed* with +*caution*. Such changes will be considered features, and as such will be no +faster than the standard release cadence of features (i.e. on ``X.Y`` releases, +never ``X.Y.Z``). Slowness will not be considered a bug for this purpose. +Correctness bug fixes that break stream-compatibility can happen on bugfix +releases, per usual, but developers should consider if they can wait until the +next feature release. We encourage developers to strongly weight user’s pain +from the break in stream-compatibility against the improvements. One example +of a worthwhile improvement would be to change algorithms for a significant +increase in performance, for example, moving from the `Box-Muller transform +<https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform>`_ method of +Gaussian variate generation to the faster `Ziggurat algorithm +<https://en.wikipedia.org/wiki/Ziggurat_algorithm>`_. An example of +a discouraged improvement would be tweaking the Ziggurat tables just a little +bit for a small performance improvement. + +.. note:: + + In particular, `default_rng` is allowed to change the default + `BitGenerator` that it uses (again, with *caution* and plenty of advance + warning). + +In general, `BitGenerator` classes have stronger guarantees of +version-to-version stream compatibility. This allows them to be a firmer +building block for downstream users that need it. Their limited API surface +makes it easier for them to maintain this compatibility from version to version. See +the docstrings of each `BitGenerator` class for their individual compatibility +guarantees. + +The legacy `RandomState` and the :ref:`associated convenience functions +<functions-in-numpy-random>` have a stricter version-to-version +compatibility guarantee. For reasons outlined in :ref:`NEP 19 <NEP19>`, we had made +stronger promises about their version-to-version stability early in NumPy's +development. There are still some limited use cases for this kind of +compatibility (like generating data for tests), so we maintain as much +compatibility as we can. There will be no more modifications to `RandomState`, +not even to fix correctness bugs. There are a few gray areas where we can make +minor fixes to keep `RandomState` working without segfaulting as NumPy's +internals change, and some docstring fixes. However, the previously-mentioned +caveats about the variability from machine to machine and build to build still +apply to `RandomState` just as much as it does to `Generator`. diff --git a/doc/source/reference/random/extending.rst b/doc/source/reference/random/extending.rst index 6bb941496..998faf80a 100644 --- a/doc/source/reference/random/extending.rst +++ b/doc/source/reference/random/extending.rst @@ -25,7 +25,7 @@ provided by ``ctypes.next_double``. Both CTypes and CFFI allow the more complicated distributions to be used directly in Numba after compiling the file distributions.c into a ``DLL`` or ``so``. An example showing the use of a more complicated distribution is in -the `examples` section below. +the `Examples`_ section below. .. _random_cython: @@ -113,6 +113,6 @@ Examples .. toctree:: Numba <examples/numba> - CFFI + Numba <examples/numba_cffi> + CFFI + Numba <examples/numba_cffi> Cython <examples/cython/index> CFFI <examples/cffi> diff --git a/doc/source/reference/random/generator.rst b/doc/source/reference/random/generator.rst index dc71cb1f9..e08395b17 100644 --- a/doc/source/reference/random/generator.rst +++ b/doc/source/reference/random/generator.rst @@ -18,12 +18,13 @@ can be changed by passing an instantized BitGenerator to ``Generator``. :members: __init__ :exclude-members: __init__ -Accessing the BitGenerator --------------------------- +Accessing the BitGenerator and Spawning +--------------------------------------- .. autosummary:: :toctree: generated/ ~numpy.random.Generator.bit_generator + ~numpy.random.Generator.spawn Simple random data ------------------ diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst index 83a27d80c..38555b133 100644 --- a/doc/source/reference/random/index.rst +++ b/doc/source/reference/random/index.rst @@ -7,210 +7,124 @@ Random sampling (:mod:`numpy.random`) ===================================== -Numpy's random number routines produce pseudo random numbers using -combinations of a `BitGenerator` to create sequences and a `Generator` -to use those sequences to sample from different statistical distributions: - -* BitGenerators: Objects that generate random numbers. These are typically - unsigned integer words filled with sequences of either 32 or 64 random bits. -* Generators: Objects that transform sequences of random bits from a - BitGenerator into sequences of numbers that follow a specific probability - distribution (such as uniform, Normal or Binomial) within a specified - interval. - -Since Numpy version 1.17.0 the Generator can be initialized with a -number of different BitGenerators. It exposes many different probability -distributions. See `NEP 19 <https://www.numpy.org/neps/ -nep-0019-rng-policy.html>`_ for context on the updated random Numpy number -routines. The legacy `RandomState` random number routines are still -available, but limited to a single BitGenerator. See :ref:`new-or-different` -for a complete list of improvements and differences from the legacy -``RandomState``. - -For convenience and backward compatibility, a single `RandomState` -instance's methods are imported into the numpy.random namespace, see -:ref:`legacy` for the complete list. - .. _random-quick-start: Quick Start ----------- -Call `default_rng` to get a new instance of a `Generator`, then call its -methods to obtain samples from different distributions. By default, -`Generator` uses bits provided by `PCG64` which has better statistical -properties than the legacy `MT19937` used in `RandomState`. - -.. code-block:: python - - # Do this (new version) - from numpy.random import default_rng - rng = default_rng() - vals = rng.standard_normal(10) - more_vals = rng.standard_normal(10) - - # instead of this (legacy version) - from numpy import random - vals = random.standard_normal(10) - more_vals = random.standard_normal(10) - -`Generator` can be used as a replacement for `RandomState`. Both class -instances hold an internal `BitGenerator` instance to provide the bit -stream, it is accessible as ``gen.bit_generator``. Some long-overdue API -cleanup means that legacy and compatibility methods have been removed from -`Generator` - -=================== ============== ============ -`RandomState` `Generator` Notes -------------------- -------------- ------------ -``random_sample``, ``random`` Compatible with `random.random` -``rand`` -------------------- -------------- ------------ -``randint``, ``integers`` Add an ``endpoint`` kwarg -``random_integers`` -------------------- -------------- ------------ -``tomaxint`` removed Use ``integers(0, np.iinfo(np.int_).max,`` - ``endpoint=False)`` -------------------- -------------- ------------ -``seed`` removed Use `SeedSequence.spawn` -=================== ============== ============ - -See :ref:`new-or-different` for more information. - -Something like the following code can be used to support both ``RandomState`` -and ``Generator``, with the understanding that the interfaces are slightly -different - -.. code-block:: python - - try: - rng_integers = rng.integers - except AttributeError: - rng_integers = rng.randint - a = rng_integers(1000) - -Seeds can be passed to any of the BitGenerators. The provided value is mixed -via `SeedSequence` to spread a possible sequence of seeds across a wider -range of initialization states for the BitGenerator. Here `PCG64` is used and -is wrapped with a `Generator`. - -.. code-block:: python - - from numpy.random import Generator, PCG64 - rng = Generator(PCG64(12345)) - rng.standard_normal() - -Here we use `default_rng` to create an instance of `Generator` to generate a -random float: - ->>> import numpy as np ->>> rng = np.random.default_rng(12345) ->>> print(rng) -Generator(PCG64) ->>> rfloat = rng.random() ->>> rfloat -0.22733602246716966 ->>> type(rfloat) -<class 'float'> - -Here we use `default_rng` to create an instance of `Generator` to generate 3 -random integers between 0 (inclusive) and 10 (exclusive): - ->>> import numpy as np ->>> rng = np.random.default_rng(12345) ->>> rints = rng.integers(low=0, high=10, size=3) ->>> rints -array([6, 2, 7]) ->>> type(rints[0]) -<class 'numpy.int64'> - -Introduction ------------- -The new infrastructure takes a different approach to producing random numbers -from the `RandomState` object. Random number generation is separated into -two components, a bit generator and a random generator. - -The `BitGenerator` has a limited set of responsibilities. It manages state -and provides functions to produce random doubles and random unsigned 32- and -64-bit values. - -The `random generator <Generator>` takes the -bit generator-provided stream and transforms them into more useful -distributions, e.g., simulated normal random values. This structure allows -alternative bit generators to be used with little code duplication. - -The `Generator` is the user-facing object that is nearly identical to the -legacy `RandomState`. It accepts a bit generator instance as an argument. -The default is currently `PCG64` but this may change in future versions. -As a convenience NumPy provides the `default_rng` function to hide these -details: - ->>> from numpy.random import default_rng ->>> rng = default_rng(12345) ->>> print(rng) -Generator(PCG64) ->>> print(rng.random()) -0.22733602246716966 - -One can also instantiate `Generator` directly with a `BitGenerator` instance. - -To use the default `PCG64` bit generator, one can instantiate it directly and -pass it to `Generator`: - ->>> from numpy.random import Generator, PCG64 ->>> rng = Generator(PCG64(12345)) ->>> print(rng) -Generator(PCG64) - -Similarly to use the older `MT19937` bit generator (not recommended), one can -instantiate it directly and pass it to `Generator`: - ->>> from numpy.random import Generator, MT19937 ->>> rng = Generator(MT19937(12345)) ->>> print(rng) -Generator(MT19937) - -What's New or Different -~~~~~~~~~~~~~~~~~~~~~~~ +The :mod:`numpy.random` module implements pseudo-random number generators +(PRNGs or RNGs, for short) with the ability to draw samples from a variety of +probability distributions. In general, users will create a `Generator` instance +with `default_rng` and call the various methods on it to obtain samples from +different distributions. + +:: + + >>> import numpy as np + >>> rng = np.random.default_rng() + # Generate one random float uniformly distributed over the range [0, 1) + >>> rng.random() #doctest: +SKIP + 0.06369197489564249 # may vary + # Generate an array of 10 numbers according to a unit Gaussian distribution. + >>> rng.standard_normal(10) #doctest: +SKIP + array([-0.31018314, -1.8922078 , -0.3628523 , -0.63526532, 0.43181166, # may vary + 0.51640373, 1.25693945, 0.07779185, 0.84090247, -2.13406828]) + # Generate an array of 5 integers uniformly over the range [0, 10). + >>> rng.integers(low=0, high=10, size=5) #doctest: +SKIP + array([8, 7, 6, 2, 0]) # may vary + +Our RNGs are deterministic sequences and can be reproduced by specifying a seed integer to +derive its initial state. By default, with no seed provided, `default_rng` will create +seed the RNG from nondeterministic data from the operating system and therefore +generate different numbers each time. The pseudo-random sequences will be +independent for all practical purposes, at least those purposes for which our +pseudo-randomness was good for in the first place. + +:: + + >>> rng1 = np.random.default_rng() + >>> rng1.random() #doctest: +SKIP + 0.6596288841243357 # may vary + >>> rng2 = np.random.default_rng() + >>> rng2.random() #doctest: +SKIP + 0.11885628817151628 # may vary + .. warning:: - The Box-Muller method used to produce NumPy's normals is no longer available - in `Generator`. It is not possible to reproduce the exact random - values using Generator for the normal distribution or any other - distribution that relies on the normal such as the `RandomState.gamma` or - `RandomState.standard_t`. If you require bitwise backward compatible - streams, use `RandomState`. - -* The Generator's normal, exponential and gamma functions use 256-step Ziggurat - methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF - implementations. -* Optional ``dtype`` argument that accepts ``np.float32`` or ``np.float64`` - to produce either single or double precision uniform random variables for - select distributions -* Optional ``out`` argument that allows existing arrays to be filled for - select distributions -* All BitGenerators can produce doubles, uint64s and uint32s via CTypes - (`PCG64.ctypes`) and CFFI (`PCG64.cffi`). This allows the bit generators - to be used in numba. -* The bit generators can be used in downstream projects via - :ref:`Cython <random_cython>`. -* `Generator.integers` is now the canonical way to generate integer - random numbers from a discrete uniform distribution. The ``rand`` and - ``randn`` methods are only available through the legacy `RandomState`. - The ``endpoint`` keyword can be used to specify open or closed intervals. - This replaces both ``randint`` and the deprecated ``random_integers``. -* `Generator.random` is now the canonical way to generate floating-point - random numbers, which replaces `RandomState.random_sample`, - `RandomState.sample`, and `RandomState.ranf`. This is consistent with - 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``. + The pseudo-random number generators implemented in this module are designed + for statistical modeling and simulation. They are not suitable for security + or cryptographic purposes. See the :py:mod:`secrets` module from the + standard library for such use cases. + +Seeds should be large positive integers. `default_rng` can take positive +integers of any size. We recommend using very large, unique numbers to ensure +that your seed is different from anyone else's. This is good practice to ensure +that your results are statistically independent from theirs unless you are +intentionally *trying* to reproduce their result. A convenient way to get +such a seed number is to use :py:func:`secrets.randbits` to get an +arbitrary 128-bit integer. + +:: + + >>> import secrets + >>> import numpy as np + >>> secrets.randbits(128) #doctest: +SKIP + 122807528840384100672342137672332424406 # may vary + >>> rng1 = np.random.default_rng(122807528840384100672342137672332424406) + >>> rng1.random() + 0.5363922081269535 + >>> rng2 = np.random.default_rng(122807528840384100672342137672332424406) + >>> rng2.random() + 0.5363922081269535 + +See the documentation on `default_rng` and `SeedSequence` for more advanced +options for controlling the seed in specialized scenarios. + +`Generator` and its associated infrastructure was introduced in NumPy version +1.17.0. There is still a lot of code that uses the older `RandomState` and the +functions in `numpy.random`. While there are no plans to remove them at this +time, we do recommend transitioning to `Generator` as you can. The algorithms +are faster, more flexible, and will receive more improvements in the future. +For the most part, `Generator` can be used as a replacement for `RandomState`. +See :ref:`legacy` for information on the legacy infrastructure, +:ref:`new-or-different` for information on transitioning, and :ref:`NEP 19 +<NEP19>` for some of the reasoning for the transition. + +Design +------ + +Users primarily interact with `Generator` instances. Each `Generator` instance +owns a `BitGenerator` instance that implements the core RNG algorithm. The +`BitGenerator` has a limited set of responsibilities. It manages state and +provides functions to produce random doubles and random unsigned 32- and 64-bit +values. + +The `Generator` takes the bit generator-provided stream and transforms them +into more useful distributions, e.g., simulated normal random values. This +structure allows alternative bit generators to be used with little code +duplication. + +NumPy implements several different `BitGenerator` classes implementing +different RNG algorithms. `default_rng` currently uses `~PCG64` as the +default `BitGenerator`. It has better statistical properties and performance +than the `~MT19937` algorithm used in the legacy `RandomState`. See +:ref:`random-bit-generators` for more details on the supported BitGenerators. + +`default_rng` and BitGenerators delegate the conversion of seeds into RNG +states to `SeedSequence` internally. `SeedSequence` implements a sophisticated +algorithm that intermediates between the user's input and the internal +implementation details of each `BitGenerator` algorithm, each of which can +require different amounts of bits for its state. Importantly, it lets you use +arbitrary-sized integers and arbitrary sequences of such integers to mix +together into the RNG state. This is a useful primitive for constructing +a :ref:`flexible pattern for parallel RNG streams <seedsequence-spawn>`. + +For backward compatibility, we still maintain the legacy `RandomState` class. +It continues to use the `~MT19937` algorithm by default, and old seeds continue +to reproduce the same results. The convenience :ref:`functions-in-numpy-random` +are still aliases to the methods on a single global `RandomState` instance. See +:ref:`legacy` for the complete details. See :ref:`new-or-different` for +a detailed comparison between `Generator` and `RandomState`. Parallel Generation ~~~~~~~~~~~~~~~~~~~ @@ -235,6 +149,7 @@ Concepts Legacy Generator (RandomState) <legacy> BitGenerators, SeedSequences <bit_generators/index> Upgrading PCG64 with PCG64DXSM <upgrading-pcg64> + compatibility Features -------- diff --git a/doc/source/reference/random/legacy.rst b/doc/source/reference/random/legacy.rst index b1fce49a1..00921c477 100644 --- a/doc/source/reference/random/legacy.rst +++ b/doc/source/reference/random/legacy.rst @@ -52,7 +52,7 @@ using the state of the `RandomState`: :exclude-members: __init__ Seeding and State ------------------ +================= .. autosummary:: :toctree: generated/ @@ -62,7 +62,7 @@ Seeding and State ~RandomState.seed Simple random data ------------------- +================== .. autosummary:: :toctree: generated/ @@ -75,7 +75,7 @@ Simple random data ~RandomState.bytes Permutations ------------- +============ .. autosummary:: :toctree: generated/ @@ -83,7 +83,7 @@ Permutations ~RandomState.permutation Distributions -------------- +============== .. autosummary:: :toctree: generated/ @@ -123,8 +123,10 @@ Distributions ~RandomState.weibull ~RandomState.zipf +.. _functions-in-numpy-random: + Functions in `numpy.random` ---------------------------- +=========================== Many of the RandomState methods above are exported as functions in `numpy.random` This usage is discouraged, as it is implemented via a global `RandomState` instance which is not advised on two counts: @@ -133,8 +135,7 @@ Many of the RandomState methods above are exported as functions in - It uses a `RandomState` rather than the more modern `Generator`. -For backward compatible legacy reasons, we cannot change this. See -:ref:`random-quick-start`. +For backward compatible legacy reasons, we will not change this. .. autosummary:: :toctree: generated/ diff --git a/doc/source/reference/random/new-or-different.rst b/doc/source/reference/random/new-or-different.rst index 8f4a70540..9b5bf38e5 100644 --- a/doc/source/reference/random/new-or-different.rst +++ b/doc/source/reference/random/new-or-different.rst @@ -5,17 +5,9 @@ What's New or Different ----------------------- -.. warning:: - - The Box-Muller method used to produce NumPy's normals is no longer available - in `Generator`. It is not possible to reproduce the exact random - values using ``Generator`` for the normal distribution or any other - distribution that relies on the normal such as the `Generator.gamma` or - `Generator.standard_t`. If you require bitwise backward compatible - streams, use `RandomState`, i.e., `RandomState.gamma` or - `RandomState.standard_t`. - -Quick comparison of legacy :ref:`mtrand <legacy>` to the new `Generator` +NumPy 1.17.0 introduced `Generator` as an improved replacement for +the :ref:`legacy <legacy>` `RandomState`. Here is a quick comparison of the two +implementations. ================== ==================== ============= Feature Older Equivalent Notes @@ -44,21 +36,17 @@ Feature Older Equivalent Notes ``high`` interval endpoint ================== ==================== ============= -And in more detail: - -* Simulate from the complex normal distribution - (`~.Generator.complex_normal`) * The normal, exponential and gamma generators use 256-step Ziggurat methods which are 2-10 times faster than NumPy's default implementation in `~.Generator.standard_normal`, `~.Generator.standard_exponential` or - `~.Generator.standard_gamma`. - + `~.Generator.standard_gamma`. Because of the change in algorithms, it is not + possible to reproduce the exact random values using ``Generator`` for these + distributions or any distribution method that relies on them. .. ipython:: python - from numpy.random import Generator, PCG64 import numpy.random - rng = Generator(PCG64()) + rng = np.random.default_rng() %timeit -n 1 rng.standard_normal(100000) %timeit -n 1 numpy.random.standard_normal(100000) @@ -74,18 +62,25 @@ And in more detail: * `~.Generator.integers` is now the canonical way to generate integer - random numbers from a discrete uniform distribution. The ``rand`` and - ``randn`` methods are only available through the legacy `~.RandomState`. - This replaces both ``randint`` and the deprecated ``random_integers``. -* The Box-Muller method used to produce NumPy's normals is no longer available. + random numbers from a discrete uniform distribution. This replaces both + ``randint`` and the deprecated ``random_integers``. +* The ``rand`` and ``randn`` methods are only available through the legacy + `~.RandomState`. +* `Generator.random` is now the canonical way to generate floating-point + random numbers, which replaces `RandomState.random_sample`, + `sample`, and `ranf`, all of which were aliases. This is consistent with + Python's `random.random`. * All bit generators can produce doubles, uint64s and uint32s via CTypes (`~PCG64.ctypes`) and CFFI (`~PCG64.cffi`). This allows these bit generators to be used in numba. * The bit generators can be used in downstream projects via Cython. +* All bit generators use `SeedSequence` to :ref:`convert seed integers to + initialized states <seeding_and_entropy>`. * Optional ``dtype`` argument that accepts ``np.float32`` or ``np.float64`` to produce either single or double precision uniform random variables for - select distributions + select distributions. `~.Generator.integers` accepts a ``dtype`` argument + with any signed or unsigned integer dtype. * Uniforms (`~.Generator.random` and `~.Generator.integers`) * Normals (`~.Generator.standard_normal`) @@ -94,9 +89,10 @@ And in more detail: .. ipython:: python - rng = Generator(PCG64(0)) - rng.random(3, dtype='d') - rng.random(3, dtype='f') + rng = np.random.default_rng() + rng.random(3, dtype=np.float64) + rng.random(3, dtype=np.float32) + rng.integers(0, 256, size=3, dtype=np.uint8) * Optional ``out`` argument that allows existing arrays to be filled for select distributions @@ -111,6 +107,7 @@ And in more detail: .. ipython:: python + rng = np.random.default_rng() existing = np.zeros(4) rng.random(out=existing[:2]) print(existing) @@ -121,9 +118,12 @@ And in more detail: .. ipython:: python - rng = Generator(PCG64(123456789)) + rng = np.random.default_rng() a = np.arange(12).reshape((3, 4)) a rng.choice(a, axis=1, size=5) rng.shuffle(a, axis=1) # Shuffle in-place a + +* Added a method to sample from the complex normal distribution + (`~.Generator.complex_normal`) diff --git a/doc/source/reference/random/parallel.rst b/doc/source/reference/random/parallel.rst index b625d34b7..b4934a0ca 100644 --- a/doc/source/reference/random/parallel.rst +++ b/doc/source/reference/random/parallel.rst @@ -12,6 +12,11 @@ or distributed). `~SeedSequence` spawning ------------------------ +NumPy allows you to spawn new (with very high probability) independent +`~BitGenerator` and `~Generator` instances via their ``spawn()`` method. +This spawning is implemented by the `~SeedSequence` used for initializing +the bit generators random stream. + `~SeedSequence` `implements an algorithm`_ to process a user-provided seed, typically as an integer of some size, and to convert it into an initial state for a `~BitGenerator`. It uses hashing techniques to ensure that low-quality seeds @@ -53,15 +58,25 @@ wrap this together into an API that is easy to use and difficult to misuse. .. end_block -Child `~SeedSequence` objects can also spawn to make grandchildren, and so on. -Each `~SeedSequence` has its position in the tree of spawned `~SeedSequence` -objects mixed in with the user-provided seed to generate independent (with very -high probability) streams. +For convenience the direct use of `~SeedSequence` is not necessary. +The above ``streams`` can be spawned directly from a parent generator +via `~Generator.spawn`: + +.. code-block:: python + + parent_rng = default_rng(12345) + streams = parent_rng.spawn(10) + +.. end_block + +Child objects can also spawn to make grandchildren, and so on. +Each child has a `~SeedSequence` with its position in the tree of spawned +child objects mixed in with the user-provided seed to generate independent +(with very high probability) streams. .. code-block:: python - grandchildren = child_seeds[0].spawn(4) - grand_streams = [default_rng(s) for s in grandchildren] + grandchildren = streams[0].spawn(4) .. end_block diff --git a/doc/source/reference/routines.ctypeslib.rst b/doc/source/reference/routines.ctypeslib.rst index c6127ca64..fe5ffb5a8 100644 --- a/doc/source/reference/routines.ctypeslib.rst +++ b/doc/source/reference/routines.ctypeslib.rst @@ -1,7 +1,7 @@ .. module:: numpy.ctypeslib *********************************************************** -C-Types Foreign Function Interface (:mod:`numpy.ctypeslib`) +C-Types foreign function interface (:mod:`numpy.ctypeslib`) *********************************************************** .. currentmodule:: numpy.ctypeslib diff --git a/doc/source/reference/routines.datetime.rst b/doc/source/reference/routines.datetime.rst index 966ed5a47..72513882b 100644 --- a/doc/source/reference/routines.datetime.rst +++ b/doc/source/reference/routines.datetime.rst @@ -1,6 +1,6 @@ .. _routines.datetime: -Datetime Support Functions +Datetime support functions ************************** .. currentmodule:: numpy @@ -12,7 +12,7 @@ Datetime Support Functions datetime_data -Business Day Functions +Business day functions ====================== .. currentmodule:: numpy diff --git a/doc/source/reference/routines.dual.rst b/doc/source/reference/routines.dual.rst deleted file mode 100644 index 18c7791d0..000000000 --- a/doc/source/reference/routines.dual.rst +++ /dev/null @@ -1,47 +0,0 @@ -Optionally SciPy-accelerated routines (:mod:`numpy.dual`) -========================================================= - -.. automodule:: numpy.dual - -Linear algebra --------------- - -.. currentmodule:: numpy.linalg - -.. autosummary:: - - cholesky - det - eig - eigh - eigvals - eigvalsh - inv - lstsq - norm - pinv - solve - svd - -FFT ---- - -.. currentmodule:: numpy.fft - -.. autosummary:: - - fft - fft2 - fftn - ifft - ifft2 - ifftn - -Other ------ - -.. currentmodule:: numpy - -.. autosummary:: - - i0 diff --git a/doc/source/reference/routines.io.rst b/doc/source/reference/routines.io.rst index 2542b336f..1ec2ccb5e 100644 --- a/doc/source/reference/routines.io.rst +++ b/doc/source/reference/routines.io.rst @@ -83,7 +83,7 @@ Data sources DataSource -Binary Format Description +Binary format description ------------------------- .. autosummary:: :toctree: generated/ diff --git a/doc/source/reference/routines.ma.rst b/doc/source/reference/routines.ma.rst index d503cc243..fd22a74aa 100644 --- a/doc/source/reference/routines.ma.rst +++ b/doc/source/reference/routines.ma.rst @@ -31,6 +31,7 @@ From existing data ma.fromfunction ma.MaskedArray.copy + ma.diagflat Ones and zeros @@ -72,6 +73,9 @@ Inspecting the array ma.isMaskedArray ma.isMA ma.isarray + ma.isin + ma.in1d + ma.unique ma.MaskedArray.all @@ -394,6 +398,17 @@ Clipping and rounding ma.MaskedArray.clip ma.MaskedArray.round +Set operations +~~~~~~~~~~~~~~ +.. autosummary:: + :toctree: generated/ + + + ma.intersect1d + ma.setdiff1d + ma.setxor1d + ma.union1d + Miscellanea ~~~~~~~~~~~ diff --git a/doc/source/reference/routines.math.rst b/doc/source/reference/routines.math.rst index 35771cc9c..4cc8719fb 100644 --- a/doc/source/reference/routines.math.rst +++ b/doc/source/reference/routines.math.rst @@ -39,6 +39,7 @@ Rounding .. autosummary:: :toctree: generated/ + round around rint fix @@ -148,13 +149,15 @@ Extrema Finding :toctree: generated/ maximum - fmax + max amax + fmax nanmax minimum - fmin + min amin + fmin nanmin diff --git a/doc/source/reference/routines.other.rst b/doc/source/reference/routines.other.rst index 7b60545f1..769b3d910 100644 --- a/doc/source/reference/routines.other.rst +++ b/doc/source/reference/routines.other.rst @@ -59,3 +59,5 @@ Matlab-like Functions disp .. automodule:: numpy.exceptions + +.. automodule:: numpy.dtypes diff --git a/doc/source/reference/routines.rst b/doc/source/reference/routines.rst index 24117895b..72ed80972 100644 --- a/doc/source/reference/routines.rst +++ b/doc/source/reference/routines.rst @@ -24,7 +24,6 @@ indentation. routines.ctypeslib routines.datetime routines.dtype - routines.dual routines.emath routines.err routines.fft diff --git a/doc/source/reference/routines.testing.rst b/doc/source/reference/routines.testing.rst index 16d53bb4e..82e43dfdb 100644 --- a/doc/source/reference/routines.testing.rst +++ b/doc/source/reference/routines.testing.rst @@ -51,11 +51,6 @@ Decorators .. autosummary:: :toctree: generated/ - dec.deprecated - dec.knownfailureif - dec.setastest - dec.skipif - dec.slow decorate_methods Test Running @@ -63,10 +58,8 @@ Test Running .. autosummary:: :toctree: generated/ - Tester clear_and_catch_warnings measure - run_module_suite rundocs suppress_warnings diff --git a/doc/source/reference/simd/build-options.rst b/doc/source/reference/simd/build-options.rst index 0994f15aa..d1e2e6b8e 100644 --- a/doc/source/reference/simd/build-options.rst +++ b/doc/source/reference/simd/build-options.rst @@ -333,7 +333,7 @@ and here is how it looks on x86_64/gcc: .. literalinclude:: log_example.txt :language: bash -As you see, there is a separate report for each of ``build_ext`` and ``build_clib`` +There is a separate report for each of ``build_ext`` and ``build_clib`` that includes several sections, and each section has several values, representing the following: **Platform**: @@ -371,6 +371,17 @@ that includes several sections, and each section has several values, representin - The lines that come after the above property and end with a ':' on a separate line, represent the paths of c/c++ sources that define the generated optimizations. -Runtime Trace -------------- -To be completed. +.. _runtime-simd-dispatch: + +Runtime dispatch +---------------- +Importing NumPy triggers a scan of the available CPU features from the set +of dispatchable features. This can be further restricted by setting the +environment variable ``NPY_DISABLE_CPU_FEATURES`` to a comma-, tab-, or +space-separated list of features to disable. This will raise an error if +parsing fails or if the feature was not enabled. For instance, on ``x86_64`` +this will disable ``AVX2`` and ``FMA3``:: + + NPY_DISABLE_CPU_FEATURES="AVX2,FMA3" + +If the feature is not available, a warning will be emitted. diff --git a/doc/source/reference/simd/gen_features.py b/doc/source/reference/simd/gen_features.py index 9a38ef5c9..b141e23d0 100644 --- a/doc/source/reference/simd/gen_features.py +++ b/doc/source/reference/simd/gen_features.py @@ -168,7 +168,7 @@ if __name__ == '__main__': gen_path = path.join( path.dirname(path.realpath(__file__)), "generated_tables" ) - with open(path.join(gen_path, 'cpu_features.inc'), 'wt') as fd: + with open(path.join(gen_path, 'cpu_features.inc'), 'w') as fd: fd.write(f'.. generated via {__file__}\n\n') for arch in ( ("x86", "PPC64", "PPC64LE", "ARMHF", "AARCH64", "S390X") @@ -177,7 +177,7 @@ if __name__ == '__main__': table = Features(arch, 'gcc').table() fd.write(wrapper_section(title, table)) - with open(path.join(gen_path, 'compilers-diff.inc'), 'wt') as fd: + with open(path.join(gen_path, 'compilers-diff.inc'), 'w') as fd: fd.write(f'.. generated via {__file__}\n\n') for arch, cc_names in ( ("x86", ("clang", "ICC", "MSVC")), diff --git a/doc/source/reference/simd/generated_tables/compilers-diff.inc b/doc/source/reference/simd/generated_tables/compilers-diff.inc index 4b9009a68..d5a87da3c 100644 --- a/doc/source/reference/simd/generated_tables/compilers-diff.inc +++ b/doc/source/reference/simd/generated_tables/compilers-diff.inc @@ -1,33 +1,35 @@ -.. generated via /home/seiko/work/repos/numpy/doc/source/reference/simd/./gen_features.py +.. generated via /numpy/numpy/./doc/source/reference/simd/gen_features.py On x86::Intel Compiler ~~~~~~~~~~~~~~~~~~~~~~ .. table:: :align: left - ================ ========================================================================================================================================== - Name Implies - ================ ========================================================================================================================================== - FMA3 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`AVX2` - AVX2 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`FMA3` - AVX512F SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 :enabled:`AVX512CD` - :disabled:`XOP` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` - :disabled:`FMA4` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` - ================ ========================================================================================================================================== + ====================== ================================================================================================================================================================================================================================================================================================================================== ====================== + Name Implies Gathers + ====================== ================================================================================================================================================================================================================================================================================================================================== ====================== + FMA3 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`AVX2` + AVX2 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`FMA3` + AVX512F SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 :enabled:`AVX512CD` + :disabled:`XOP` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` + :disabled:`FMA4` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` + :disabled:`AVX512_SPR` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` :disabled:`F16C` :disabled:`FMA3` :disabled:`AVX2` :disabled:`AVX512F` :disabled:`AVX512CD` :disabled:`AVX512_SKX` :disabled:`AVX512_CLX` :disabled:`AVX512_CNL` :disabled:`AVX512_ICL` :disabled:`AVX512FP16` + ====================== ================================================================================================================================================================================================================================================================================================================================== ====================== On x86::Microsoft Visual C/C++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. table:: :align: left - ====================== ============================================================================================================================================================================================================================================================= ============================================================================= - Name Implies Gathers - ====================== ============================================================================================================================================================================================================================================================= ============================================================================= - FMA3 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`AVX2` - AVX2 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`FMA3` - AVX512F SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 :enabled:`AVX512CD` :enabled:`AVX512_SKX` - AVX512CD SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F :enabled:`AVX512_SKX` - :disabled:`AVX512_KNL` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` :disabled:`F16C` :disabled:`FMA3` :disabled:`AVX2` :disabled:`AVX512F` :disabled:`AVX512CD` :disabled:`AVX512ER` :disabled:`AVX512PF` - :disabled:`AVX512_KNM` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` :disabled:`F16C` :disabled:`FMA3` :disabled:`AVX2` :disabled:`AVX512F` :disabled:`AVX512CD` :disabled:`AVX512_KNL` :disabled:`AVX5124FMAPS` :disabled:`AVX5124VNNIW` :disabled:`AVX512VPOPCNTDQ` - ====================== ============================================================================================================================================================================================================================================================= ============================================================================= + ====================== ================================================================================================================================================================================================================================================================================================================================== ============================================================================= + Name Implies Gathers + ====================== ================================================================================================================================================================================================================================================================================================================================== ============================================================================= + FMA3 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`AVX2` + AVX2 SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C :enabled:`FMA3` + AVX512F SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 :enabled:`AVX512CD` :enabled:`AVX512_SKX` + AVX512CD SSE SSE2 SSE3 SSSE3 SSE41 POPCNT SSE42 AVX F16C FMA3 AVX2 AVX512F :enabled:`AVX512_SKX` + :disabled:`AVX512_KNL` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` :disabled:`F16C` :disabled:`FMA3` :disabled:`AVX2` :disabled:`AVX512F` :disabled:`AVX512CD` :disabled:`AVX512ER` :disabled:`AVX512PF` + :disabled:`AVX512_KNM` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` :disabled:`F16C` :disabled:`FMA3` :disabled:`AVX2` :disabled:`AVX512F` :disabled:`AVX512CD` :disabled:`AVX512_KNL` :disabled:`AVX5124FMAPS` :disabled:`AVX5124VNNIW` :disabled:`AVX512VPOPCNTDQ` + :disabled:`AVX512_SPR` :disabled:`SSE` :disabled:`SSE2` :disabled:`SSE3` :disabled:`SSSE3` :disabled:`SSE41` :disabled:`POPCNT` :disabled:`SSE42` :disabled:`AVX` :disabled:`F16C` :disabled:`FMA3` :disabled:`AVX2` :disabled:`AVX512F` :disabled:`AVX512CD` :disabled:`AVX512_SKX` :disabled:`AVX512_CLX` :disabled:`AVX512_CNL` :disabled:`AVX512_ICL` :disabled:`AVX512FP16` + ====================== ================================================================================================================================================================================================================================================================================================================================== ============================================================================= diff --git a/doc/source/reference/simd/generated_tables/cpu_features.inc b/doc/source/reference/simd/generated_tables/cpu_features.inc index 7782172d2..603370e21 100644 --- a/doc/source/reference/simd/generated_tables/cpu_features.inc +++ b/doc/source/reference/simd/generated_tables/cpu_features.inc @@ -1,35 +1,36 @@ -.. generated via /home/seiko/work/repos/review/numpy/doc/source/reference/simd/gen_features.py +.. generated via /numpy/numpy/./doc/source/reference/simd/gen_features.py On x86 ~~~~~~ .. table:: :align: left - ============== =========================================================================================================================================================================== ===================================================== - Name Implies Gathers - ============== =========================================================================================================================================================================== ===================================================== - ``SSE`` ``SSE2`` - ``SSE2`` ``SSE`` - ``SSE3`` ``SSE`` ``SSE2`` - ``SSSE3`` ``SSE`` ``SSE2`` ``SSE3`` - ``SSE41`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` - ``POPCNT`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` - ``SSE42`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` - ``AVX`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` - ``XOP`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` - ``FMA4`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` - ``F16C`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` - ``FMA3`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` - ``AVX2`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` - ``AVX512F`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` - ``AVX512CD`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` - ``AVX512_KNL`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512ER`` ``AVX512PF`` - ``AVX512_KNM`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_KNL`` ``AVX5124FMAPS`` ``AVX5124VNNIW`` ``AVX512VPOPCNTDQ`` - ``AVX512_SKX`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512VL`` ``AVX512BW`` ``AVX512DQ`` - ``AVX512_CLX`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_SKX`` ``AVX512VNNI`` - ``AVX512_CNL`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_SKX`` ``AVX512IFMA`` ``AVX512VBMI`` - ``AVX512_ICL`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_SKX`` ``AVX512_CLX`` ``AVX512_CNL`` ``AVX512VBMI2`` ``AVX512BITALG`` ``AVX512VPOPCNTDQ`` - ============== =========================================================================================================================================================================== ===================================================== + ============== ========================================================================================================================================================================================== ===================================================== + Name Implies Gathers + ============== ========================================================================================================================================================================================== ===================================================== + ``SSE`` ``SSE2`` + ``SSE2`` ``SSE`` + ``SSE3`` ``SSE`` ``SSE2`` + ``SSSE3`` ``SSE`` ``SSE2`` ``SSE3`` + ``SSE41`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` + ``POPCNT`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` + ``SSE42`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` + ``AVX`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` + ``XOP`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` + ``FMA4`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` + ``F16C`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` + ``FMA3`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` + ``AVX2`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` + ``AVX512F`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` + ``AVX512CD`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` + ``AVX512_KNL`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512ER`` ``AVX512PF`` + ``AVX512_KNM`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_KNL`` ``AVX5124FMAPS`` ``AVX5124VNNIW`` ``AVX512VPOPCNTDQ`` + ``AVX512_SKX`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512VL`` ``AVX512BW`` ``AVX512DQ`` + ``AVX512_CLX`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_SKX`` ``AVX512VNNI`` + ``AVX512_CNL`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_SKX`` ``AVX512IFMA`` ``AVX512VBMI`` + ``AVX512_ICL`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_SKX`` ``AVX512_CLX`` ``AVX512_CNL`` ``AVX512VBMI2`` ``AVX512BITALG`` ``AVX512VPOPCNTDQ`` + ``AVX512_SPR`` ``SSE`` ``SSE2`` ``SSE3`` ``SSSE3`` ``SSE41`` ``POPCNT`` ``SSE42`` ``AVX`` ``F16C`` ``FMA3`` ``AVX2`` ``AVX512F`` ``AVX512CD`` ``AVX512_SKX`` ``AVX512_CLX`` ``AVX512_CNL`` ``AVX512_ICL`` ``AVX512FP16`` + ============== ========================================================================================================================================================================================== ===================================================== On IBM/POWER big-endian ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/reference/simd/how-it-works.rst b/doc/source/reference/simd/how-it-works.rst index 19b3dba45..dac80dd02 100644 --- a/doc/source/reference/simd/how-it-works.rst +++ b/doc/source/reference/simd/how-it-works.rst @@ -1,6 +1,6 @@ -********************************** +********************************* How does the CPU dispatcher work? -********************************** +********************************* NumPy dispatcher is based on multi-source compiling, which means taking a certain source and compiling it multiple times with different compiler diff --git a/doc/source/release.rst b/doc/source/release.rst index 84aff7f66..b8a877924 100644 --- a/doc/source/release.rst +++ b/doc/source/release.rst @@ -6,6 +6,9 @@ Release notes :maxdepth: 3 1.25.0 <release/1.25.0-notes> + 1.24.3 <release/1.24.3-notes> + 1.24.2 <release/1.24.2-notes> + 1.24.1 <release/1.24.1-notes> 1.24.0 <release/1.24.0-notes> 1.23.5 <release/1.23.5-notes> 1.23.4 <release/1.23.4-notes> diff --git a/doc/source/release/1.15.0-notes.rst b/doc/source/release/1.15.0-notes.rst index 2d9d068e5..e84386f0f 100644 --- a/doc/source/release/1.15.0-notes.rst +++ b/doc/source/release/1.15.0-notes.rst @@ -92,7 +92,7 @@ Deprecations ``np.sum(np.from_iter(generator))`` or the built-in Python ``sum`` instead. * Users of the C-API should call ``PyArrayResolveWriteBackIfCopy`` or - ``PyArray_DiscardWritbackIfCopy`` on any array with the ``WRITEBACKIFCOPY`` + ``PyArray_DiscardWritebackIfCopy`` on any array with the ``WRITEBACKIFCOPY`` flag set, before deallocating the array. A deprecation warning will be emitted if those calls are not used when needed. diff --git a/doc/source/release/1.23.0-notes.rst b/doc/source/release/1.23.0-notes.rst index c5c23620a..2301192cc 100644 --- a/doc/source/release/1.23.0-notes.rst +++ b/doc/source/release/1.23.0-notes.rst @@ -83,8 +83,8 @@ Expired deprecations * The ``UPDATEIFCOPY`` array flag has been removed together with the enum ``NPY_ARRAY_UPDATEIFCOPY``. The associated (and deprecated) ``PyArray_XDECREF_ERR`` was also removed. These were all deprecated in 1.14. They - are replaced by ``WRITEBACKIFCOPY``, that requires calling - ``PyArray_ResoveWritebackIfCopy`` before the array is deallocated. + are replaced by ``NPY_ARRAY_WRITEBACKIFCOPY``, that requires calling + ``PyArray_ResolveWritebackIfCopy`` before the array is deallocated. (`gh-20589 <https://github.com/numpy/numpy/pull/20589>`__) diff --git a/doc/source/release/1.24.0-notes.rst b/doc/source/release/1.24.0-notes.rst index 68134bce2..1c9e719b3 100644 --- a/doc/source/release/1.24.0-notes.rst +++ b/doc/source/release/1.24.0-notes.rst @@ -1,45 +1,515 @@ .. currentmodule:: numpy -========================== -NumPy 1.24.0 Release Notes -========================== +======================== +NumPy 1.24 Release Notes +======================== +The NumPy 1.24.0 release continues the ongoing work to improve the handling and +promotion of dtypes, increase the execution speed, and clarify the +documentation. There are also a large number of new and expired deprecations +due to changes in promotion and cleanups. This might be called a deprecation +release. Highlights are +* Many new deprecations, check them out. +* Many expired deprecations, +* New F2PY features and fixes. +* New "dtype" and "casting" keywords for stacking functions. -Highlights -========== +See below for the details, - -New functions -============= +This release supports Python versions 3.8-3.11. Deprecations ============ +Deprecate fastCopyAndTranspose and PyArray_CopyAndTranspose +----------------------------------------------------------- +The ``numpy.fastCopyAndTranspose`` function has been deprecated. Use the +corresponding copy and transpose methods directly:: + + arr.T.copy() + +The underlying C function ``PyArray_CopyAndTranspose`` has also been deprecated +from the NumPy C-API. + +(`gh-22313 <https://github.com/numpy/numpy/pull/22313>`__) + +Conversion of out-of-bound Python integers +------------------------------------------ +Attempting a conversion from a Python integer to a NumPy value will now always +check whether the result can be represented by NumPy. This means the following +examples will fail in the future and give a ``DeprecationWarning`` now:: + + np.uint8(-1) + np.array([3000], dtype=np.int8) + +Many of these did succeed before. Such code was mainly useful for unsigned +integers with negative values such as ``np.uint8(-1)`` giving +``np.iinfo(np.uint8).max``. + +Note that conversion between NumPy integers is unaffected, so that +``np.array(-1).astype(np.uint8)`` continues to work and use C integer overflow +logic. For negative values, it will also work to view the array: +``np.array(-1, dtype=np.int8).view(np.uint8)``. +In some cases, using ``np.iinfo(np.uint8).max`` or ``val % 2**8`` may also +work well. -Future Changes -============== +In rare cases input data may mix both negative values and very large unsigned +values (i.e. ``-1`` and ``2**63``). There it is unfortunately necessary +to use ``%`` on the Python value or use signed or unsigned conversion +depending on whether negative values are expected. + +(`gh-22385 <https://github.com/numpy/numpy/pull/22385>`__) + +Deprecate ``msort`` +------------------- +The ``numpy.msort`` function is deprecated. Use ``np.sort(a, axis=0)`` instead. + +(`gh-22456 <https://github.com/numpy/numpy/pull/22456>`__) + +``np.str0`` and similar are now deprecated +------------------------------------------ +The scalar type aliases ending in a 0 bit size: ``np.object0``, ``np.str0``, +``np.bytes0``, ``np.void0``, ``np.int0``, ``np.uint0`` as well as ``np.bool8`` +are now deprecated and will eventually be removed. + +(`gh-22607 <https://github.com/numpy/numpy/pull/22607>`__) Expired deprecations ==================== +* The ``normed`` keyword argument has been removed from + `np.histogram`, `np.histogram2d`, and `np.histogramdd`. + Use ``density`` instead. If ``normed`` was passed by + position, ``density`` is now used. + + (`gh-21645 <https://github.com/numpy/numpy/pull/21645>`__) + +* Ragged array creation will now always raise a ``ValueError`` unless + ``dtype=object`` is passed. This includes very deeply nested sequences. + + (`gh-22004 <https://github.com/numpy/numpy/pull/22004>`__) + +* Support for Visual Studio 2015 and earlier has been removed. + +* Support for the Windows Interix POSIX interop layer has been removed. + + (`gh-22139 <https://github.com/numpy/numpy/pull/22139>`__) + +* Support for Cygwin < 3.3 has been removed. + + (`gh-22159 <https://github.com/numpy/numpy/pull/22159>`__) + +* The mini() method of ``np.ma.MaskedArray`` has been removed. Use either + ``np.ma.MaskedArray.min()`` or ``np.ma.minimum.reduce()``. + +* The single-argument form of ``np.ma.minimum`` and ``np.ma.maximum`` has been + removed. Use ``np.ma.minimum.reduce()`` or ``np.ma.maximum.reduce()`` + instead. + + (`gh-22228 <https://github.com/numpy/numpy/pull/22228>`__) + +* Passing dtype instances other than the canonical (mainly native byte-order) + ones to ``dtype=`` or ``signature=`` in ufuncs will now raise a + ``TypeError``. We recommend passing the strings ``"int8"`` or scalar types + ``np.int8`` since the byte-order, datetime/timedelta unit, etc. are never + enforced. (Initially deprecated in NumPy 1.21.) + + (`gh-22540 <https://github.com/numpy/numpy/pull/22540>`__) + +* The ``dtype=`` argument to comparison ufuncs is now applied correctly. That + means that only ``bool`` and ``object`` are valid values and ``dtype=object`` + is enforced. + + (`gh-22541 <https://github.com/numpy/numpy/pull/22541>`__) + +* The deprecation for the aliases ``np.object``, ``np.bool``, ``np.float``, + ``np.complex``, ``np.str``, and ``np.int`` is expired (introduces NumPy + 1.20). Some of these will now give a FutureWarning in addition to raising an + error since they will be mapped to the NumPy scalars in the future. + + (`gh-22607 <https://github.com/numpy/numpy/pull/22607>`__) + Compatibility notes =================== +``array.fill(scalar)`` may behave slightly different +---------------------------------------------------- +``numpy.ndarray.fill`` may in some cases behave slightly different now due to +the fact that the logic is aligned with item assignment:: + + arr = np.array([1]) # with any dtype/value + arr.fill(scalar) + # is now identical to: + arr[0] = scalar + +Previously casting may have produced slightly different answers when using +values that could not be represented in the target ``dtype`` or when the target +had ``object`` dtype. + +(`gh-20924 <https://github.com/numpy/numpy/pull/20924>`__) + +Subarray to object cast now copies +---------------------------------- +Casting a dtype that includes a subarray to an object will now ensure a copy of +the subarray. Previously an unsafe view was returned:: + + arr = np.ones(3, dtype=[("f", "i", 3)]) + subarray_fields = arr.astype(object)[0] + subarray = subarray_fields[0] # "f" field + + np.may_share_memory(subarray, arr) + +Is now always false. While previously it was true for the specific cast. + +(`gh-21925 <https://github.com/numpy/numpy/pull/21925>`__) + +Returned arrays respect uniqueness of dtype kwarg objects +--------------------------------------------------------- +When the ``dtype`` keyword argument is used with :py:func:`np.array()` or +:py:func:`asarray()`, the dtype of the returned array now always exactly +matches the dtype provided by the caller. + +In some cases this change means that a *view* rather than the input array is +returned. The following is an example for this on 64bit Linux where ``long`` +and ``longlong`` are the same precision but different ``dtypes``:: + + >>> arr = np.array([1, 2, 3], dtype="long") + >>> new_dtype = np.dtype("longlong") + >>> new = np.asarray(arr, dtype=new_dtype) + >>> new.dtype is new_dtype + True + >>> new is arr + False + +Before the change, the ``dtype`` did not match because ``new is arr`` was +``True``. + +(`gh-21995 <https://github.com/numpy/numpy/pull/21995>`__) + +DLPack export raises ``BufferError`` +------------------------------------ +When an array buffer cannot be exported via DLPack a ``BufferError`` is now +always raised where previously ``TypeError`` or ``RuntimeError`` was raised. +This allows falling back to the buffer protocol or ``__array_interface__`` when +DLPack was tried first. -C API changes -============= +(`gh-22542 <https://github.com/numpy/numpy/pull/22542>`__) + +NumPy builds are no longer tested on GCC-6 +------------------------------------------ +Ubuntu 18.04 is deprecated for GitHub actions and GCC-6 is not available on +Ubuntu 20.04, so builds using that compiler are no longer tested. We still test +builds using GCC-7 and GCC-8. + +(`gh-22598 <https://github.com/numpy/numpy/pull/22598>`__) New Features ============ +New attribute ``symbol`` added to polynomial classes +---------------------------------------------------- +The polynomial classes in the ``numpy.polynomial`` package have a new +``symbol`` attribute which is used to represent the indeterminate of the +polynomial. This can be used to change the value of the variable when +printing:: + + >>> P_y = np.polynomial.Polynomial([1, 0, -1], symbol="y") + >>> print(P_y) + 1.0 + 0.0·y¹ - 1.0·y² + +Note that the polynomial classes only support 1D polynomials, so operations +that involve polynomials with different symbols are disallowed when the result +would be multivariate:: + + >>> P = np.polynomial.Polynomial([1, -1]) # default symbol is "x" + >>> P_z = np.polynomial.Polynomial([1, 1], symbol="z") + >>> P * P_z + Traceback (most recent call last) + ... + ValueError: Polynomial symbols differ + +The symbol can be any valid Python identifier. The default is ``symbol=x``, +consistent with existing behavior. + +(`gh-16154 <https://github.com/numpy/numpy/pull/16154>`__) + +F2PY support for Fortran ``character`` strings +---------------------------------------------- +F2PY now supports wrapping Fortran functions with: + +* character (e.g. ``character x``) +* character array (e.g. ``character, dimension(n) :: x``) +* character string (e.g. ``character(len=10) x``) +* and character string array (e.g. ``character(len=10), dimension(n, m) :: x``) + +arguments, including passing Python unicode strings as Fortran character string +arguments. + +(`gh-19388 <https://github.com/numpy/numpy/pull/19388>`__) + +New function ``np.show_runtime`` +-------------------------------- +A new function ``numpy.show_runtime`` has been added to display the runtime +information of the machine in addition to ``numpy.show_config`` which displays +the build-related information. + +(`gh-21468 <https://github.com/numpy/numpy/pull/21468>`__) + +``strict`` option for ``testing.assert_array_equal`` +---------------------------------------------------- +The ``strict`` option is now available for ``testing.assert_array_equal``. +Setting ``strict=True`` will disable the broadcasting behaviour for scalars and +ensure that input arrays have the same data type. + +(`gh-21595 <https://github.com/numpy/numpy/pull/21595>`__) + +New parameter ``equal_nan`` added to ``np.unique`` +-------------------------------------------------- +``np.unique`` was changed in 1.21 to treat all ``NaN`` values as equal and +return a single ``NaN``. Setting ``equal_nan=False`` will restore pre-1.21 +behavior to treat ``NaNs`` as unique. Defaults to ``True``. + +(`gh-21623 <https://github.com/numpy/numpy/pull/21623>`__) + +``casting`` and ``dtype`` keyword arguments for ``numpy.stack`` +--------------------------------------------------------------- +The ``casting`` and ``dtype`` keyword arguments are now available for +``numpy.stack``. To use them, write ``np.stack(..., dtype=None, +casting='same_kind')``. + +``casting`` and ``dtype`` keyword arguments for ``numpy.vstack`` +---------------------------------------------------------------- +The ``casting`` and ``dtype`` keyword arguments are now available for +``numpy.vstack``. To use them, write ``np.vstack(..., dtype=None, +casting='same_kind')``. + +``casting`` and ``dtype`` keyword arguments for ``numpy.hstack`` +---------------------------------------------------------------- +The ``casting`` and ``dtype`` keyword arguments are now available for +``numpy.hstack``. To use them, write ``np.hstack(..., dtype=None, +casting='same_kind')``. + +(`gh-21627 <https://github.com/numpy/numpy/pull/21627>`__) + +The bit generator underlying the singleton RandomState can be changed +--------------------------------------------------------------------- +The singleton ``RandomState`` instance exposed in the ``numpy.random`` module +is initialized at startup with the ``MT19937`` bit generator. The new function +``set_bit_generator`` allows the default bit generator to be replaced with a +user-provided bit generator. This function has been introduced to provide a +method allowing seamless integration of a high-quality, modern bit generator in +new code with existing code that makes use of the singleton-provided random +variate generating functions. The companion function ``get_bit_generator`` +returns the current bit generator being used by the singleton ``RandomState``. +This is provided to simplify restoring the original source of randomness if +required. + +The preferred method to generate reproducible random numbers is to use a modern +bit generator in an instance of ``Generator``. The function ``default_rng`` +simplifies instantiation:: + + >>> rg = np.random.default_rng(3728973198) + >>> rg.random() + +The same bit generator can then be shared with the singleton instance so that +calling functions in the ``random`` module will use the same bit generator:: + + >>> orig_bit_gen = np.random.get_bit_generator() + >>> np.random.set_bit_generator(rg.bit_generator) + >>> np.random.normal() + +The swap is permanent (until reversed) and so any call to functions in the +``random`` module will use the new bit generator. The original can be restored +if required for code to run correctly:: + + >>> np.random.set_bit_generator(orig_bit_gen) + +(`gh-21976 <https://github.com/numpy/numpy/pull/21976>`__) + +``np.void`` now has a ``dtype`` argument +---------------------------------------- +NumPy now allows constructing structured void scalars directly by +passing the ``dtype`` argument to ``np.void``. + +(`gh-22316 <https://github.com/numpy/numpy/pull/22316>`__) + Improvements ============ +F2PY Improvements +----------------- +* The generated extension modules don't use the deprecated NumPy-C API anymore +* Improved ``f2py`` generated exception messages +* Numerous bug and ``flake8`` warning fixes +* various CPP macros that one can use within C-expressions of signature files + are prefixed with ``f2py_``. For example, one should use ``f2py_len(x)`` + instead of ``len(x)`` +* A new construct ``character(f2py_len=...)`` is introduced to support + returning assumed length character strings (e.g. ``character(len=*)``) from + wrapper functions + +A hook to support rewriting ``f2py`` internal data structures after reading all +its input files is introduced. This is required, for instance, for BC of SciPy +support where character arguments are treated as character strings arguments in +``C`` expressions. + +(`gh-19388 <https://github.com/numpy/numpy/pull/19388>`__) + +IBM zSystems Vector Extension Facility (SIMD) +--------------------------------------------- +Added support for SIMD extensions of zSystem (z13, z14, z15), through the +universal intrinsics interface. This support leads to performance improvements +for all SIMD kernels implemented using the universal intrinsics, including the +following operations: rint, floor, trunc, ceil, sqrt, absolute, square, +reciprocal, tanh, sin, cos, equal, not_equal, greater, greater_equal, less, +less_equal, maximum, minimum, fmax, fmin, argmax, argmin, add, subtract, +multiply, divide. + +(`gh-20913 <https://github.com/numpy/numpy/pull/20913>`__) + +NumPy now gives floating point errors in casts +---------------------------------------------- +In most cases, NumPy previously did not give floating point warnings or errors +when these happened during casts. For examples, casts like:: + + np.array([2e300]).astype(np.float32) # overflow for float32 + np.array([np.inf]).astype(np.int64) + +Should now generally give floating point warnings. These warnings should warn +that floating point overflow occurred. For errors when converting floating +point values to integers users should expect invalid value warnings. + +Users can modify the behavior of these warnings using ``np.errstate``. + +Note that for float to int casts, the exact warnings that are given may +be platform dependent. For example:: + + arr = np.full(100, fill_value=1000, dtype=np.float64) + arr.astype(np.int8) + +May give a result equivalent to (the intermediate cast means no warning is +given):: + + arr.astype(np.int64).astype(np.int8) + +May return an undefined result, with a warning set:: + + RuntimeWarning: invalid value encountered in cast + +The precise behavior is subject to the C99 standard and its implementation in +both software and hardware. + +(`gh-21437 <https://github.com/numpy/numpy/pull/21437>`__) + +F2PY supports the value attribute +--------------------------------- +The Fortran standard requires that variables declared with the ``value`` +attribute must be passed by value instead of reference. F2PY now supports this +use pattern correctly. So ``integer, intent(in), value :: x`` in Fortran codes +will have correct wrappers generated. + +(`gh-21807 <https://github.com/numpy/numpy/pull/21807>`__) + +Added pickle support for third-party BitGenerators +-------------------------------------------------- +The pickle format for bit generators was extended to allow each bit generator +to supply its own constructor when during pickling. Previous versions of NumPy +only supported unpickling ``Generator`` instances created with one of the core +set of bit generators supplied with NumPy. Attempting to unpickle a +``Generator`` that used a third-party bit generators would fail since the +constructor used during the unpickling was only aware of the bit generators +included in NumPy. + +(`gh-22014 <https://github.com/numpy/numpy/pull/22014>`__) + +arange() now explicitly fails with dtype=str +--------------------------------------------- +Previously, the ``np.arange(n, dtype=str)`` function worked for ``n=1`` and +``n=2``, but would raise a non-specific exception message for other values of +``n``. Now, it raises a `TypeError` informing that ``arange`` does not support +string dtypes:: + + >>> np.arange(2, dtype=str) + Traceback (most recent call last) + ... + TypeError: arange() not supported for inputs with DType <class 'numpy.dtype[str_]'>. + +(`gh-22055 <https://github.com/numpy/numpy/pull/22055>`__) + +``numpy.typing`` protocols are now runtime checkable +---------------------------------------------------- +The protocols used in ``numpy.typing.ArrayLike`` and ``numpy.typing.DTypeLike`` +are now properly marked as runtime checkable, making them easier to use for +runtime type checkers. + +(`gh-22357 <https://github.com/numpy/numpy/pull/22357>`__) + + +Performance improvements and changes +==================================== + +Faster version of ``np.isin`` and ``np.in1d`` for integer arrays +---------------------------------------------------------------- +``np.in1d`` (used by ``np.isin``) can now switch to a faster algorithm (up to +>10x faster) when it is passed two integer arrays. This is often automatically +used, but you can use ``kind="sort"`` or ``kind="table"`` to force the old or +new method, respectively. + +(`gh-12065 <https://github.com/numpy/numpy/pull/12065>`__) + +Faster comparison operators +---------------------------- +The comparison functions (``numpy.equal``, ``numpy.not_equal``, ``numpy.less``, +``numpy.less_equal``, ``numpy.greater`` and ``numpy.greater_equal``) are now +much faster as they are now vectorized with universal intrinsics. For a CPU +with SIMD extension AVX512BW, the performance gain is up to 2.57x, 1.65x and +19.15x for integer, float and boolean data types, respectively (with N=50000). + +(`gh-21483 <https://github.com/numpy/numpy/pull/21483>`__) + Changes ======= + +Better reporting of integer division overflow +--------------------------------------------- +Integer division overflow of scalars and arrays used to provide a +``RuntimeWarning`` and the return value was undefined leading to crashes at +rare occasions:: + + >>> np.array([np.iinfo(np.int32).min]*10, dtype=np.int32) // np.int32(-1) + <stdin>:1: RuntimeWarning: divide by zero encountered in floor_divide + array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0], dtype=int32) + +Integer division overflow now returns the input dtype's minimum value and raise +the following ``RuntimeWarning``:: + + >>> np.array([np.iinfo(np.int32).min]*10, dtype=np.int32) // np.int32(-1) + <stdin>:1: RuntimeWarning: overflow encountered in floor_divide + array([-2147483648, -2147483648, -2147483648, -2147483648, -2147483648, + -2147483648, -2147483648, -2147483648, -2147483648, -2147483648], + dtype=int32) + +(`gh-21506 <https://github.com/numpy/numpy/pull/21506>`__) + +``masked_invalid`` now modifies the mask in-place +------------------------------------------------- +When used with ``copy=False``, ``numpy.ma.masked_invalid`` now modifies the +input masked array in-place. This makes it behave identically to +``masked_where`` and better matches the documentation. + +(`gh-22046 <https://github.com/numpy/numpy/pull/22046>`__) + +``nditer``/``NpyIter`` allows all allocating all operands +--------------------------------------------------------- +The NumPy iterator available through ``np.nditer`` in Python and as ``NpyIter`` +in C now supports allocating all arrays. The iterator shape defaults to ``()`` +in this case. The operands dtype must be provided, since a "common dtype" +cannot be inferred from the other inputs. + +(`gh-22457 <https://github.com/numpy/numpy/pull/22457>`__) diff --git a/doc/source/release/1.24.1-notes.rst b/doc/source/release/1.24.1-notes.rst new file mode 100644 index 000000000..c346f6d20 --- /dev/null +++ b/doc/source/release/1.24.1-notes.rst @@ -0,0 +1,50 @@ +.. currentmodule:: numpy + +========================== +NumPy 1.24.1 Release Notes +========================== +NumPy 1.24.1 is a maintenance release that fixes bugs and regressions discovered after the +1.24.0 release. The Python versions supported by this release are 3.8-3.11. + +Contributors +============ + +A total of 12 people contributed to this release. People with a "+" by their +names contributed a patch for the first time. + +* Andrew Nelson +* Ben Greiner + +* Charles Harris +* Clément Robert +* Matteo Raso +* Matti Picus +* Melissa Weber Mendonça +* Miles Cranmer +* Ralf Gommers +* Rohit Goswami +* Sayed Adel +* Sebastian Berg + +Pull requests merged +==================== + +A total of 18 pull requests were merged for this release. + +* `#22820 <https://github.com/numpy/numpy/pull/22820>`__: BLD: add workaround in setup.py for newer setuptools +* `#22830 <https://github.com/numpy/numpy/pull/22830>`__: BLD: CIRRUS_TAG redux +* `#22831 <https://github.com/numpy/numpy/pull/22831>`__: DOC: fix a couple typos in 1.23 notes +* `#22832 <https://github.com/numpy/numpy/pull/22832>`__: BUG: Fix refcounting errors found using pytest-leaks +* `#22834 <https://github.com/numpy/numpy/pull/22834>`__: BUG, SIMD: Fix invalid value encountered in several ufuncs +* `#22837 <https://github.com/numpy/numpy/pull/22837>`__: TST: ignore more np.distutils.log imports +* `#22839 <https://github.com/numpy/numpy/pull/22839>`__: BUG: Do not use getdata() in np.ma.masked_invalid +* `#22847 <https://github.com/numpy/numpy/pull/22847>`__: BUG: Ensure correct behavior for rows ending in delimiter in... +* `#22848 <https://github.com/numpy/numpy/pull/22848>`__: BUG, SIMD: Fix the bitmask of the boolean comparison +* `#22857 <https://github.com/numpy/numpy/pull/22857>`__: BLD: Help raspian arm + clang 13 about __builtin_mul_overflow +* `#22858 <https://github.com/numpy/numpy/pull/22858>`__: API: Ensure a full mask is returned for masked_invalid +* `#22866 <https://github.com/numpy/numpy/pull/22866>`__: BUG: Polynomials now copy properly (#22669) +* `#22867 <https://github.com/numpy/numpy/pull/22867>`__: BUG, SIMD: Fix memory overlap in ufunc comparison loops +* `#22868 <https://github.com/numpy/numpy/pull/22868>`__: BUG: Fortify string casts against floating point warnings +* `#22875 <https://github.com/numpy/numpy/pull/22875>`__: TST: Ignore nan-warnings in randomized out tests +* `#22883 <https://github.com/numpy/numpy/pull/22883>`__: MAINT: restore npymath implementations needed for freebsd +* `#22884 <https://github.com/numpy/numpy/pull/22884>`__: BUG: Fix integer overflow in in1d for mixed integer dtypes #22877 +* `#22887 <https://github.com/numpy/numpy/pull/22887>`__: BUG: Use whole file for encoding checks with ``charset_normalizer``. diff --git a/doc/source/release/1.24.2-notes.rst b/doc/source/release/1.24.2-notes.rst new file mode 100644 index 000000000..9e9412244 --- /dev/null +++ b/doc/source/release/1.24.2-notes.rst @@ -0,0 +1,51 @@ +.. currentmodule:: numpy + +========================== +NumPy 1.24.2 Release Notes +========================== +NumPy 1.24.2 is a maintenance release that fixes bugs and regressions discovered after the +1.24.1 release. The Python versions supported by this release are 3.8-3.11. + +Contributors +============ + +A total of 14 people contributed to this release. People with a "+" by their +names contributed a patch for the first time. + +* Bas van Beek +* Charles Harris +* Khem Raj + +* Mark Harfouche +* Matti Picus +* Panagiotis Zestanakis + +* Peter Hawkins +* Pradipta Ghosh +* Ross Barnowski +* Sayed Adel +* Sebastian Berg +* Syam Gadde + +* dmbelov + +* pkubaj + + +Pull requests merged +==================== + +A total of 17 pull requests were merged for this release. + +* `#22965 <https://github.com/numpy/numpy/pull/22965>`__: MAINT: Update python 3.11-dev to 3.11. +* `#22966 <https://github.com/numpy/numpy/pull/22966>`__: DOC: Remove dangling deprecation warning +* `#22967 <https://github.com/numpy/numpy/pull/22967>`__: ENH: Detect CPU features on FreeBSD/powerpc64* +* `#22968 <https://github.com/numpy/numpy/pull/22968>`__: BUG: np.loadtxt cannot load text file with quoted fields separated... +* `#22969 <https://github.com/numpy/numpy/pull/22969>`__: TST: Add fixture to avoid issue with randomizing test order. +* `#22970 <https://github.com/numpy/numpy/pull/22970>`__: BUG: Fix fill violating read-only flag. (#22959) +* `#22971 <https://github.com/numpy/numpy/pull/22971>`__: MAINT: Add additional information to missing scalar AttributeError +* `#22972 <https://github.com/numpy/numpy/pull/22972>`__: MAINT: Move export for scipy arm64 helper into main module +* `#22976 <https://github.com/numpy/numpy/pull/22976>`__: BUG, SIMD: Fix spurious invalid exception for sin/cos on arm64/clang +* `#22989 <https://github.com/numpy/numpy/pull/22989>`__: BUG: Ensure correct loop order in sin, cos, and arctan2 +* `#23030 <https://github.com/numpy/numpy/pull/23030>`__: DOC: Add version added information for the strict parameter in... +* `#23031 <https://github.com/numpy/numpy/pull/23031>`__: BUG: use ``_Alignof`` rather than ``offsetof()`` on most compilers +* `#23147 <https://github.com/numpy/numpy/pull/23147>`__: BUG: Fix for npyv__trunc_s32_f32 (VXE) +* `#23148 <https://github.com/numpy/numpy/pull/23148>`__: BUG: Fix integer / float scalar promotion +* `#23149 <https://github.com/numpy/numpy/pull/23149>`__: BUG: Add missing <type_traits> header. +* `#23150 <https://github.com/numpy/numpy/pull/23150>`__: TYP, MAINT: Add a missing explicit ``Any`` parameter to the ``npt.ArrayLike``... +* `#23161 <https://github.com/numpy/numpy/pull/23161>`__: BLD: remove redundant definition of npy_nextafter [wheel build] diff --git a/doc/source/release/1.24.3-notes.rst b/doc/source/release/1.24.3-notes.rst new file mode 100644 index 000000000..1aaf79cb6 --- /dev/null +++ b/doc/source/release/1.24.3-notes.rst @@ -0,0 +1,49 @@ +.. currentmodule:: numpy + +========================== +NumPy 1.24.3 Release Notes +========================== +NumPy 1.24.3 is a maintenance release that fixes bugs and regressions discovered after the +1.24.2 release. The Python versions supported by this release are 3.8-3.11. + +Contributors +============ + +A total of 12 people contributed to this release. People with a "+" by their +names contributed a patch for the first time. + +* Aleksei Nikiforov + +* Alexander Heger +* Bas van Beek +* Bob Eldering +* Brock Mendel +* Charles Harris +* Kyle Sunden +* Peter Hawkins +* Rohit Goswami +* Sebastian Berg +* Warren Weckesser +* dependabot[bot] + +Pull requests merged +==================== + +A total of 17 pull requests were merged for this release. + +* `#23206 <https://github.com/numpy/numpy/pull/23206>`__: BUG: fix for f2py string scalars (#23194) +* `#23207 <https://github.com/numpy/numpy/pull/23207>`__: BUG: datetime64/timedelta64 comparisons return NotImplemented +* `#23208 <https://github.com/numpy/numpy/pull/23208>`__: MAINT: Pin matplotlib to version 3.6.3 for refguide checks +* `#23221 <https://github.com/numpy/numpy/pull/23221>`__: DOC: Fix matplotlib error in documentation +* `#23226 <https://github.com/numpy/numpy/pull/23226>`__: CI: Ensure submodules are initialized in gitpod. +* `#23341 <https://github.com/numpy/numpy/pull/23341>`__: TYP: Replace duplicate reduce in ufunc type signature with reduceat. +* `#23342 <https://github.com/numpy/numpy/pull/23342>`__: TYP: Remove duplicate CLIP/WRAP/RAISE in ``__init__.pyi``. +* `#23343 <https://github.com/numpy/numpy/pull/23343>`__: TYP: Mark ``d`` argument to fftfreq and rfftfreq as optional... +* `#23344 <https://github.com/numpy/numpy/pull/23344>`__: TYP: Add type annotations for comparison operators to MaskedArray. +* `#23345 <https://github.com/numpy/numpy/pull/23345>`__: TYP: Remove some stray type-check-only imports of ``msort`` +* `#23370 <https://github.com/numpy/numpy/pull/23370>`__: BUG: Ensure like is only stripped for ``like=`` dispatched functions +* `#23543 <https://github.com/numpy/numpy/pull/23543>`__: BUG: fix loading and storing big arrays on s390x +* `#23544 <https://github.com/numpy/numpy/pull/23544>`__: MAINT: Bump larsoner/circleci-artifacts-redirector-action +* `#23634 <https://github.com/numpy/numpy/pull/23634>`__: BUG: Ignore invalid and overflow warnings in masked setitem +* `#23635 <https://github.com/numpy/numpy/pull/23635>`__: BUG: Fix masked array raveling when ``order="A"`` or ``order="K"`` +* `#23636 <https://github.com/numpy/numpy/pull/23636>`__: MAINT: Update conftest for newer hypothesis versions +* `#23637 <https://github.com/numpy/numpy/pull/23637>`__: BUG: Fix bug in parsing F77 style string arrays. 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> |
