diff options
Diffstat (limited to 'doc')
195 files changed, 3510 insertions, 1522 deletions
diff --git a/doc/changelog/1.23.5-changelog.rst b/doc/changelog/1.23.5-changelog.rst new file mode 100644 index 000000000..e24a291e4 --- /dev/null +++ b/doc/changelog/1.23.5-changelog.rst @@ -0,0 +1,30 @@ + +Contributors +============ + +A total of 7 people contributed to this release. People with a "+" by their +names contributed a patch for the first time. + +* @DWesl +* Aayush Agrawal + +* Adam Knapp + +* Charles Harris +* Navpreet Singh + +* Sebastian Berg +* Tania Allard + +Pull requests merged +==================== + +A total of 10 pull requests were merged for this release. + +* `#22489 <https://github.com/numpy/numpy/pull/22489>`__: TST, MAINT: Replace most setup with setup_method (also teardown) +* `#22490 <https://github.com/numpy/numpy/pull/22490>`__: MAINT, CI: Switch to cygwin/cygwin-install-action@v2 +* `#22494 <https://github.com/numpy/numpy/pull/22494>`__: TST: Make test_partial_iteration_cleanup robust but require leak... +* `#22592 <https://github.com/numpy/numpy/pull/22592>`__: MAINT: Ensure graceful handling of large header sizes +* `#22593 <https://github.com/numpy/numpy/pull/22593>`__: TYP: Spelling alignment for array flag literal +* `#22594 <https://github.com/numpy/numpy/pull/22594>`__: BUG: Fix bounds checking for ``random.logseries`` +* `#22595 <https://github.com/numpy/numpy/pull/22595>`__: DEV: Update GH actions and Dockerfile for Gitpod +* `#22596 <https://github.com/numpy/numpy/pull/22596>`__: CI: Only fetch in actions/checkout +* `#22597 <https://github.com/numpy/numpy/pull/22597>`__: BUG: Decrement ref count in gentype_reduce if allocated memory... +* `#22625 <https://github.com/numpy/numpy/pull/22625>`__: BUG: Histogramdd breaks on big arrays in Windows diff --git a/doc/changelog/1.24.0-changelog.rst b/doc/changelog/1.24.0-changelog.rst new file mode 100644 index 000000000..7ae8cd4c9 --- /dev/null +++ b/doc/changelog/1.24.0-changelog.rst @@ -0,0 +1,634 @@ + +Contributors +============ + +A total of 177 people contributed to this release. People with a "+" by their +names contributed a patch for the first time. + +* @DWesl +* @amagicmuffin + +* @dg3192 + +* @h-vetinari +* @juztamau5 + +* @swagatip + +* Aaron Meurer +* Aayush Agrawal + +* Adam Knapp + +* Adarsh Singh + +* Al-Baraa El-Hag +* Alban Desmaison + +* Ales Crocaro + +* Alex Low + +* Alexander Grund + +* Alexander Kanavin + +* Andras Deak +* Andrew Nelson +* Angéllica Araujo + +* Anselm Hahn + +* Ari Cooper Davis + +* Axel Huebl + +* Bas van Beek +* Bhavuk Kalra +* Bram Ton + +* Brent Tan + +* Brigitta Sipőcz +* Callum O'Riley + +* Charles Harris +* Chiara Marmo +* Christoph Reiter +* Damien Caliste +* Dan Schult + +* Daniel da Silva +* DanielHabenicht + +* Dave Goel + +* David Gilbertson + +* Developer-Ecosystem-Engineering +* Digya Acharya + +* Dimitri Papadopoulos Orfanos +* Eric-Shang + +* Evgeni Burovski +* Ewout ter Hoeven +* Felix Hirwa Nshuti + +* Frazer McLean + +* Ganesh Kathiresan +* Gavin Zhang + +* Gaëtan de Menten +* Greg Lucas +* Greg Sadetsky + +* Gregory P. Smith [Google LLC] + +* Hameer Abbasi +* Hannah Aizenman + +* Hood Chatham +* I-Shen Leong +* Iantra Solari + +* Ikko Ashimine + +* Inessa Pawson +* Jake Bowhay + +* Jake Close + +* Jarrod Millman +* Jason Thai +* JessePires + +* Jessé Pires + +* Jhonatan Cunha + +* Jingxuan He + +* Johnathon Cusick + +* Jon Morris +* Jordy Williams + +* Josh Wilson +* João Fontes Gonçalves + +* Juan Luis Cano Rodríguez +* Jyn Spring 琴春 + +* KIU Shueng Chuan +* Karl Otness + +* Kevin Sheppard +* Kinshuk Dua + +* Leo Fang +* Leona Taric + +* Lev Maximov + +* Lillian Zha + +* Loïc Estève +* M. Eric Irrgang + +* Mariusz Felisiak +* Mark Harfouche +* Martin Zacho + +* Matheus Santana Patriarca + +* Matt Williams + +* Matteo Raso + +* Matthew Barber +* Matthew Brett +* Matthew Sterrett + +* Matthias Bussonnier +* Matthias Koeppe + +* Matti Picus +* Meekail Zain + +* Melissa Weber Mendonça +* Michael Osthege + +* Michael Siebert + +* Mike Toews +* Miki Watanabe + +* Miles Cranmer + +* Monika Kubek + +* Muhammad Jarir Kanji + +* Mukulika Pahari +* Namami Shanker +* Nathan Goldbaum + +* Nathan Rooy + +* Navpreet Singh + +* Noritada Kobayashi + +* Oleksiy Kononenko + +* Omar Ali + +* Pal Barta + +* Pamphile Roy +* Patrick Hoefler + +* Pearu Peterson +* Pedro Nacht + +* Petar Mlinarić + +* Peter Hawkins +* Pey Lian Lim +* Pieter Eendebak +* Pradipta Ghosh +* Pranab Das + +* Precision Wordcraft LLC + +* PrecisionWordcraft + +* Rafael CF Sousa + +* Rafael Cardoso Fernandes Sousa +* Rafael Sousa + +* Raghuveer Devulapalli +* Ralf Gommers +* Rin Cat (鈴猫) + +* Robert Kern +* Rohit Davas + +* Rohit Goswami +* Ross Barnowski +* Roy Smart + +* Ruth Comer + +* Sabiha Tahsin Soha + +* Sachin Krishnan T V + +* Sanjana M Moodbagil + +* Sanya Sinha + +* Sarah Coffland + +* Saransh Chopra + +* Satish Kumar Mishra + +* Satish Mishra + +* Sayed Adel +* Schrijvers Luc + +* Sebastian Berg +* Serge Guelton +* Seva Lotoshnikov + +* Shashank Gupta + +* Shoban Chiddarth + +* Shreya Singh + +* Shreyas Joshi + +* Sicheng Zeng + +* Simran Makandar + +* Shuangchi He + +* Srimukh Sripada + +* Stefan van der Walt +* Stefanie Molin + +* Stuart Archibald +* Tania Allard +* Thomas A Caswell +* Thomas Kastl + +* Thomas Mansencal + +* Tony Newton / Teng Liu + +* Toshiki Kataoka +* Tyler Reddy +* Vardhaman Kalloli + +* Warren Weckesser +* Will Ayd + +* William Stein + +* XinRu Lin + +* Yin Li + +* Yunika Bajracharya + +* Zachary Blackwood + +* 渡邉 美希 + + +Pull requests merged +==================== + +A total of 444 pull requests were merged for this release. + +* `#12065 <https://github.com/numpy/numpy/pull/12065>`__: API: Optimize np.isin and np.in1d for integer arrays and add... +* `#15782 <https://github.com/numpy/numpy/pull/15782>`__: ENH: complete the 'vars' list of a module +* `#16022 <https://github.com/numpy/numpy/pull/16022>`__: ENH: Adding __array_ufunc__ capability to MaskedArrays +* `#16154 <https://github.com/numpy/numpy/pull/16154>`__: ENH: Add support for symbol to polynomial package +* `#16507 <https://github.com/numpy/numpy/pull/16507>`__: BUG: Do not allow nditer to reduce the mask +* `#16971 <https://github.com/numpy/numpy/pull/16971>`__: BUG: Fix three ``complex``- & ``float128``-related issues with ``nd_grid`` +* `#19388 <https://github.com/numpy/numpy/pull/19388>`__: ENH: Support character and character string arrays +* `#20321 <https://github.com/numpy/numpy/pull/20321>`__: ENH: allow NumPy created .npy files to be appended in-place +* `#20659 <https://github.com/numpy/numpy/pull/20659>`__: BUG: cross product. Added dtype conversions of inputs. See. #19138 +* `#20913 <https://github.com/numpy/numpy/pull/20913>`__: ENH, SIMD: Extend universal intrinsics to support IBMZ +* `#20914 <https://github.com/numpy/numpy/pull/20914>`__: BUG: change ``ma.mean`` dtype to be consistent with ``np.mean`` +* `#20924 <https://github.com/numpy/numpy/pull/20924>`__: MAINT: Simplify element setting and use it for filling +* `#20949 <https://github.com/numpy/numpy/pull/20949>`__: MAINT: Rename INSTALL.rst.txt to INSTALL.rst +* `#21041 <https://github.com/numpy/numpy/pull/21041>`__: ENH: Implement string comparison ufuncs (or almost) +* `#21084 <https://github.com/numpy/numpy/pull/21084>`__: MAINT: Fix computation of numpy.array_api.linalg.vector_norm +* `#21098 <https://github.com/numpy/numpy/pull/21098>`__: DOC: Fix axis naming in ``argpartition`` docs +* `#21103 <https://github.com/numpy/numpy/pull/21103>`__: NEP: Add NEP 50 draft about fixing scalar promotion rules +* `#21152 <https://github.com/numpy/numpy/pull/21152>`__: DOC: verifying bug existence and fixes - replacement for PR 17851 +* `#21248 <https://github.com/numpy/numpy/pull/21248>`__: DOC: improve description of the ``data`` entry in ``__array_interface__`` +* `#21308 <https://github.com/numpy/numpy/pull/21308>`__: MAINT: Start testing with Python 3.11. +* `#21403 <https://github.com/numpy/numpy/pull/21403>`__: MAINT: remove some names from main numpy namespace +* `#21437 <https://github.com/numpy/numpy/pull/21437>`__: ENH: Add floating point error checking to (almost) all casts +* `#21468 <https://github.com/numpy/numpy/pull/21468>`__: ENH: Use ``threadpoolctl`` in ``show_runtime`` (a new function) +* `#21471 <https://github.com/numpy/numpy/pull/21471>`__: DOC: adding docstring to TooHardError class +* `#21483 <https://github.com/numpy/numpy/pull/21483>`__: SIMD: Use universal intrinsics to implement comparison functions +* `#21501 <https://github.com/numpy/numpy/pull/21501>`__: DOC: improve ``ascontiguousarray()`` and ``asfortranarray()`` examples +* `#21504 <https://github.com/numpy/numpy/pull/21504>`__: MAINT: Fix some typos. +* `#21507 <https://github.com/numpy/numpy/pull/21507>`__: BUG: Better report integer division overflow +* `#21527 <https://github.com/numpy/numpy/pull/21527>`__: PERF: Fast path for dtype lookup of float and long +* `#21537 <https://github.com/numpy/numpy/pull/21537>`__: DOC: Add a policy about inactive PRs. +* `#21564 <https://github.com/numpy/numpy/pull/21564>`__: TST: Enable doctests in IO Howto with testsetup and testcleanup +* `#21567 <https://github.com/numpy/numpy/pull/21567>`__: BUG: Adding the default pytest doctest instead of the ValueError +* `#21572 <https://github.com/numpy/numpy/pull/21572>`__: MAINT: allow absolute module names in refguide-check +* `#21579 <https://github.com/numpy/numpy/pull/21579>`__: DOC: Improve docstring of numpy.testing.assert_allclose +* `#21581 <https://github.com/numpy/numpy/pull/21581>`__: REL: Prepare main for NumPy 1.24.0 development +* `#21582 <https://github.com/numpy/numpy/pull/21582>`__: MAINT: Fix some small refcounting and similar issues +* `#21583 <https://github.com/numpy/numpy/pull/21583>`__: Add ``CODEOWNER`` for the ``array_api`` module +* `#21587 <https://github.com/numpy/numpy/pull/21587>`__: DOC: update logarithm docs as per theory. +* `#21591 <https://github.com/numpy/numpy/pull/21591>`__: BUG, STY: Fix doctest failure in EXAMPLE_DOCSTRING. +* `#21595 <https://github.com/numpy/numpy/pull/21595>`__: ENH: Add strict parameter to assert_array_equal. Fixes #9542 +* `#21596 <https://github.com/numpy/numpy/pull/21596>`__: TYP,MAINT: Allow unsigned integer inplace-ops to accept signed... +* `#21600 <https://github.com/numpy/numpy/pull/21600>`__: DOC: Add missing links for NEP36 and NEP49 +* `#21601 <https://github.com/numpy/numpy/pull/21601>`__: DOC: update NEP29 to address PEP0602 +* `#21602 <https://github.com/numpy/numpy/pull/21602>`__: BUILD: fix tag name for travis: it is v1.23.0rc1 +* `#21605 <https://github.com/numpy/numpy/pull/21605>`__: MAINT: Adapt npt._GenericAlias to Python 3.11 types.GenericAlias... +* `#21609 <https://github.com/numpy/numpy/pull/21609>`__: MAINT: Fix some API versions. +* `#21611 <https://github.com/numpy/numpy/pull/21611>`__: MAINT: make MismatchCAPIWarnining into MismatchCAPIError +* `#21615 <https://github.com/numpy/numpy/pull/21615>`__: MAINT: Remove compatibility shims for old versions of PyPy +* `#21616 <https://github.com/numpy/numpy/pull/21616>`__: DOC: Describe the changed Python release cadence better +* `#21617 <https://github.com/numpy/numpy/pull/21617>`__: MAINT, STY: Make download-wheels download source files. +* `#21620 <https://github.com/numpy/numpy/pull/21620>`__: MAINT: Fortify masked in-place ops against promotion warnings +* `#21622 <https://github.com/numpy/numpy/pull/21622>`__: TST: Skip F2PY tests without Fortran compilers +* `#21623 <https://github.com/numpy/numpy/pull/21623>`__: ENH: Add equals_nans kwarg to np.unique +* `#21624 <https://github.com/numpy/numpy/pull/21624>`__: DOC: move ``import_array`` and ``import_umath`` above ``PyModule_Create`` +* `#21626 <https://github.com/numpy/numpy/pull/21626>`__: API: Introduce optional (and partial) NEP 50 weak scalar logic +* `#21627 <https://github.com/numpy/numpy/pull/21627>`__: ENH: adding casting option to numpy.stack. +* `#21630 <https://github.com/numpy/numpy/pull/21630>`__: MAINT: back out conversion of npymath component to c++ +* `#21632 <https://github.com/numpy/numpy/pull/21632>`__: API: Retain ``arr.base`` more strictly in ``np.frombuffer`` +* `#21639 <https://github.com/numpy/numpy/pull/21639>`__: BUG: use explicit einsum_path whenever it is given +* `#21641 <https://github.com/numpy/numpy/pull/21641>`__: DOC: Note version-switcher update in the release walkthrough +* `#21644 <https://github.com/numpy/numpy/pull/21644>`__: MAINT: Fixup ``unique``'s ``equal_nan`` kwarg to match ``np.array_equal`` +* `#21645 <https://github.com/numpy/numpy/pull/21645>`__: DEP: Remove ``normed=`` keyword argument from histograms +* `#21648 <https://github.com/numpy/numpy/pull/21648>`__: ENH: issue overflow warning when using ``abs`` on ``np.int8(-128)`` +* `#21651 <https://github.com/numpy/numpy/pull/21651>`__: MAINT: Remove unused/not useful CODEOWNERS file again +* `#21654 <https://github.com/numpy/numpy/pull/21654>`__: MAINT: limit the number of decimals in Polynomial representation +* `#21658 <https://github.com/numpy/numpy/pull/21658>`__: MAINT: improved overflow check to avoid undefined behavior +* `#21659 <https://github.com/numpy/numpy/pull/21659>`__: BUG: Fix a bug left after f2py2e refactor +* `#21661 <https://github.com/numpy/numpy/pull/21661>`__: TYP, ENH: Add annotations for the ``equal_nan`` keyword to ``np.unique`` +* `#21662 <https://github.com/numpy/numpy/pull/21662>`__: DOC: ``np`` in double backticks. +* `#21663 <https://github.com/numpy/numpy/pull/21663>`__: DEP: Deprecate (rather than remove) the int-via-float parsing... +* `#21664 <https://github.com/numpy/numpy/pull/21664>`__: DOC: Misc RST reformatting. +* `#21666 <https://github.com/numpy/numpy/pull/21666>`__: MAINT: Change array API unique_*() functions to not compare nans... +* `#21675 <https://github.com/numpy/numpy/pull/21675>`__: DOC: Add note about broadcasting support for ``random.Generator.multinomial`` +* `#21677 <https://github.com/numpy/numpy/pull/21677>`__: DOC: RST Titles Underline reordering +* `#21681 <https://github.com/numpy/numpy/pull/21681>`__: MAINT: Point documentation version switcher at the docs homepage +* `#21687 <https://github.com/numpy/numpy/pull/21687>`__: BUG: switch _CMP_NEQ_OQ to _CMP_NEQ_UQ for npyv_cmpneq_f[32,64] +* `#21689 <https://github.com/numpy/numpy/pull/21689>`__: DOC: Fix broadcasting documentation. +* `#21690 <https://github.com/numpy/numpy/pull/21690>`__: BUG: Prevent attempted broadcasting of 0-D output operands in... +* `#21691 <https://github.com/numpy/numpy/pull/21691>`__: BUG: Small fixupes found using valgrind +* `#21692 <https://github.com/numpy/numpy/pull/21692>`__: MAINT: Renamed doc/records.rst.txt to doc/records.rst +* `#21701 <https://github.com/numpy/numpy/pull/21701>`__: BUG: Enable fortran preprocessing for ifort on Windows +* `#21704 <https://github.com/numpy/numpy/pull/21704>`__: DOC: Mention positional-only arguments in the array API compatibility... +* `#21705 <https://github.com/numpy/numpy/pull/21705>`__: BLD, SIMD: Fix detect armhf and hardened the Neon/ASIMD compile-time... +* `#21707 <https://github.com/numpy/numpy/pull/21707>`__: MAINT: generate_umath.py: do not write full path into output... +* `#21709 <https://github.com/numpy/numpy/pull/21709>`__: TST: Fixup loadtxt int-via-float tests when in release mode +* `#21712 <https://github.com/numpy/numpy/pull/21712>`__: BUG: ``.f2py_f2cmap`` doesn't map ``long_long`` and other options +* `#21715 <https://github.com/numpy/numpy/pull/21715>`__: DOC: Tell people to use only-binary option +* `#21723 <https://github.com/numpy/numpy/pull/21723>`__: DOC: Update sphinx, numpydoc, and pydata-sphinx-theme +* `#21727 <https://github.com/numpy/numpy/pull/21727>`__: MAINT, SIMD: Handle overflow gracefully in integer division +* `#21731 <https://github.com/numpy/numpy/pull/21731>`__: ENH: Ensure dispatcher TypeErrors report original name +* `#21732 <https://github.com/numpy/numpy/pull/21732>`__: ENH: Add support for platforms with missing fenv flags +* `#21733 <https://github.com/numpy/numpy/pull/21733>`__: ENH: Fix pointer size determination for cross build +* `#21734 <https://github.com/numpy/numpy/pull/21734>`__: ENH: Check that we are targeting x86 or x64 architecture before... +* `#21735 <https://github.com/numpy/numpy/pull/21735>`__: ENH: cross compilation: use sysconfig to determine if x86_64... +* `#21745 <https://github.com/numpy/numpy/pull/21745>`__: MAINT: Remove FPE helper code that is unnecessary on C99/C++11 +* `#21748 <https://github.com/numpy/numpy/pull/21748>`__: BUG: Fix for npyv_orc_b8 and npyv_xnor_b8 for s390x (z13) +* `#21749 <https://github.com/numpy/numpy/pull/21749>`__: BUG, SIMD: Fix detecting NEON/ASIMD on aarch64 +* `#21750 <https://github.com/numpy/numpy/pull/21750>`__: CI: Fix CI SIMD build on s390x +* `#21755 <https://github.com/numpy/numpy/pull/21755>`__: BUG: Do not skip value-based promotion path for large Python... +* `#21759 <https://github.com/numpy/numpy/pull/21759>`__: BUG: Fix small reference leaks found with pytest-leaks +* `#21763 <https://github.com/numpy/numpy/pull/21763>`__: MAINT: use f-string format in test_abc.py +* `#21764 <https://github.com/numpy/numpy/pull/21764>`__: BUG: Fix a potential variable misuse bug +* `#21766 <https://github.com/numpy/numpy/pull/21766>`__: CI: Guard compile-time CPU features tests +* `#21771 <https://github.com/numpy/numpy/pull/21771>`__: MAINT: Add a check of the return value of PyMem_Calloc(). +* `#21773 <https://github.com/numpy/numpy/pull/21773>`__: MAINT: fix typo in string_ufuncs.cpp +* `#21776 <https://github.com/numpy/numpy/pull/21776>`__: CI: add workflow for non-optimized builds +* `#21778 <https://github.com/numpy/numpy/pull/21778>`__: MAINT, SIMD: remove orphan path vsx/conversion.h +* `#21779 <https://github.com/numpy/numpy/pull/21779>`__: MAINT: random: Disallow complex inputs in multivariate_normal +* `#21786 <https://github.com/numpy/numpy/pull/21786>`__: MAINT: fix up use of ``NPY_NO_DEPRECATED_API`` usage in f2py +* `#21789 <https://github.com/numpy/numpy/pull/21789>`__: ENH: Change f2c declarations with void return type to int +* `#21790 <https://github.com/numpy/numpy/pull/21790>`__: ENH: add overflow handling for scalar ``negative`` operation +* `#21793 <https://github.com/numpy/numpy/pull/21793>`__: ENH: Add overflow handling for negative integers scalar multiplication +* `#21794 <https://github.com/numpy/numpy/pull/21794>`__: BUG: lib: A loadtxt error message had two values reversed. +* `#21795 <https://github.com/numpy/numpy/pull/21795>`__: ENH: Ensure that assertion of unsigned dtypes does not return... +* `#21796 <https://github.com/numpy/numpy/pull/21796>`__: BUG: Fix comparison for empty structured arrays +* `#21797 <https://github.com/numpy/numpy/pull/21797>`__: MAINT: Reduce object construction in np.require +* `#21798 <https://github.com/numpy/numpy/pull/21798>`__: MAINT: use PyErr_SetString in _import_array where possible +* `#21807 <https://github.com/numpy/numpy/pull/21807>`__: ENH: Handle the value attribute in F2Py wrappers +* `#21812 <https://github.com/numpy/numpy/pull/21812>`__: BUG: Define ``<``, ``<=``, ``>``, ``>=`` for masked arrays +* `#21815 <https://github.com/numpy/numpy/pull/21815>`__: BUG: Fix discovered MachAr (still used within valgrind) +* `#21817 <https://github.com/numpy/numpy/pull/21817>`__: ENH: Always fill object fields with None rather than NULL +* `#21823 <https://github.com/numpy/numpy/pull/21823>`__: MAINT: Try fixing broken Anaconda uploads. +* `#21828 <https://github.com/numpy/numpy/pull/21828>`__: MAINT: Update main after 1.23.0 release. +* `#21830 <https://github.com/numpy/numpy/pull/21830>`__: DOC: Change substract to subtract in comment +* `#21832 <https://github.com/numpy/numpy/pull/21832>`__: PERF: Micro optimize np.linspace +* `#21835 <https://github.com/numpy/numpy/pull/21835>`__: TST: Add f2py CLI tests +* `#21836 <https://github.com/numpy/numpy/pull/21836>`__: DOC: F2PY documentation improvements +* `#21837 <https://github.com/numpy/numpy/pull/21837>`__: DOC: Document expectation for object array initialization +* `#21842 <https://github.com/numpy/numpy/pull/21842>`__: BUG: Fix in1d for empty integer array as input +* `#21844 <https://github.com/numpy/numpy/pull/21844>`__: DOC: Rephrase dimensionality, size in broadcasting.rst +* `#21848 <https://github.com/numpy/numpy/pull/21848>`__: BUG: Handle NaNs correctly for float16 during sorting +* `#21849 <https://github.com/numpy/numpy/pull/21849>`__: MAINT: Update the documentation Makefile +* `#21851 <https://github.com/numpy/numpy/pull/21851>`__: BUG: Use ``keepdims`` during normalization in ``np.average`` and... +* `#21853 <https://github.com/numpy/numpy/pull/21853>`__: DOC: Update the docstring for np.around +* `#21854 <https://github.com/numpy/numpy/pull/21854>`__: DOC: mention changes to ``max_rows`` behaviour in ``np.loadtxt`` +* `#21855 <https://github.com/numpy/numpy/pull/21855>`__: DOC: Replace the mathematical notation N(...) with text. +* `#21856 <https://github.com/numpy/numpy/pull/21856>`__: DOC: Mention uniform in the np.random.Generator.random function. +* `#21857 <https://github.com/numpy/numpy/pull/21857>`__: BUG: Reject non integer array-likes with size 1 in delete +* `#21860 <https://github.com/numpy/numpy/pull/21860>`__: BUG: Fix numpy.isin for timedelta dtype +* `#21861 <https://github.com/numpy/numpy/pull/21861>`__: DOC: clarify loadtxt input cols requirement +* `#21863 <https://github.com/numpy/numpy/pull/21863>`__: ENH,MAINT: Improve and simplify scalar floating point warnings +* `#21872 <https://github.com/numpy/numpy/pull/21872>`__: CI: tools: Remove a long but obsolete comment from travis-test.sh +* `#21875 <https://github.com/numpy/numpy/pull/21875>`__: ENH: Implement correct scalar and integer overflow errors for... +* `#21876 <https://github.com/numpy/numpy/pull/21876>`__: DOC: Fixed minor typo in reference +* `#21877 <https://github.com/numpy/numpy/pull/21877>`__: DOC: dark theme css rules +* `#21879 <https://github.com/numpy/numpy/pull/21879>`__: CI: skip azp and circleCI logic +* `#21881 <https://github.com/numpy/numpy/pull/21881>`__: MAINT: Disable checks for Win workaround for GCC +* `#21884 <https://github.com/numpy/numpy/pull/21884>`__: MAINT: Fix non-void function does not return a value warning +* `#21885 <https://github.com/numpy/numpy/pull/21885>`__: DOC: Link to PEP-484 in the typing docs +* `#21886 <https://github.com/numpy/numpy/pull/21886>`__: Fix lib flags for librandom +* `#21887 <https://github.com/numpy/numpy/pull/21887>`__: BLD: Allow GCC compile on mingw-w64-based systems +* `#21890 <https://github.com/numpy/numpy/pull/21890>`__: BUG: Fix KeyError in crackfortran operator support +* `#21894 <https://github.com/numpy/numpy/pull/21894>`__: BUG: Fix datetime_to_timedelta_resolve_descriptors signature +* `#21895 <https://github.com/numpy/numpy/pull/21895>`__: ENH, CI: Add Emscripten to CI +* `#21896 <https://github.com/numpy/numpy/pull/21896>`__: BLD: Make can_link_svml return False for 32bit builds on x86_64 +* `#21904 <https://github.com/numpy/numpy/pull/21904>`__: DOC: Add usage example to np.char.center docstring +* `#21905 <https://github.com/numpy/numpy/pull/21905>`__: DOC: Fix the interpolation formulae for quantile and percentile +* `#21909 <https://github.com/numpy/numpy/pull/21909>`__: DOC: fix typo in ``numpy._typing._NestedSequence`` docstring example +* `#21921 <https://github.com/numpy/numpy/pull/21921>`__: DOC: Fix typo on Byte-swapping page +* `#21922 <https://github.com/numpy/numpy/pull/21922>`__: DOC: fix typo on custom array containers page +* `#21924 <https://github.com/numpy/numpy/pull/21924>`__: CI: Use OpenBLAS again on Cygwin +* `#21925 <https://github.com/numpy/numpy/pull/21925>`__: BUG: Fix subarray to object cast ownership details +* `#21926 <https://github.com/numpy/numpy/pull/21926>`__: MAINT: random: Annotate default_rng with cython.embedsignature +* `#21927 <https://github.com/numpy/numpy/pull/21927>`__: DOC: Add a note about security and NumPy to the documentation +* `#21928 <https://github.com/numpy/numpy/pull/21928>`__: BUG: Fix the implementation of numpy.array_api.vecdot +* `#21943 <https://github.com/numpy/numpy/pull/21943>`__: DOC, MAINT: Document the C-API incompatibility error and point... +* `#21945 <https://github.com/numpy/numpy/pull/21945>`__: MAINT, DOC: Update release guide +* `#21946 <https://github.com/numpy/numpy/pull/21946>`__: BUG: Reorder extern "C" to only apply to function declarations... +* `#21948 <https://github.com/numpy/numpy/pull/21948>`__: [DOC] Double backticks in lagfit. +* `#21954 <https://github.com/numpy/numpy/pull/21954>`__: TST: Add tests for FP16 umath functions +* `#21955 <https://github.com/numpy/numpy/pull/21955>`__: ENH: Vectorize FP16 umath functions using AVX512 +* `#21956 <https://github.com/numpy/numpy/pull/21956>`__: MAINT: Update main after 1.23.1 release. +* `#21957 <https://github.com/numpy/numpy/pull/21957>`__: TYP,ENH: Mark all unhashable classes as such +* `#21959 <https://github.com/numpy/numpy/pull/21959>`__: BUG: Use ``Popen`` to silently invoke f77 -v +* `#21960 <https://github.com/numpy/numpy/pull/21960>`__: Revert "ENH: Adding __array_ufunc__ capability to MaskedArrays" +* `#21963 <https://github.com/numpy/numpy/pull/21963>`__: BLD: remove outdated pin for ``packaging`` on macOS arm64 +* `#21965 <https://github.com/numpy/numpy/pull/21965>`__: Added priority in bug-report issue-template +* `#21968 <https://github.com/numpy/numpy/pull/21968>`__: ENH: Add ``__array_ufunc__`` typing support to the ``nin=1`` ufuncs +* `#21973 <https://github.com/numpy/numpy/pull/21973>`__: DOC: correct docstring for numpy.correlate() +* `#21974 <https://github.com/numpy/numpy/pull/21974>`__: MAINT, TYP: Fix ``np.angle`` dtype-overloads +* `#21976 <https://github.com/numpy/numpy/pull/21976>`__: ENH: Add the capability to swap the singleton bit generator +* `#21977 <https://github.com/numpy/numpy/pull/21977>`__: ENH: Adding __array_ufunc__ capability to MaskedArrays +* `#21979 <https://github.com/numpy/numpy/pull/21979>`__: BUG: Fix experimental dtype slot numbers +* `#21981 <https://github.com/numpy/numpy/pull/21981>`__: TST: ensure ``np.equal.reduce`` raises a ``TypeError`` +* `#21982 <https://github.com/numpy/numpy/pull/21982>`__: MAINT: Do not let ``_GenericAlias`` wrap the underlying classes'... +* `#21983 <https://github.com/numpy/numpy/pull/21983>`__: TYP,MAINT: Allow ``einsum`` subscripts to be passed via integer... +* `#21984 <https://github.com/numpy/numpy/pull/21984>`__: MAINT,TYP: Add object-overloads for the ``np.generic`` rich comparisons +* `#21986 <https://github.com/numpy/numpy/pull/21986>`__: MAINT: Remove two unused imports +* `#21991 <https://github.com/numpy/numpy/pull/21991>`__: MAINT: rm old warning +* `#21992 <https://github.com/numpy/numpy/pull/21992>`__: DOC: cross-reference descriptions of frombuffer and ndarray.tobytes +* `#21993 <https://github.com/numpy/numpy/pull/21993>`__: BUG: fix ma.minimum.reduce with axis keyword +* `#21995 <https://github.com/numpy/numpy/pull/21995>`__: BUG: Distinguish exact vs. equivalent dtype for C type aliases. +* `#21996 <https://github.com/numpy/numpy/pull/21996>`__: BUG: Avoid errors on NULL during deepcopy +* `#21997 <https://github.com/numpy/numpy/pull/21997>`__: DOC: unify ``np.transpose``, ``np.ndarray.transpose``, and ``np.ndarray.T`` +* `#21999 <https://github.com/numpy/numpy/pull/21999>`__: BUG: Fix masked median bug +* `#22000 <https://github.com/numpy/numpy/pull/22000>`__: DOC: some improvements in the NumPy/MATLAB comparison +* `#22002 <https://github.com/numpy/numpy/pull/22002>`__: DOC: add links to ``linalg`` in docs of ``dot`` and ``matmul`` +* `#22004 <https://github.com/numpy/numpy/pull/22004>`__: DEP: Finalize ragged array creation deprecation +* `#22008 <https://github.com/numpy/numpy/pull/22008>`__: MAINT: remove unneeded ``__future__`` imports +* `#22009 <https://github.com/numpy/numpy/pull/22009>`__: BUG: fix np.average for Fraction elements +* `#22010 <https://github.com/numpy/numpy/pull/22010>`__: DOC: Add versionchanged for converter callable behavior. +* `#22013 <https://github.com/numpy/numpy/pull/22013>`__: DOC: updated masked_print_option and added explanation +* `#22014 <https://github.com/numpy/numpy/pull/22014>`__: BUG/ENH: Allow bit generators to supply their own constructor +* `#22016 <https://github.com/numpy/numpy/pull/22016>`__: BUG: Revert using __array_ufunc__ for MaskedArray +* `#22017 <https://github.com/numpy/numpy/pull/22017>`__: ENH: reorder includes for testing on top of system installations... +* `#22022 <https://github.com/numpy/numpy/pull/22022>`__: MAINT,TYP: Allow the ``squeeze`` and ``transpose`` method to... +* `#22024 <https://github.com/numpy/numpy/pull/22024>`__: BUG: Expose string_heapsort algorithm in a shared header +* `#22043 <https://github.com/numpy/numpy/pull/22043>`__: BLD: use macos-11 image on azure, macos-1015 is deprecated +* `#22045 <https://github.com/numpy/numpy/pull/22045>`__: ENH: allow importlib.LazyLoader to work with numpy and add test... +* `#22046 <https://github.com/numpy/numpy/pull/22046>`__: BUG: Make ``mask_invalid`` consistent with ``mask_where`` if ``copy``... +* `#22053 <https://github.com/numpy/numpy/pull/22053>`__: MAINT: Quiet the anaconda uploads. +* `#22060 <https://github.com/numpy/numpy/pull/22060>`__: PERF: Improve import time of numpy +* `#22071 <https://github.com/numpy/numpy/pull/22071>`__: MAINT: fix typo in test_array_object.py +* `#22081 <https://github.com/numpy/numpy/pull/22081>`__: PERF: Remove numpy.compat._pep440 from default imports +* `#22083 <https://github.com/numpy/numpy/pull/22083>`__: BUG: Fix skip condition for test_loss_of_precision[complex256] +* `#22087 <https://github.com/numpy/numpy/pull/22087>`__: ENH: raise TypeError when arange() is called with string dtype +* `#22090 <https://github.com/numpy/numpy/pull/22090>`__: MAINT: Simplify npymath +* `#22096 <https://github.com/numpy/numpy/pull/22096>`__: PERF: Improve intrinsics for tobits and pack on Apple silicon +* `#22099 <https://github.com/numpy/numpy/pull/22099>`__: TST: Remove workaround for gh-9968 from ``test_scalar_methods.test_roundtrip`` +* `#22102 <https://github.com/numpy/numpy/pull/22102>`__: BLD: Try building python3.11 wheels. +* `#22105 <https://github.com/numpy/numpy/pull/22105>`__: TST: fix test_linear_interpolation_formula_symmetric +* `#22110 <https://github.com/numpy/numpy/pull/22110>`__: BUG: Address failures in aarch64 gcc builds due to #22096 +* `#22111 <https://github.com/numpy/numpy/pull/22111>`__: BUG: Missed a case in the diff merge for #22110 +* `#22112 <https://github.com/numpy/numpy/pull/22112>`__: MAINT: remove redundant reversal of eigenvalues order in svd... +* `#22116 <https://github.com/numpy/numpy/pull/22116>`__: MAINT,DOC: Remove sphinx-panels in favor of sphinx-design +* `#22117 <https://github.com/numpy/numpy/pull/22117>`__: DOC: Reorganize user guide outline +* `#22118 <https://github.com/numpy/numpy/pull/22118>`__: DOC: Fix documentation for percentile and quantile +* `#22120 <https://github.com/numpy/numpy/pull/22120>`__: DOC: Explain spawn_key a little more. +* `#22122 <https://github.com/numpy/numpy/pull/22122>`__: DOC: Explain how to use sequences of integers as seeds. +* `#22124 <https://github.com/numpy/numpy/pull/22124>`__: MAINT: support IBM i system +* `#22127 <https://github.com/numpy/numpy/pull/22127>`__: BLD: Add Python 3.11 wheels to aarch64 build +* `#22130 <https://github.com/numpy/numpy/pull/22130>`__: MAINT: Update main after 1.23.2 release. +* `#22132 <https://github.com/numpy/numpy/pull/22132>`__: DOC: Add a release note for bit generator reduce changes +* `#22139 <https://github.com/numpy/numpy/pull/22139>`__: DEP: drop support for msvc<=1900 and Interix +* `#22142 <https://github.com/numpy/numpy/pull/22142>`__: MAINT: Update setup.py for Python 3.11. +* `#22143 <https://github.com/numpy/numpy/pull/22143>`__: MAINT: Update the RELEASE_WALKTHROUGH file. +* `#22144 <https://github.com/numpy/numpy/pull/22144>`__: DOC: Add missing word +* `#22147 <https://github.com/numpy/numpy/pull/22147>`__: DOC: fix linalg.tensorsolve docstring +* `#22149 <https://github.com/numpy/numpy/pull/22149>`__: DOC: Copy-edit the 'partition' docstring. +* `#22150 <https://github.com/numpy/numpy/pull/22150>`__: CI: Test NumPy build against old versions of GCC(6, 7, 8) +* `#22152 <https://github.com/numpy/numpy/pull/22152>`__: BUG: Support using libunwind for backtrack +* `#22154 <https://github.com/numpy/numpy/pull/22154>`__: DOC: add more prominent warnings to pin setuptools +* `#22159 <https://github.com/numpy/numpy/pull/22159>`__: DEP: drop older cygwin compatibility shims +* `#22161 <https://github.com/numpy/numpy/pull/22161>`__: MAINT: simplify complex math function handling in npymath +* `#22163 <https://github.com/numpy/numpy/pull/22163>`__: PERF: Eliminate slow check for pypy during numpy import +* `#22164 <https://github.com/numpy/numpy/pull/22164>`__: ENH: Improve tanh for architectures without efficient gather/scatter... +* `#22168 <https://github.com/numpy/numpy/pull/22168>`__: ENH: Remove AVX related functions from non x86 based builds +* `#22169 <https://github.com/numpy/numpy/pull/22169>`__: MAINT: fix defines for universal2 python builds of NumPy +* `#22171 <https://github.com/numpy/numpy/pull/22171>`__: DOC: Note symmetry requirement in ``multivariate_normal`` error +* `#22179 <https://github.com/numpy/numpy/pull/22179>`__: TST: Implemented an unused test for np.random.randint +* `#22189 <https://github.com/numpy/numpy/pull/22189>`__: MAINT: fix an incorrect pointer type usage in f2py +* `#22193 <https://github.com/numpy/numpy/pull/22193>`__: BUG: change overloads to play nice with pyright. +* `#22194 <https://github.com/numpy/numpy/pull/22194>`__: BUG: Fix circleci build +* `#22199 <https://github.com/numpy/numpy/pull/22199>`__: MAINT: Unpin towncrier +* `#22204 <https://github.com/numpy/numpy/pull/22204>`__: TST,BUG: Use fork context to fix MacOS savez test +* `#22205 <https://github.com/numpy/numpy/pull/22205>`__: DOC: Clarify that ``like`` is not passed to ``function`` +* `#22206 <https://github.com/numpy/numpy/pull/22206>`__: DOC: Fix typo disutils -> distutils in numpy.distutils migration... +* `#22210 <https://github.com/numpy/numpy/pull/22210>`__: DOC: Fix typos in cast warning release note +* `#22212 <https://github.com/numpy/numpy/pull/22212>`__: TYP,BUG: Reduce argument validation in C-based ``__class_getitem__`` +* `#22227 <https://github.com/numpy/numpy/pull/22227>`__: DOC: fix up release note +* `#22228 <https://github.com/numpy/numpy/pull/22228>`__: MAINT: Remove long deprecated functionality from np.ma +* `#22235 <https://github.com/numpy/numpy/pull/22235>`__: Remove incorrect comment about checking generated C files in +* `#22236 <https://github.com/numpy/numpy/pull/22236>`__: BUG: Fix incorrect refcounting in new ``asarray`` path +* `#22239 <https://github.com/numpy/numpy/pull/22239>`__: MAINT: Update main after 1.23.3 release. +* `#22240 <https://github.com/numpy/numpy/pull/22240>`__: ENH: Use SVML for fp32 and fp64 power and arctan2 +* `#22242 <https://github.com/numpy/numpy/pull/22242>`__: BLD: add back stdlib.h include in pcg64.h +* `#22245 <https://github.com/numpy/numpy/pull/22245>`__: MAINT: random: remove ``get_info`` from "extending with Cython"... +* `#22251 <https://github.com/numpy/numpy/pull/22251>`__: TST: Move new ``asarray`` test to a more appropriate place. +* `#22253 <https://github.com/numpy/numpy/pull/22253>`__: DOC: Update concatenate exception message. +* `#22254 <https://github.com/numpy/numpy/pull/22254>`__: DOC: Improve ``converters`` parameter description for loadtxt +* `#22256 <https://github.com/numpy/numpy/pull/22256>`__: DOC: Add C API example for NPY_ITER_MULTI_INDEX +* `#22259 <https://github.com/numpy/numpy/pull/22259>`__: DOC: Better report integer division overflow (#21506) +* `#22261 <https://github.com/numpy/numpy/pull/22261>`__: NEP: Make NEP 51 to propose changing the scalar representation +* `#22263 <https://github.com/numpy/numpy/pull/22263>`__: DOC: Clarified how finfo works with complex numbers (#22260) +* `#22272 <https://github.com/numpy/numpy/pull/22272>`__: MAINT, Haiku defines neither __STDC_NO_THREADS__ nor __GLIBC__ +* `#22276 <https://github.com/numpy/numpy/pull/22276>`__: DOC: Update for return value of np.ptp() +* `#22279 <https://github.com/numpy/numpy/pull/22279>`__: DOC: Add example to msort docstring +* `#22280 <https://github.com/numpy/numpy/pull/22280>`__: DOC: updated the description for array-like type in histogramdd... +* `#22282 <https://github.com/numpy/numpy/pull/22282>`__: DOC: Add example for find +* `#22285 <https://github.com/numpy/numpy/pull/22285>`__: DOC: Add ``isupper`` examples +* `#22291 <https://github.com/numpy/numpy/pull/22291>`__: DOC: Add examples for isdigit and str_len +* `#22292 <https://github.com/numpy/numpy/pull/22292>`__: DOC: Add copyto example +* `#22294 <https://github.com/numpy/numpy/pull/22294>`__: DOC: add examples to np.char.multiply +* `#22295 <https://github.com/numpy/numpy/pull/22295>`__: DOC: Added an example for isupper() function +* `#22296 <https://github.com/numpy/numpy/pull/22296>`__: BUG: Memory leaks in numpy.nested_iters +* `#22297 <https://github.com/numpy/numpy/pull/22297>`__: DOC: Add example to np.prod +* `#22298 <https://github.com/numpy/numpy/pull/22298>`__: DOC: add example for ma.unique function +* `#22299 <https://github.com/numpy/numpy/pull/22299>`__: DOC: Add examples for join and index +* `#22300 <https://github.com/numpy/numpy/pull/22300>`__: DOC: examples for ``np.char.isdecimal`` and ``np.char.isnumeric`` +* `#22302 <https://github.com/numpy/numpy/pull/22302>`__: DOC: Change in the documentation for chebpts2 method +* `#22304 <https://github.com/numpy/numpy/pull/22304>`__: DOC: default_rng cleanup +* `#22306 <https://github.com/numpy/numpy/pull/22306>`__: ENH: Implement essential intrinsics required by the upcoming... +* `#22308 <https://github.com/numpy/numpy/pull/22308>`__: DOC: add examples to numpy.char.replace +* `#22309 <https://github.com/numpy/numpy/pull/22309>`__: DOC: Correct usage example for np.char.decode docstring +* `#22312 <https://github.com/numpy/numpy/pull/22312>`__: MAINT: Shorten test output on travis builds +* `#22313 <https://github.com/numpy/numpy/pull/22313>`__: DEP: Deprecate fastCopyAndTranspose +* `#22314 <https://github.com/numpy/numpy/pull/22314>`__: MAINT: Shorten wheel test output on travis builds +* `#22316 <https://github.com/numpy/numpy/pull/22316>`__: ENH: Allow creating structured void scalars by passing dtype +* `#22319 <https://github.com/numpy/numpy/pull/22319>`__: TST: add functional tests for kron +* `#22321 <https://github.com/numpy/numpy/pull/22321>`__: MAINT: core: Fix a typo in a datetime error message. +* `#22324 <https://github.com/numpy/numpy/pull/22324>`__: MAINT: update function's __module__ attribute in deprecate +* `#22325 <https://github.com/numpy/numpy/pull/22325>`__: SIMD: Improve the performance of NEON vector initializer +* `#22326 <https://github.com/numpy/numpy/pull/22326>`__: CI, SIMD: Test and build without the support of AVX2 and AVX512 +* `#22327 <https://github.com/numpy/numpy/pull/22327>`__: BUG: Fix complex vector dot with more than NPY_CBLAS_CHUNK elements +* `#22331 <https://github.com/numpy/numpy/pull/22331>`__: DOC: Adding examples to ``ma.max`` function +* `#22332 <https://github.com/numpy/numpy/pull/22332>`__: DOC: Minor typo in docs +* `#22334 <https://github.com/numpy/numpy/pull/22334>`__: DOC: Added missing dtype attribute to ``iinfo`` and ``finfo`` docstring +* `#22336 <https://github.com/numpy/numpy/pull/22336>`__: MAINT: Rm numpydoc remnant example docstring. +* `#22342 <https://github.com/numpy/numpy/pull/22342>`__: MAINT: update sde toolkit to 9.0, fix download link +* `#22343 <https://github.com/numpy/numpy/pull/22343>`__: DOC: fixed two more typos in docstrings +* `#22344 <https://github.com/numpy/numpy/pull/22344>`__: DOC: fixed minor typo in percentile docstring +* `#22354 <https://github.com/numpy/numpy/pull/22354>`__: MAINT: switch sponsor link from numfocus to opencollective +* `#22356 <https://github.com/numpy/numpy/pull/22356>`__: REV: Loosen ``lookfor``'s import try/except again +* `#22357 <https://github.com/numpy/numpy/pull/22357>`__: TYP,ENH: Mark ``numpy.typing`` protocols as runtime checkable +* `#22358 <https://github.com/numpy/numpy/pull/22358>`__: ENH,TYP: Add special casing for ``ndarray``-based indexing +* `#22359 <https://github.com/numpy/numpy/pull/22359>`__: TYP,MAINT: Change more overloads to play nice with pyright +* `#22360 <https://github.com/numpy/numpy/pull/22360>`__: TST,TYP: Bump mypy to 0.981 +* `#22362 <https://github.com/numpy/numpy/pull/22362>`__: DOC: Updated amin/amax output dimensions for tuple axis +* `#22363 <https://github.com/numpy/numpy/pull/22363>`__: DOC: Added examples to ``maa.min`` function +* `#22365 <https://github.com/numpy/numpy/pull/22365>`__: BUG: Add ``__array_api_version__`` to ``numpy.array_api`` namespace +* `#22367 <https://github.com/numpy/numpy/pull/22367>`__: BUILD: add permissions to github actions +* `#22371 <https://github.com/numpy/numpy/pull/22371>`__: MAINT: remove permission restrictions for PR labeler [skip ci] +* `#22372 <https://github.com/numpy/numpy/pull/22372>`__: DOC: Update delimiter param description. +* `#22373 <https://github.com/numpy/numpy/pull/22373>`__: DOC, MAINT: Remove unused files +* `#22374 <https://github.com/numpy/numpy/pull/22374>`__: DOC: typo additional colon in beginners tutorial +* `#22375 <https://github.com/numpy/numpy/pull/22375>`__: DOC: How to partition domains +* `#22379 <https://github.com/numpy/numpy/pull/22379>`__: ENH: allow explicit ``like=None`` in all array creation functions +* `#22385 <https://github.com/numpy/numpy/pull/22385>`__: DEP: Deprecate conversion of out-of-bound Python integers +* `#22393 <https://github.com/numpy/numpy/pull/22393>`__: MAINT: Ensure graceful handling of large header sizes +* `#22398 <https://github.com/numpy/numpy/pull/22398>`__: DOC: Update broken link to diataxis framework. +* `#22399 <https://github.com/numpy/numpy/pull/22399>`__: MAINT: Fix typos found by codespell +* `#22401 <https://github.com/numpy/numpy/pull/22401>`__: MAINT: fix obsolete code comment +* `#22404 <https://github.com/numpy/numpy/pull/22404>`__: DOC: added ``ma.round`` and ``ma.round_`` examples +* `#22406 <https://github.com/numpy/numpy/pull/22406>`__: DOC: Add changelog for ``masked_invalid`` change. +* `#22407 <https://github.com/numpy/numpy/pull/22407>`__: DOC: Fix title level for release note improvements +* `#22409 <https://github.com/numpy/numpy/pull/22409>`__: DOC: Adopt a harmonic color scheme with the dark mode of pydata-sphinx-theme +* `#22411 <https://github.com/numpy/numpy/pull/22411>`__: DOC: Remove documentation specific to Python 2 +* `#22418 <https://github.com/numpy/numpy/pull/22418>`__: TST, BLD: Fix failing aarch64 wheel builds. +* `#22419 <https://github.com/numpy/numpy/pull/22419>`__: MAINT: Remove PyCObject from the SWIG interface +* `#22421 <https://github.com/numpy/numpy/pull/22421>`__: DOC: Replace CObject with Capsule consistently +* `#22422 <https://github.com/numpy/numpy/pull/22422>`__: ENH: Expose ``ufunc.resolve_dtypes`` and strided loop access +* `#22430 <https://github.com/numpy/numpy/pull/22430>`__: MAINT: Update main after 1.23.4 release. +* `#22432 <https://github.com/numpy/numpy/pull/22432>`__: MAINT: always use sys.base_prefix, never use sys.real_prefix +* `#22433 <https://github.com/numpy/numpy/pull/22433>`__: DOC: remove reference to Python 2 +* `#22436 <https://github.com/numpy/numpy/pull/22436>`__: DOC: Clarify docstring of ``masked_equal`` and ``masked_values`` +* `#22438 <https://github.com/numpy/numpy/pull/22438>`__: MAINT: Update versioneer 0.19 → 0.26 +* `#22440 <https://github.com/numpy/numpy/pull/22440>`__: MAINT: fix typo in f2c_lapack.c +* `#22441 <https://github.com/numpy/numpy/pull/22441>`__: MAINT,DOC: Revert "MAINT: fix typo in f2c_lapack.c" +* `#22442 <https://github.com/numpy/numpy/pull/22442>`__: ENH: unstructured_to_structured converts dtype argument +* `#22447 <https://github.com/numpy/numpy/pull/22447>`__: TYP: Spelling alignment for array flag literal +* `#22450 <https://github.com/numpy/numpy/pull/22450>`__: BUG: Fix bounds checking for random.logseries +* `#22452 <https://github.com/numpy/numpy/pull/22452>`__: DEV: Update GH actions and Dockerfile for Gitpod +* `#22453 <https://github.com/numpy/numpy/pull/22453>`__: DOC: Update NEP 50 text since integer conversion errors now exist. +* `#22456 <https://github.com/numpy/numpy/pull/22456>`__: DEP: Proposal to deprecate the ``msort`` convenience function +* `#22458 <https://github.com/numpy/numpy/pull/22458>`__: ENH: Allow all allocated operands in nditer/NpyIter +* `#22462 <https://github.com/numpy/numpy/pull/22462>`__: MAINT: refactor mandatory npymath functions to #define macros +* `#22463 <https://github.com/numpy/numpy/pull/22463>`__: DOC: remove mention of ``ipython -p numpy``. +* `#22466 <https://github.com/numpy/numpy/pull/22466>`__: MAINT: Ensure that fmin loops do not show up multiple times +* `#22475 <https://github.com/numpy/numpy/pull/22475>`__: MAINT: remove code specific to Python 2 +* `#22478 <https://github.com/numpy/numpy/pull/22478>`__: BUG: -unsigned_int(0) no overflow warning +* `#22479 <https://github.com/numpy/numpy/pull/22479>`__: MAINT: remove u-prefix for former Unicode strings +* `#22480 <https://github.com/numpy/numpy/pull/22480>`__: DOC: fix typo in advanced_debugging.rst [skip ci] +* `#22481 <https://github.com/numpy/numpy/pull/22481>`__: GitHub Workflows security hardening +* `#22482 <https://github.com/numpy/numpy/pull/22482>`__: ENH: Add OpenSSF Scorecard GitHub Action +* `#22483 <https://github.com/numpy/numpy/pull/22483>`__: MAINT: change subprocess arguments from Python>=3.7 +* `#22485 <https://github.com/numpy/numpy/pull/22485>`__: TST: Make test_partial_iteration_cleanup robust but require leak... +* `#22487 <https://github.com/numpy/numpy/pull/22487>`__: TST, MAINT: Replace most setup with setup_method (also teardown) +* `#22488 <https://github.com/numpy/numpy/pull/22488>`__: MAINT, CI: Switch to cygwin/cygwin-install-action@v2 +* `#22491 <https://github.com/numpy/numpy/pull/22491>`__: CI: Make cygwin build run for branches. +* `#22496 <https://github.com/numpy/numpy/pull/22496>`__: MAINT: Use SPDX license expression in project metadata +* `#22498 <https://github.com/numpy/numpy/pull/22498>`__: REL: readme in PyPI plus test +* `#22500 <https://github.com/numpy/numpy/pull/22500>`__: DOC: added example in char +* `#22503 <https://github.com/numpy/numpy/pull/22503>`__: CI: Only fetch in actions/checkout +* `#22504 <https://github.com/numpy/numpy/pull/22504>`__: DOC: Add code-formatting on install instructions +* `#22505 <https://github.com/numpy/numpy/pull/22505>`__: DOC: fixed minor typo in f2py docs +* `#22510 <https://github.com/numpy/numpy/pull/22510>`__: MAINT: Ensure raw dlpack deleter works when called without the... +* `#22519 <https://github.com/numpy/numpy/pull/22519>`__: DOC: fixed pad_width description in numpy.pad +* `#22521 <https://github.com/numpy/numpy/pull/22521>`__: DOC: Remove "current" from byte-order note and expand it slightly +* `#22524 <https://github.com/numpy/numpy/pull/22524>`__: MAINT, BLD: Wheel CI: Update cibuildwheel to 2.11.2 +* `#22525 <https://github.com/numpy/numpy/pull/22525>`__: BLD: update OpenBLAS to 0.3.21 and clean up openblas download... +* `#22531 <https://github.com/numpy/numpy/pull/22531>`__: BLD, CI: Update setup-python +* `#22538 <https://github.com/numpy/numpy/pull/22538>`__: DOC: update libnpymath docs on its status and how to consume... +* `#22540 <https://github.com/numpy/numpy/pull/22540>`__: DEP: Expire deprecation of dtype/signature allowing instances +* `#22541 <https://github.com/numpy/numpy/pull/22541>`__: DEP: Expire deprecation to ignore bad dtype= in logical ufuncs +* `#22542 <https://github.com/numpy/numpy/pull/22542>`__: API: Always use BufferError when dlpack export fails +* `#22543 <https://github.com/numpy/numpy/pull/22543>`__: DOC: Add instruction to initialize git submodules +* `#22548 <https://github.com/numpy/numpy/pull/22548>`__: MAINT: Fix designator order not matching declaration order +* `#22550 <https://github.com/numpy/numpy/pull/22550>`__: MAINT: Fix Fortran order flag use (using bool rather than enum) +* `#22552 <https://github.com/numpy/numpy/pull/22552>`__: MAINT: Do not use temporary struct construct +* `#22554 <https://github.com/numpy/numpy/pull/22554>`__: MAINT: Match arguments of constant in ``isless()`` +* `#22557 <https://github.com/numpy/numpy/pull/22557>`__: BUG: Decrement ref count in gentype_reduce if allocated memory... +* `#22561 <https://github.com/numpy/numpy/pull/22561>`__: BUG: Histogramdd breaks on big arrays in Windows +* `#22566 <https://github.com/numpy/numpy/pull/22566>`__: BUG: Fix use and errorchecking of ObjectType use +* `#22567 <https://github.com/numpy/numpy/pull/22567>`__: CI: Add PR write permissions to artifact redirector. +* `#22571 <https://github.com/numpy/numpy/pull/22571>`__: DOC: Mention numpy types in ``isnat`` error message +* `#22576 <https://github.com/numpy/numpy/pull/22576>`__: BUG: fix issue with broken assert statement in ``templ_common.h.src`` +* `#22578 <https://github.com/numpy/numpy/pull/22578>`__: BLD: fix issue with header includes in dlpack.c +* `#22579 <https://github.com/numpy/numpy/pull/22579>`__: MAINT: remove ``NPY_RESTRICT`` in favor of C99 ``restrict`` +* `#22580 <https://github.com/numpy/numpy/pull/22580>`__: BLD: remove unused ``ncola`` variables from lapack-lite +* `#22583 <https://github.com/numpy/numpy/pull/22583>`__: MAINT: Patch to remove ncola variable from f2c_blas.c +* `#22586 <https://github.com/numpy/numpy/pull/22586>`__: MAINT: Rm meaningless checks in determining typeless data +* `#22587 <https://github.com/numpy/numpy/pull/22587>`__: TYP: Update type annotations for new 1.24 features +* `#22588 <https://github.com/numpy/numpy/pull/22588>`__: DOC: Clarify relationship between row_stack and vstack. +* `#22589 <https://github.com/numpy/numpy/pull/22589>`__: DOC: expand docs on debugging with gdb +* `#22598 <https://github.com/numpy/numpy/pull/22598>`__: MAINT, CI: Update Ubuntu 18.04 to Ubuntu 20.04 +* `#22601 <https://github.com/numpy/numpy/pull/22601>`__: MAINT: Use C99 flexible struct construct for ``NpyIter_InternalOnly`` +* `#22605 <https://github.com/numpy/numpy/pull/22605>`__: MAINT: (array-coercion) Silence invalid read warning in some... +* `#22607 <https://github.com/numpy/numpy/pull/22607>`__: DEP: Next step in scalar type alias deprecations/futurewarnings +* `#22608 <https://github.com/numpy/numpy/pull/22608>`__: MAINT, CI: Enable coverage checking. +* `#22612 <https://github.com/numpy/numpy/pull/22612>`__: BLD: update wheel builds on macos to macos-12 image +* `#22614 <https://github.com/numpy/numpy/pull/22614>`__: MAINT: remove macOS specific long double handling in numpyconfig.h +* `#22615 <https://github.com/numpy/numpy/pull/22615>`__: DOC: Rm ``round_`` from the autosummary for rounding +* `#22616 <https://github.com/numpy/numpy/pull/22616>`__: TST: Rename setup to setup_method in _locales +* `#22620 <https://github.com/numpy/numpy/pull/22620>`__: DOC: testing: Fix typo: nulps -> nulp +* `#22628 <https://github.com/numpy/numpy/pull/22628>`__: DOC: Add example for np.ma.power +* `#22629 <https://github.com/numpy/numpy/pull/22629>`__: MAINT: Update main after 1.23.5 release. +* `#22630 <https://github.com/numpy/numpy/pull/22630>`__: BLD: Use cibuildwheel 2.9.0 for Python 3.8 aarch64 builds +* `#22634 <https://github.com/numpy/numpy/pull/22634>`__: CI: Increase travis timeout to 20 minutes. +* `#22636 <https://github.com/numpy/numpy/pull/22636>`__: CI: Increase travis timeout to 30 minutes (2). +* `#22639 <https://github.com/numpy/numpy/pull/22639>`__: DOC: Remove traces of interrupt handling utilities +* `#22662 <https://github.com/numpy/numpy/pull/22662>`__: rel: prepare for the numpy 1.24.0rc1 release. +* `#22665 <https://github.com/numpy/numpy/pull/22665>`__: MAINT: Fix 1.24.0 release note markup. +* `#22697 <https://github.com/numpy/numpy/pull/22697>`__: MAINT: Rename symbols in textreading/ that may clash when statically... +* `#22698 <https://github.com/numpy/numpy/pull/22698>`__: MAINT: check user-defined dtype has an ensure_canonical implementation +* `#22699 <https://github.com/numpy/numpy/pull/22699>`__: BUG: Ensure string aliases "int0", etc. remain valid for now +* `#22700 <https://github.com/numpy/numpy/pull/22700>`__: BLD: revert function() -> #define for 3 npymath functions +* `#22702 <https://github.com/numpy/numpy/pull/22702>`__: MAINT: pin ubuntu and python for emscripten +* `#22716 <https://github.com/numpy/numpy/pull/22716>`__: BLD, CI: Use cirrus for building aarch64 wheels +* `#22717 <https://github.com/numpy/numpy/pull/22717>`__: TST: Skip when numba/numpy compat issues cause SystemError +* `#22719 <https://github.com/numpy/numpy/pull/22719>`__: CI: Make benchmark asv run quick to only check that benchmarks... +* `#22729 <https://github.com/numpy/numpy/pull/22729>`__: REL: Prepare for the NumPy 1.24.0rc2 release. +* `#22743 <https://github.com/numpy/numpy/pull/22743>`__: DOC: Fix release note link to out-of-bounds integer deprecation +* `#22746 <https://github.com/numpy/numpy/pull/22746>`__: BUG: Fix some valgrind errors (and probably harmless warnings) +* `#22748 <https://github.com/numpy/numpy/pull/22748>`__: BUG: ``keepdims=True`` is ignored if ``out`` is not ``None``... +* `#22749 <https://github.com/numpy/numpy/pull/22749>`__: MAINT: check if PyArrayDTypeMeta_Spec->casts is set +* `#22757 <https://github.com/numpy/numpy/pull/22757>`__: CI: fix CIRRUS_TAG check when tagging. Closes #22730. +* `#22758 <https://github.com/numpy/numpy/pull/22758>`__: DOC: Some updates to the array_api compat document (#22747) +* `#22759 <https://github.com/numpy/numpy/pull/22759>`__: BUG, SIMD: Fix rounding large numbers >= 2^52 on SSE2 +* `#22760 <https://github.com/numpy/numpy/pull/22760>`__: CI, SIMD: Add workflow to test default baseline features only +* `#22761 <https://github.com/numpy/numpy/pull/22761>`__: BUG: Fix deepcopy cleanup on error +* `#22793 <https://github.com/numpy/numpy/pull/22793>`__: BUG: Fix infinite recursion in longdouble/large integer scalar... +* `#22795 <https://github.com/numpy/numpy/pull/22795>`__: BUG: Ensure arguments to ``npy_floatstatus_..._barrier()`` can... +* `#22805 <https://github.com/numpy/numpy/pull/22805>`__: REV: revert change to ``numpyconfig.h`` for sizeof(type) hardcoding... +* `#22815 <https://github.com/numpy/numpy/pull/22815>`__: BLD: use newer version of delocate diff --git a/doc/changelog/1.24.1-changelog.rst b/doc/changelog/1.24.1-changelog.rst new file mode 100644 index 000000000..5650438b6 --- /dev/null +++ b/doc/changelog/1.24.1-changelog.rst @@ -0,0 +1,43 @@ + +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/changelog/1.24.2-changelog.rst b/doc/changelog/1.24.2-changelog.rst new file mode 100644 index 000000000..399092eb0 --- /dev/null +++ b/doc/changelog/1.24.2-changelog.rst @@ -0,0 +1,44 @@ + +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/changelog/1.24.3-changelog.rst b/doc/changelog/1.24.3-changelog.rst new file mode 100644 index 000000000..ccfdfe8f0 --- /dev/null +++ b/doc/changelog/1.24.3-changelog.rst @@ -0,0 +1,42 @@ + +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/make.bat b/doc/make.bat new file mode 100644 index 000000000..974d5c3d8 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,74 @@ +@echo off + +pushd %~dp0 + +:: Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=LANG=C sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build +if defined SPHINXOPTS goto skipopts +set SPHINXOPTS=-W --keep-going -d build/doctrees %SPHINXOPTS% source +set DOXYGEN=doxygen +set FILES= +:skipopts + +if "%1" == "" goto help +if "%1" == "clean" goto clean +if "%1" == "docenv" goto docenv +if "%1" == "html" goto html +if "%1" == "linkcheck" goto linkcheck +if "%1" == "show" goto show + +:help + echo. + echo Please use "make.bat <target>" where ^<target^> is one of + echo. + echo clean to remove generated doc files and start fresh + echo docenv make a virtual environment in which to build docs + echo html to make standalone HTML files + echo linkcheck to check all external links for integrity + echo show to show the html output in a browser +goto end + +:clean +if exist "%SOURCEDIR%\build\" ( + rmdir /s /q "%SOURCEDIR%\build" + :: TODO + :: find . -name generated -type d -prune -exec rm -rf "{}" ";" +) +goto end + +:docenv +echo Not implemented +Rem python -mvenv docenv +Rem ( \ +Rem . docenv/bin/activate; \ +Rem pip install -q --upgrade pip; \ +Rem pip install -q -r ../test_requirements.txt; \ +Rem pip install -q -r ../doc_requirements.txt; \ +Rem pip install -q ..; \ +Rem ) +goto end + +:html +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:linkcheck + md build + md build\linkcheck + md build\doctrees + %SPHINXBUILD% -b linkcheck %SOURCEDIR% build\linkcheck + echo. + echo Link check complete; look for any errors in the above output + echo or in build\linkcheck\output.txt. +goto end + +:show +python -m webbrowser -t "%~dp0\build\html\index.html" + +:end +popd diff --git a/doc/neps/nep-0013-ufunc-overrides.rst b/doc/neps/nep-0013-ufunc-overrides.rst index c132113db..d69af6924 100644 --- a/doc/neps/nep-0013-ufunc-overrides.rst +++ b/doc/neps/nep-0013-ufunc-overrides.rst @@ -20,6 +20,8 @@ NEP 13 — A mechanism for overriding Ufuncs :Date: 2017-03-31 :Status: Final +:Updated: 2023-02-19 +:Author: Roy Smart Executive summary ================= @@ -173,12 +175,12 @@ where in all current cases only a single output makes sense). The function dispatch proceeds as follows: -- If one of the input or output arguments implements +- If one of the input, output, or ``where`` arguments implements ``__array_ufunc__``, it is executed instead of the ufunc. - If more than one of the arguments implements ``__array_ufunc__``, they are tried in the following order: subclasses before superclasses, - inputs before outputs, otherwise left to right. + inputs before outputs, outputs before ``where``, otherwise left to right. - The first ``__array_ufunc__`` method returning something else than :obj:`NotImplemented` determines the return value of the Ufunc. @@ -326,7 +328,10 @@ equivalent to:: def __array_ufunc__(self, ufunc, method, *inputs, **kwargs): # Cannot handle items that have __array_ufunc__ (other than our own). outputs = kwargs.get('out', ()) - for item in inputs + outputs: + objs = inputs + outputs + if "where" in kwargs: + objs = objs + (kwargs["where"], ) + for item in objs: if (hasattr(item, '__array_ufunc__') and type(item).__array_ufunc__ is not ndarray.__array_ufunc__): return NotImplemented diff --git a/doc/neps/nep-0019-rng-policy.rst b/doc/neps/nep-0019-rng-policy.rst index c5c46603b..44033357a 100644 --- a/doc/neps/nep-0019-rng-policy.rst +++ b/doc/neps/nep-0019-rng-policy.rst @@ -17,7 +17,7 @@ Abstract For the past decade, NumPy has had a strict backwards compatibility policy for the number stream of all of its random number distributions. Unlike other numerical components in ``numpy``, which are usually allowed to return -different when results when they are modified if they remain correct, we have +different results when modified if the results remain correct, we have obligated the random number distributions to always produce the exact same numbers in every version. The objective of our stream-compatibility guarantee was to provide exact reproducibility for simulations across numpy versions in diff --git a/doc/neps/nep-0021-advanced-indexing.rst b/doc/neps/nep-0021-advanced-indexing.rst index 7751d309b..4c7a16375 100644 --- a/doc/neps/nep-0021-advanced-indexing.rst +++ b/doc/neps/nep-0021-advanced-indexing.rst @@ -143,7 +143,7 @@ exactly. Vectorized indexing in particular can be challenging to implement with array storage backends not based on NumPy. In contrast, indexing by 1D arrays along -at least one dimension in the style of outer indexing is much more acheivable. +at least one dimension in the style of outer indexing is much more achievable. This has led many libraries (including dask and h5py) to attempt to define a safe subset of NumPy-style indexing that is equivalent to outer indexing, e.g., by only allowing indexing with an array along at most one dimension. However, diff --git a/doc/neps/nep-0029-deprecation_policy.rst b/doc/neps/nep-0029-deprecation_policy.rst index 4eb2aa50f..ccb566227 100644 --- a/doc/neps/nep-0029-deprecation_policy.rst +++ b/doc/neps/nep-0029-deprecation_policy.rst @@ -127,7 +127,10 @@ Apr 14, 2023 3.9+ 1.21+ Jun 23, 2023 3.9+ 1.22+ Jan 01, 2024 3.9+ 1.23+ Apr 05, 2024 3.10+ 1.23+ -Apr 04, 2025 3.11+ 1.23+ +Jun 22, 2024 3.10+ 1.24+ +Dec 18, 2024 3.10+ 1.25+ +Apr 04, 2025 3.11+ 1.25+ +Apr 24, 2026 3.12+ 1.25+ ============ ====== ===== @@ -150,7 +153,10 @@ Drop Schedule On Jun 23, 2023 drop support for NumPy 1.21 (initially released on Jun 22, 2021) On Jan 01, 2024 drop support for NumPy 1.22 (initially released on Dec 31, 2021) On Apr 05, 2024 drop support for Python 3.9 (initially released on Oct 05, 2020) + On Jun 22, 2024 drop support for NumPy 1.23 (initially released on Jun 22, 2022) + On Dec 18, 2024 drop support for NumPy 1.24 (initially released on Dec 18, 2022) On Apr 04, 2025 drop support for Python 3.10 (initially released on Oct 04, 2021) + On Apr 24, 2026 drop support for Python 3.11 (initially released on Oct 24, 2022) Implementation @@ -284,6 +290,9 @@ Code to generate support and drop schedule tables :: Jun 22, 2021: NumPy 1.21 Oct 04, 2021: Python 3.10 Dec 31, 2021: NumPy 1.22 + Jun 22, 2022: NumPy 1.23 + Oct 24, 2022: Python 3.11 + Dec 18, 2022: NumPy 1.24 """ releases = [] diff --git a/doc/neps/nep-0046-sponsorship-guidelines.rst b/doc/neps/nep-0046-sponsorship-guidelines.rst index ed54c21d5..746a73f5d 100644 --- a/doc/neps/nep-0046-sponsorship-guidelines.rst +++ b/doc/neps/nep-0046-sponsorship-guidelines.rst @@ -108,11 +108,12 @@ About page) will be added to acknowledge all current and previous sponsors, partners, and any other entities and individuals who provided $5,000 or more of financial or in-kind support. This page will include relevant details of support (dates, amounts, names, and purpose); no logos will be used on this -page. The rationale for the $5,000 minimum level is to keep the amount of work -maintaining the page reasonable; the level is the equivalent of, e.g., one GSoC -or a person-week's worth of engineering time in a Western country, which seems -like a reasonable lower limit. - +page. Such support, if provided for a specific enhancements or fix, may be +acknowledged in the appropriate release note snippet. The rationale for the +$5,000 minimum level is to keep the amount of work maintaining the page +reasonable; the level is the equivalent of, e.g., one GSoC or a person-week's +worth of engineering time in a Western country, which seems like a reasonable +lower limit. Implementation -------------- @@ -128,7 +129,6 @@ The following content changes need to be made: - Update https://numpy.org/about with details on how to get in touch with the NumPy project about sponsorship related matters (see next section). - NumPy Funding Team ~~~~~~~~~~~~~~~~~~ diff --git a/doc/neps/nep-0051-scalar-representation.rst b/doc/neps/nep-0051-scalar-representation.rst index 851f173de..1e6f27a5f 100644 --- a/doc/neps/nep-0051-scalar-representation.rst +++ b/doc/neps/nep-0051-scalar-representation.rst @@ -70,7 +70,7 @@ Even ``np.float64``, which is very similar to Python's ``float`` and inherits from it, does behave differently for example when dividing by zero. Another common source of confusion are the NumPy booleans. Python programmers -somtimes write ``obj is True`` and will surprised when an object that shows +sometimes write ``obj is True`` and will surprised when an object that shows as ``True`` fails to pass the test. It is much easier to understand this behavior when the value is shown as ``np.True_``. @@ -96,7 +96,7 @@ Jupyter notebook cells will often show the type information intact. np.longdouble('3.0') -to allow round-tripping. Addtionally to this change, ``float128`` will +to allow round-tripping. Additionally to this change, ``float128`` will now always be printed as ``longdouble`` since the old name gives a false impression of precision. @@ -137,7 +137,7 @@ The proposal is to change the default (back) to use ``str`` rather than Detailed description ==================== -This NEP proposes to change the represenatation for NumPy scalars to: +This NEP proposes to change the representation for NumPy scalars to: * ``np.True_`` and ``np.False_`` for booleans (their singleton instances) * ``np.scalar(<value>)``, i.e. ``np.float64(3.0)`` for all numerical dtypes. @@ -202,8 +202,8 @@ to always print as ``longdouble`` and never ``float128`` or ``float96``. It does not include deprecating the ``np.float128`` alias. However, such a deprecation may occur independently of the NEP. -Integer scalar type name and instance represenatation ------------------------------------------------------ +Integer scalar type name and instance representation +---------------------------------------------------- One detail is that due to NumPy scalar types being based on the C types, NumPy sometimes distinguishes them, for example on most 64 bit systems @@ -263,7 +263,7 @@ allowing customized formatting for all DTypes. Making ``get_formatter`` public allows it to be used for ``np.record`` and masked arrays. -Currenlty, the formatters themselves seem semi-public; using a single +Currently, the formatters themselves seem semi-public; using a single entry-point will hopefully provide a clear API for formatting NumPy values. The large part for the scalar representation changes had previously been done diff --git a/doc/postprocess.py b/doc/postprocess.py index 3e066d22e..4b48fa443 100755 --- a/doc/postprocess.py +++ b/doc/postprocess.py @@ -2,7 +2,7 @@ """ Post-processes HTML and Latex files output by Sphinx. """ -import io + def main(): import argparse @@ -15,13 +15,13 @@ def main(): mode = args.mode for fn in args.file: - with io.open(fn, 'r', encoding="utf-8") as f: + with open(fn, encoding="utf-8") as f: if mode == 'html': lines = process_html(fn, f.readlines()) elif mode == 'tex': lines = process_tex(f.readlines()) - with io.open(fn, 'w', encoding="utf-8") as f: + with open(fn, 'w', encoding="utf-8") as f: f.write("".join(lines)) def process_html(fn, lines): diff --git a/doc/preprocess.py b/doc/preprocess.py index 870d3e123..83980bb2f 100755 --- a/doc/preprocess.py +++ b/doc/preprocess.py @@ -32,7 +32,7 @@ def doxy_config(root_path): confs = [] dsrc_path = os.path.join(root_path, "doc", "source") sub = dict(ROOT_DIR=root_path) - with open(os.path.join(dsrc_path, "doxyfile"), "r") as fd: + with open(os.path.join(dsrc_path, "doxyfile")) as fd: conf = DoxyTpl(fd.read()) confs.append(conf.substitute(CUR_DIR=dsrc_path, **sub)) @@ -40,7 +40,7 @@ def doxy_config(root_path): if ".doxyfile" not in files: continue conf_path = os.path.join(dpath, ".doxyfile") - with open(conf_path, "r") as fd: + with open(conf_path) as fd: conf = DoxyTpl(fd.read()) confs.append(conf.substitute(CUR_DIR=dpath, **sub)) return confs diff --git a/doc/records.rst b/doc/records.rst index 3c0d55216..2e9b1251a 100644 --- a/doc/records.rst +++ b/doc/records.rst @@ -74,7 +74,7 @@ New possibilities for the "data-type" Reference counting for ``PyArray_Descr *`` objects. ``````````````````````````````````````````````````` -Most functions that take ``PyArary_Descr *`` as arguments and return a +Most functions that take ``PyArray_Descr *`` as arguments and return a ``PyObject *`` steal the reference unless otherwise noted in the code: Functions that return ``PyArray_Descr *`` objects return a new diff --git a/doc/release/numpy2_changes/23089.change.rst b/doc/release/numpy2_changes/23089.change.rst new file mode 100644 index 000000000..fbd87e0aa --- /dev/null +++ b/doc/release/numpy2_changes/23089.change.rst @@ -0,0 +1,2 @@ +* ``np.gradient()`` now returns a tuple rather than list making the + return value immutable. diff --git a/doc/release/numpy2_changes/README.md b/doc/release/numpy2_changes/README.md new file mode 100644 index 000000000..fb59749a9 --- /dev/null +++ b/doc/release/numpy2_changes/README.md @@ -0,0 +1,4 @@ +Same as ``../upcoming_changes`` but for changes that currently +are opt-in behind ``NPY_NUMPY_2_BEHAVIOR=1``. + +This is to get a start on release notes for such changes. diff --git a/doc/release/upcoming_changes/10615.deprecation.rst b/doc/release/upcoming_changes/10615.deprecation.rst new file mode 100644 index 000000000..7fa948ea8 --- /dev/null +++ b/doc/release/upcoming_changes/10615.deprecation.rst @@ -0,0 +1,14 @@ +Only ndim-0 arrays are treated as scalars +----------------------------------------- +NumPy used to treat all arrays of size 1 (e.g., ``np.array([3.14])``) as scalars. +In the future, this will be limited to arrays of ndim 0 (e.g., ``np.array(3.14)``). +The following expressions will report a deprecation warning: + +.. code-block:: python + + a = np.array([3.14]) + float(a) # better: a[0] to get the numpy.float or a.item() + + b = np.array([[3.14]]) + c = numpy.random.rand(10) + c[0] = b # better: c[0] = b[0, 0] diff --git a/doc/release/upcoming_changes/12065.performance.rst b/doc/release/upcoming_changes/12065.performance.rst deleted file mode 100644 index 08d1263b9..000000000 --- a/doc/release/upcoming_changes/12065.performance.rst +++ /dev/null @@ -1,6 +0,0 @@ -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.
\ No newline at end of file diff --git a/doc/release/upcoming_changes/16154.new_feature.rst b/doc/release/upcoming_changes/16154.new_feature.rst deleted file mode 100644 index 99d4b1b04..000000000 --- a/doc/release/upcoming_changes/16154.new_feature.rst +++ /dev/null @@ -1,25 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/18053.new_feature.rst b/doc/release/upcoming_changes/18053.new_feature.rst new file mode 100644 index 000000000..fea04f79a --- /dev/null +++ b/doc/release/upcoming_changes/18053.new_feature.rst @@ -0,0 +1,4 @@ +``np.einsum`` now accepts arrays with ``object`` dtype +------------------------------------------------------ +The code path will call python operators on object dtype arrays, much +like ``np.dot`` and ``np.matmul``. diff --git a/doc/release/upcoming_changes/18535.improvement.rst b/doc/release/upcoming_changes/18535.improvement.rst new file mode 100644 index 000000000..a0386b3bf --- /dev/null +++ b/doc/release/upcoming_changes/18535.improvement.rst @@ -0,0 +1,7 @@ +Fix power of complex zero +------------------------- +``np.power`` now returns a different result for ``0^{non-zero}`` +for complex numbers. Note that the value is only defined when +the real part of the exponent is larger than zero. +Previously, NaN was returned unless the imaginary part was strictly +zero. The return value is either ``0+0j`` or ``0-0j``. diff --git a/doc/release/upcoming_changes/19388.improvement.rst b/doc/release/upcoming_changes/19388.improvement.rst deleted file mode 100644 index c899f9019..000000000 --- a/doc/release/upcoming_changes/19388.improvement.rst +++ /dev/null @@ -1,10 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/19388.new_feature.rst b/doc/release/upcoming_changes/19388.new_feature.rst deleted file mode 100644 index bffe5753b..000000000 --- a/doc/release/upcoming_changes/19388.new_feature.rst +++ /dev/null @@ -1,10 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/20913.improvement.rst b/doc/release/upcoming_changes/20913.improvement.rst deleted file mode 100755 index 335f44831..000000000 --- a/doc/release/upcoming_changes/20913.improvement.rst +++ /dev/null @@ -1,12 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/20924.compatibility.rst b/doc/release/upcoming_changes/20924.compatibility.rst deleted file mode 100644 index 02f3e9fdb..000000000 --- a/doc/release/upcoming_changes/20924.compatibility.rst +++ /dev/null @@ -1,13 +0,0 @@ -``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. diff --git a/doc/release/upcoming_changes/21120.new_feature.rst b/doc/release/upcoming_changes/21120.new_feature.rst new file mode 100644 index 000000000..7d4dbf743 --- /dev/null +++ b/doc/release/upcoming_changes/21120.new_feature.rst @@ -0,0 +1,21 @@ +Add support for inplace matrix multiplication +---------------------------------------------- +It is now possible to perform inplace matrix multiplication +via the ``@=`` operator. + +.. code-block:: python + + >>> import numpy as np + + >>> a = np.arange(6).reshape(3, 2) + >>> print(a) + [[0 1] + [2 3] + [4 5]] + + >>> b = np.ones((2, 2), dtype=int) + >>> a @= b + >>> print(a) + [[1 1] + [5 5] + [9 9]] diff --git a/doc/release/upcoming_changes/21437.improvement.rst b/doc/release/upcoming_changes/21437.improvement.rst deleted file mode 100644 index 291483b5f..000000000 --- a/doc/release/upcoming_changes/21437.improvement.rst +++ /dev/null @@ -1,33 +0,0 @@ -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, 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. diff --git a/doc/release/upcoming_changes/21468.new_feature.rst b/doc/release/upcoming_changes/21468.new_feature.rst deleted file mode 100644 index c37f05735..000000000 --- a/doc/release/upcoming_changes/21468.new_feature.rst +++ /dev/null @@ -1,6 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/21483.performance.rst b/doc/release/upcoming_changes/21483.performance.rst deleted file mode 100644 index f9456d69f..000000000 --- a/doc/release/upcoming_changes/21483.performance.rst +++ /dev/null @@ -1,7 +0,0 @@ -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). diff --git a/doc/release/upcoming_changes/21506.change.rst b/doc/release/upcoming_changes/21506.change.rst deleted file mode 100644 index 18bc6cbc2..000000000 --- a/doc/release/upcoming_changes/21506.change.rst +++ /dev/null @@ -1,18 +0,0 @@ -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) diff --git a/doc/release/upcoming_changes/21595.new_feature.rst b/doc/release/upcoming_changes/21595.new_feature.rst deleted file mode 100644 index 21b2a746f..000000000 --- a/doc/release/upcoming_changes/21595.new_feature.rst +++ /dev/null @@ -1,5 +0,0 @@ -``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. diff --git a/doc/release/upcoming_changes/21623.new_feature.rst b/doc/release/upcoming_changes/21623.new_feature.rst deleted file mode 100644 index d783ef5a9..000000000 --- a/doc/release/upcoming_changes/21623.new_feature.rst +++ /dev/null @@ -1,6 +0,0 @@ -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``. diff --git a/doc/release/upcoming_changes/21627.new_feature.rst b/doc/release/upcoming_changes/21627.new_feature.rst deleted file mode 100644 index f516ac96d..000000000 --- a/doc/release/upcoming_changes/21627.new_feature.rst +++ /dev/null @@ -1,16 +0,0 @@ -``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')``.
\ No newline at end of file diff --git a/doc/release/upcoming_changes/21645.expired.rst b/doc/release/upcoming_changes/21645.expired.rst deleted file mode 100644 index 4c9933244..000000000 --- a/doc/release/upcoming_changes/21645.expired.rst +++ /dev/null @@ -1,4 +0,0 @@ -* 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. diff --git a/doc/release/upcoming_changes/21807.improvement.rst b/doc/release/upcoming_changes/21807.improvement.rst deleted file mode 100644 index bfad55fb7..000000000 --- a/doc/release/upcoming_changes/21807.improvement.rst +++ /dev/null @@ -1,7 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/21925.compatibility.rst b/doc/release/upcoming_changes/21925.compatibility.rst deleted file mode 100644 index af9c47127..000000000 --- a/doc/release/upcoming_changes/21925.compatibility.rst +++ /dev/null @@ -1,12 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/21976.new_feature.rst b/doc/release/upcoming_changes/21976.new_feature.rst deleted file mode 100644 index 387f093dd..000000000 --- a/doc/release/upcoming_changes/21976.new_feature.rst +++ /dev/null @@ -1,33 +0,0 @@ -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 instantization. - - >>> 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) diff --git a/doc/release/upcoming_changes/21995.compatibility.rst b/doc/release/upcoming_changes/21995.compatibility.rst deleted file mode 100644 index 0ae5e3626..000000000 --- a/doc/release/upcoming_changes/21995.compatibility.rst +++ /dev/null @@ -1,21 +0,0 @@ -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``. diff --git a/doc/release/upcoming_changes/22004.expired.rst b/doc/release/upcoming_changes/22004.expired.rst deleted file mode 100644 index e07dffa84..000000000 --- a/doc/release/upcoming_changes/22004.expired.rst +++ /dev/null @@ -1,2 +0,0 @@ -* Ragged array creation will now always raise a ``ValueError`` unless - ``dtype=object`` is passed. This includes very deeply nested sequences. diff --git a/doc/release/upcoming_changes/22014.improvement.rst b/doc/release/upcoming_changes/22014.improvement.rst deleted file mode 100644 index b32590c85..000000000 --- a/doc/release/upcoming_changes/22014.improvement.rst +++ /dev/null @@ -1,10 +0,0 @@ -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. - diff --git a/doc/release/upcoming_changes/22046.change.rst b/doc/release/upcoming_changes/22046.change.rst deleted file mode 100644 index 13a15f9e1..000000000 --- a/doc/release/upcoming_changes/22046.change.rst +++ /dev/null @@ -1,7 +0,0 @@ -``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 now behave identical to ``masked_where`` and better matches the -documentation. diff --git a/doc/release/upcoming_changes/22139.expired.rst b/doc/release/upcoming_changes/22139.expired.rst deleted file mode 100644 index baf19a0b2..000000000 --- a/doc/release/upcoming_changes/22139.expired.rst +++ /dev/null @@ -1,4 +0,0 @@ -* Support for Visual Studio 2015 and earlier has been removed. - -* Support for the Windows Interix POSIX interop layer has been removed. - diff --git a/doc/release/upcoming_changes/22159.expired.rst b/doc/release/upcoming_changes/22159.expired.rst deleted file mode 100644 index bb8405718..000000000 --- a/doc/release/upcoming_changes/22159.expired.rst +++ /dev/null @@ -1 +0,0 @@ -* Support for cygwin < 3.3 has been removed. diff --git a/doc/release/upcoming_changes/22228.expired.rst b/doc/release/upcoming_changes/22228.expired.rst deleted file mode 100644 index 220ae2a7b..000000000 --- a/doc/release/upcoming_changes/22228.expired.rst +++ /dev/null @@ -1,5 +0,0 @@ -* 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. diff --git a/doc/release/upcoming_changes/22313.deprecation.rst b/doc/release/upcoming_changes/22313.deprecation.rst deleted file mode 100644 index c4a0a4a9a..000000000 --- a/doc/release/upcoming_changes/22313.deprecation.rst +++ /dev/null @@ -1,10 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/22315.performance.rst b/doc/release/upcoming_changes/22315.performance.rst new file mode 100644 index 000000000..a2f623e5a --- /dev/null +++ b/doc/release/upcoming_changes/22315.performance.rst @@ -0,0 +1,7 @@ +Faster ``np.sort`` on AVX-512 enabled processors +------------------------------------------------ +Quicksort for 16-bit and 64-bit dtypes gain up to 15x and 9x speed up on +processors that support AVX-512 instruction set. + +Thanks to `Intel corporation <https://open.intel.com/>`_ for sponsoring this +work. diff --git a/doc/release/upcoming_changes/22357.improvement.rst b/doc/release/upcoming_changes/22357.improvement.rst deleted file mode 100644 index a0332eaa0..000000000 --- a/doc/release/upcoming_changes/22357.improvement.rst +++ /dev/null @@ -1,6 +0,0 @@ -``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. diff --git a/doc/release/upcoming_changes/22393.deprecation.rst b/doc/release/upcoming_changes/22393.deprecation.rst deleted file mode 100644 index 52099506c..000000000 --- a/doc/release/upcoming_changes/22393.deprecation.rst +++ /dev/null @@ -1,17 +0,0 @@ -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. diff --git a/doc/release/upcoming_changes/22456.deprecation.rst b/doc/release/upcoming_changes/22456.deprecation.rst deleted file mode 100644 index ab5e7ee31..000000000 --- a/doc/release/upcoming_changes/22456.deprecation.rst +++ /dev/null @@ -1,4 +0,0 @@ -Deprecate ``msort`` -------------------- - -The ``numpy.msort`` function is deprecated. Use ``np.sort(a, axis=0)`` instead. diff --git a/doc/release/upcoming_changes/22457.change.rst b/doc/release/upcoming_changes/22457.change.rst deleted file mode 100644 index 7d787441f..000000000 --- a/doc/release/upcoming_changes/22457.change.rst +++ /dev/null @@ -1,8 +0,0 @@ -``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. diff --git a/doc/release/upcoming_changes/22575.compatibility.rst b/doc/release/upcoming_changes/22575.compatibility.rst new file mode 100644 index 000000000..256a8e933 --- /dev/null +++ b/doc/release/upcoming_changes/22575.compatibility.rst @@ -0,0 +1,9 @@ +``np.pad`` with ``mode=wrap`` pads with strict multiples of original data +------------------------------------------------------------------------- + +Code based on earlier version of ``pad`` that uses ``mode="wrap"`` will return +different results when the padding size is larger than initial array. + +``np.pad`` with ``mode=wrap`` now always fills the space with +strict multiples of original data even if the padding size is larger than the +initial array. diff --git a/doc/release/upcoming_changes/22637.compatibility.rst b/doc/release/upcoming_changes/22637.compatibility.rst new file mode 100644 index 000000000..a35b70861 --- /dev/null +++ b/doc/release/upcoming_changes/22637.compatibility.rst @@ -0,0 +1,15 @@ +Cython ``long_t`` and ``ulong_t`` removed +----------------------------------------- +``long_t`` and ``ulong_t`` were aliases for ``longlong_t`` and ``ulonglong_t`` +and confusing (a remainder from of Python 2). This change may lead to the errors:: + + 'long_t' is not a type identifier + 'ulong_t' is not a type identifier + +We recommend use of bit-sized types such as ``cnp.int64_t`` or the use of +``cnp.intp_t`` which is 32 bits on 32 bit systems and 64 bits on 64 bit +systems (this is most compatible with indexing). +If C ``long`` is desired, use plain ``long`` or ``npy_long``. +``cnp.int_t`` is also ``long`` (NumPy's default integer). However, ``long`` +is 32 bit on 64 bit windows and we may wish to adjust this even in NumPy. +(Please do not hesitate to contact NumPy developers if you are curious about this.) diff --git a/doc/release/upcoming_changes/22638.deprecation.rst b/doc/release/upcoming_changes/22638.deprecation.rst new file mode 100644 index 000000000..2db186106 --- /dev/null +++ b/doc/release/upcoming_changes/22638.deprecation.rst @@ -0,0 +1,2 @@ +* ``np.core.MachAr`` is deprecated. It is private API. In names + defined in ``np.core`` should generally be considered private. diff --git a/doc/release/upcoming_changes/22638.expired.rst b/doc/release/upcoming_changes/22638.expired.rst new file mode 100644 index 000000000..01e87fa9f --- /dev/null +++ b/doc/release/upcoming_changes/22638.expired.rst @@ -0,0 +1 @@ +* ``np.core.machar`` and ``np.finfo.machar`` have been removed. diff --git a/doc/release/upcoming_changes/22644.new_feature.rst b/doc/release/upcoming_changes/22644.new_feature.rst new file mode 100644 index 000000000..e903fc7a0 --- /dev/null +++ b/doc/release/upcoming_changes/22644.new_feature.rst @@ -0,0 +1,7 @@ +NumPy now has an ``np.exceptions`` namespace +-------------------------------------------- +NumPy now has a dedicated namespace making most exceptions +and warnings available. All of these remain available in the +main namespace, although some may be moved slowly in the future. +The main reason for this is to increase discoverably and add +future exceptions. diff --git a/doc/release/upcoming_changes/22675.compatibility.rst b/doc/release/upcoming_changes/22675.compatibility.rst new file mode 100644 index 000000000..f3c08246b --- /dev/null +++ b/doc/release/upcoming_changes/22675.compatibility.rst @@ -0,0 +1,6 @@ +Changed error message and type for bad ``axes`` argument to ``ufunc`` +--------------------------------------------------------------------- +The error message and type when a wrong ``axes`` value is passed to +``ufunc(..., axes=[...])``` has changed. The message is now more indicative of +the problem, and if the value is mismatched an ``AxisError`` will be raised. +A ``TypeError`` will still be raised for invalid input types. diff --git a/doc/release/upcoming_changes/22707.compatibility.rst b/doc/release/upcoming_changes/22707.compatibility.rst new file mode 100644 index 000000000..8c9805f37 --- /dev/null +++ b/doc/release/upcoming_changes/22707.compatibility.rst @@ -0,0 +1,4 @@ +* When comparing datetimes and timedelta using ``np.equal`` or ``np.not_equal`` + numpy previously allowed the comparison with ``casting="unsafe"``. + This operation now fails. Forcing the output dtype using the ``dtype`` + kwarg can make the operation succeed, but we do not recommend it. diff --git a/doc/release/upcoming_changes/22707.expired.rst b/doc/release/upcoming_changes/22707.expired.rst new file mode 100644 index 000000000..496752e8d --- /dev/null +++ b/doc/release/upcoming_changes/22707.expired.rst @@ -0,0 +1,13 @@ +``==`` and ``!=`` warnings finalized +------------------------------------ +The ``==`` and ``!=`` operators on arrays now always: + +* raise errors that occur during comparisons such as when the arrays + have incompatible shapes (``np.array([1, 2]) == np.array([1, 2, 3])``). +* return an array of all ``True`` or all ``False`` when values are + fundamentally not comparable (e.g. have different dtypes). An example + is ``np.array(["a"]) == np.array([1])``. + +This mimics the Python behavior of returning ``False`` and ``True`` +when comparing incompatible types like ``"a" == 1`` and ``"a" != 1``. +For a long time these gave ``DeprecationWarning`` or ``FutureWarning``. diff --git a/doc/release/upcoming_changes/22707.improvement.rst b/doc/release/upcoming_changes/22707.improvement.rst new file mode 100644 index 000000000..1b8d4f844 --- /dev/null +++ b/doc/release/upcoming_changes/22707.improvement.rst @@ -0,0 +1,8 @@ +New ``DTypePromotionError`` +--------------------------- +NumPy now has a new ``DTypePromotionError`` which is used when two +dtypes cannot be promoted to a common one, for example:: + + np.result_type("M8[s]", np.complex128) + +raises this new exception. diff --git a/doc/release/upcoming_changes/22769.improvement.rst b/doc/release/upcoming_changes/22769.improvement.rst new file mode 100644 index 000000000..3566648ac --- /dev/null +++ b/doc/release/upcoming_changes/22769.improvement.rst @@ -0,0 +1,5 @@ +`np.show_config` uses information from Meson +-------------------------------------------- +Build and system information now contains information from Meson. +`np.show_config` now has a new optional parameter ``mode`` to help +customize the output. diff --git a/doc/release/upcoming_changes/22776.improvement.rst b/doc/release/upcoming_changes/22776.improvement.rst new file mode 100644 index 000000000..669fcff16 --- /dev/null +++ b/doc/release/upcoming_changes/22776.improvement.rst @@ -0,0 +1,6 @@ +Fix ``np.ma.diff`` not preserving the mask when called with arguments prepend/append. +------------------------------------------------------------------------------------- +Calling ``np.ma.diff`` with arguments prepend and/or append now returns a +``MaskedArray`` with the input mask preserved. + +Previously, a ``MaskedArray`` without the mask was returned.
\ No newline at end of file diff --git a/doc/release/upcoming_changes/22863.new_feature.rst b/doc/release/upcoming_changes/22863.new_feature.rst new file mode 100644 index 000000000..3f45ed834 --- /dev/null +++ b/doc/release/upcoming_changes/22863.new_feature.rst @@ -0,0 +1,4 @@ +String functions in np.char are compatible with NEP 42 custom dtypes +-------------------------------------------------------------------- +Custom dtypes that represent unicode strings or byte strings can now be +passed to the string functions in np.char. diff --git a/doc/release/upcoming_changes/22963.new_feature.rst b/doc/release/upcoming_changes/22963.new_feature.rst new file mode 100644 index 000000000..88ec3f641 --- /dev/null +++ b/doc/release/upcoming_changes/22963.new_feature.rst @@ -0,0 +1,7 @@ +String dtype instances can be created from the string abstract dtype classes +---------------------------------------------------------------------------- +It is now possible to create a string dtype instance with a size without +using the string name of the dtype. For example, ``type(np.dtype('U'))(8)`` +will create a dtype that is equivalent to ``np.dtype('U8')``. This feature +is most useful when writing generic code dealing with string dtype +classes. diff --git a/doc/release/upcoming_changes/22982.new_feature.rst b/doc/release/upcoming_changes/22982.new_feature.rst new file mode 100644 index 000000000..c98f2791c --- /dev/null +++ b/doc/release/upcoming_changes/22982.new_feature.rst @@ -0,0 +1,13 @@ +Fujitsu C/C++ compiler is now supported +---------------------------------------------- +Support for Fujitsu compiler has been added. +To build with Fujitsu compiler, run: + + python setup.py build -c fujitsu + + +SSL2 is now supported +----------------------------------- +Support for SSL2 has been added. SSL2 is a library that provides OpenBLAS compatible GEMM functions. +To enable SSL2, it need to edit site.cfg and build with Fujitsu compiler. +See site.cfg.example. diff --git a/doc/release/upcoming_changes/22997.improvement.rst b/doc/release/upcoming_changes/22997.improvement.rst new file mode 100644 index 000000000..156c9dece --- /dev/null +++ b/doc/release/upcoming_changes/22997.improvement.rst @@ -0,0 +1,5 @@ +Corrected error handling for NumPy C-API in Cython +-------------------------------------------------- +Many NumPy C functions defined for use in Cython were lacking the +correct error indicator like ``except -1`` or ``except *``. +These have now been added. diff --git a/doc/release/upcoming_changes/22998.expired.rst b/doc/release/upcoming_changes/22998.expired.rst new file mode 100644 index 000000000..a4399b639 --- /dev/null +++ b/doc/release/upcoming_changes/22998.expired.rst @@ -0,0 +1,2 @@ +* ``+arr`` will now raise an error when the dtype is not + numeric (and positive is undefined). diff --git a/doc/release/upcoming_changes/23011.deprecation.rst b/doc/release/upcoming_changes/23011.deprecation.rst new file mode 100644 index 000000000..72168ff87 --- /dev/null +++ b/doc/release/upcoming_changes/23011.deprecation.rst @@ -0,0 +1 @@ +* ``np.finfo(None)`` is deprecated. diff --git a/doc/release/upcoming_changes/23019.expired.rst b/doc/release/upcoming_changes/23019.expired.rst new file mode 100644 index 000000000..0879c2658 --- /dev/null +++ b/doc/release/upcoming_changes/23019.expired.rst @@ -0,0 +1,2 @@ +* A sequence must now be passed into the stacking family of functions + (``stack``, ``vstack``, ``hstack``, ``dstack`` and ``column_stack``). diff --git a/doc/release/upcoming_changes/23020.change.rst b/doc/release/upcoming_changes/23020.change.rst new file mode 100644 index 000000000..b4198fcba --- /dev/null +++ b/doc/release/upcoming_changes/23020.change.rst @@ -0,0 +1,9 @@ +Most NumPy functions are wrapped into a C-callable +-------------------------------------------------- +To speed up the ``__array_function__`` dispatching, most NumPy functions +are now wrapped into C-callables and are not proper Python functions or +C methods. +They still look and feel the same as before (like a Python function), and this +should only improve performance and user experience (cleaner tracebacks). +However, please inform the NumPy developers if this change confuses your +program for some reason. diff --git a/doc/release/upcoming_changes/23020.performance.rst b/doc/release/upcoming_changes/23020.performance.rst new file mode 100644 index 000000000..db9fcbf3c --- /dev/null +++ b/doc/release/upcoming_changes/23020.performance.rst @@ -0,0 +1,5 @@ +``__array_function__`` machinery is now much faster +--------------------------------------------------- +The overhead of the majority of functions in NumPy is now smaller +especially when keyword arguments are used. This change significantly +speeds up many simple function calls. diff --git a/doc/release/upcoming_changes/23041.expired.rst b/doc/release/upcoming_changes/23041.expired.rst new file mode 100644 index 000000000..9049ea70f --- /dev/null +++ b/doc/release/upcoming_changes/23041.expired.rst @@ -0,0 +1,27 @@ +Nose support has been removed +----------------------------- +NumPy switched to using pytest in 2018 and nose has been unmaintained for many +years. We have kept NumPy's nose support to avoid breaking downstream projects +who might have been using it and not yet switched to pytest or some other +testing framework. With the arrival of Python 3.12, unpatched nose will raise +an error. It is time to move on. + +Decorators removed +^^^^^^^^^^^^^^^^^^ +- raises +- slow +- setastest +- skipif +- knownfailif +- deprecated +- parametrize +- _needs_refcount + +These are not to be confused with pytest versions with similar names, e.g., +pytest.mark.slow, pytest.mark.skipif, pytest.mark.parametrize. + +Functions removed +^^^^^^^^^^^^^^^^^ +- Tester +- import_nose +- run_module_suite diff --git a/doc/release/upcoming_changes/23060.expired.rst b/doc/release/upcoming_changes/23060.expired.rst new file mode 100644 index 000000000..f80ba6fd0 --- /dev/null +++ b/doc/release/upcoming_changes/23060.expired.rst @@ -0,0 +1,5 @@ +The ``numpy.testing.utils`` shim has been removed. +-------------------------------------------------- +Importing from the ``numpy.testing.utils`` shim has been deprecated since 2019, +the shim has now been removed. All imports should be made directly from +``numpy.testing``. diff --git a/doc/release/upcoming_changes/23105.compatibility.rst b/doc/release/upcoming_changes/23105.compatibility.rst new file mode 100644 index 000000000..8a0b677e5 --- /dev/null +++ b/doc/release/upcoming_changes/23105.compatibility.rst @@ -0,0 +1,5 @@ +* When loading data from a file handle using ``np.load``, + if the handle is at the end of file, as can happen when reading + multiple arrays by calling ``np.load`` repeatedly, numpy previously + raised ``ValueError`` if ``allow_pickle=False``, and ``OSError`` if + ``allow_pickle=True``. Now it raises ``EOFError`` instead, in both cases. diff --git a/doc/release/upcoming_changes/23113.improvement.rst b/doc/release/upcoming_changes/23113.improvement.rst new file mode 100644 index 000000000..299b8f762 --- /dev/null +++ b/doc/release/upcoming_changes/23113.improvement.rst @@ -0,0 +1,3 @@ +- The ``NDArrayOperatorsMixin`` class now specifies that it contains no + ``__slots__`` ensureing that subclasses can now make use of this feature in + Python. diff --git a/doc/release/upcoming_changes/23136.performance.rst b/doc/release/upcoming_changes/23136.performance.rst new file mode 100644 index 000000000..1096f8bd1 --- /dev/null +++ b/doc/release/upcoming_changes/23136.performance.rst @@ -0,0 +1,18 @@ +``ufunc.at`` can be much faster +------------------------------- +Generic ``ufunc.at`` can be up to 9x faster. The conditions for this speedup: + +- operands are aligned +- no casting + +If ufuncs with appropriate indexed loops on 1d arguments with the above +conditions, ``ufunc.at`` can be up to 60x faster (an additional 7x speedup). +Appropriate indexed loops have been added to ``add``, ``subtract``, +``multiply``, ``floor_divide``, ``maximum``, ``minimum``, ``fmax``, and +``fmin``. + +The internal logic is similar to the logic used for regular ufuncs, which also +have fast paths. + +Thanks to the `D. E. Shaw group <https://deshaw.com/>`_ for sponsoring this +work. diff --git a/doc/release/upcoming_changes/23195.improvement.rst b/doc/release/upcoming_changes/23195.improvement.rst new file mode 100644 index 000000000..38b33e849 --- /dev/null +++ b/doc/release/upcoming_changes/23195.improvement.rst @@ -0,0 +1,20 @@ +Ability to directly spawn random number generators +-------------------------------------------------- +`numpy.random.Generator.spawn` now allows to directly spawn new +independent child generators via the `numpy.random.SeedSequence.spawn` +mechanism. +`numpy.random.BitGenerator.spawn` does the same for the underlying +bit generator. + +Additionally, `numpy.random.BitGenerator.seed_seq` now gives direct +access to the seed sequence used for initializing the bit generator. +This allows for example:: + + seed = 0x2e09b90939db40c400f8f22dae617151 + rng = np.random.default_rng(seed) + child_rng1, child_rng2 = rng.spawn(2) + + # safely use rng, child_rng1, and child_rng2 + +Previously, this was hard to do without passing the ``SeedSequence`` +explicitly. Please see `numpy.random.SeedSequence` for more information. diff --git a/doc/release/upcoming_changes/23229.compatibility.rst b/doc/release/upcoming_changes/23229.compatibility.rst new file mode 100644 index 000000000..284cc06ab --- /dev/null +++ b/doc/release/upcoming_changes/23229.compatibility.rst @@ -0,0 +1,3 @@ +- The ``busday_count`` method now correctly handles cases where the ``begindates`` is later in time + than the ``enddates``. Previously, the ``enddates`` was included, even though the documentation states + it is always excluded. diff --git a/doc/release/upcoming_changes/23240.compatibility.rst b/doc/release/upcoming_changes/23240.compatibility.rst new file mode 100644 index 000000000..28536a020 --- /dev/null +++ b/doc/release/upcoming_changes/23240.compatibility.rst @@ -0,0 +1,10 @@ +Array-likes that define ``__array_ufunc__`` can now override ufuncs if used as ``where`` +---------------------------------------------------------------------------------------- +If the ``where`` keyword argument of a :class:`numpy.ufunc` is a subclass of +:class:`numpy.ndarray` or is a duck type that defines +:func:`numpy.class.__array_ufunc__` it can override the behavior of the ufunc +using the same mechanism as the input and output arguments. +Note that for this to work properly, the ``where.__array_ufunc__`` +implementation will have to unwrap the ``where`` argument to pass it into the +default implementation of the ``ufunc`` or, for :class:`numpy.ndarray` +subclasses before using ``super().__array_ufunc__``.
\ No newline at end of file diff --git a/doc/release/upcoming_changes/23275.improvement.rst b/doc/release/upcoming_changes/23275.improvement.rst new file mode 100644 index 000000000..14ed5d9ad --- /dev/null +++ b/doc/release/upcoming_changes/23275.improvement.rst @@ -0,0 +1,4 @@ +``numpy.logspace`` now supports a non-scalar ``base`` argument +-------------------------------------------------------------- +The ``base`` argument of ``numpy.logspace`` can now be array-like if it's +broadcastable against the ``start`` and ``stop`` arguments.
\ No newline at end of file diff --git a/doc/release/upcoming_changes/23302.deprecation.rst b/doc/release/upcoming_changes/23302.deprecation.rst new file mode 100644 index 000000000..9e36d658c --- /dev/null +++ b/doc/release/upcoming_changes/23302.deprecation.rst @@ -0,0 +1 @@ +* ``np.round_`` is deprecated. Use `np.round` instead. diff --git a/doc/release/upcoming_changes/23314.deprecation.rst b/doc/release/upcoming_changes/23314.deprecation.rst new file mode 100644 index 000000000..8bed1aef8 --- /dev/null +++ b/doc/release/upcoming_changes/23314.deprecation.rst @@ -0,0 +1,4 @@ +* ``np.product`` is deprecated. Use `np.prod` instead. +* ``np.cumproduct`` is deprecated. Use `np.cumprod` instead. +* ``np.sometrue`` is deprecated. Use `np.any` instead. +* ``np.alltrue`` is deprecated. Use `np.all` instead. diff --git a/doc/release/upcoming_changes/23322.improvement.rst b/doc/release/upcoming_changes/23322.improvement.rst new file mode 100644 index 000000000..ce5ab8cf5 --- /dev/null +++ b/doc/release/upcoming_changes/23322.improvement.rst @@ -0,0 +1,4 @@ +`np.ma.dot()` now supports for non-2d arrays +-------------------------------------------- +Previously `np.ma.dot()` only worked if `a` and `b` were both 2d. +Now it works for non-2d arrays as well as `np.dot()`. diff --git a/doc/release/upcoming_changes/23357.improvement.rst b/doc/release/upcoming_changes/23357.improvement.rst new file mode 100644 index 000000000..3b474146b --- /dev/null +++ b/doc/release/upcoming_changes/23357.improvement.rst @@ -0,0 +1,9 @@ +Explicitly show keys of .npz file in repr +----------------------------------------- +``NpzFile`` shows keys of loaded .npz file when printed. + +.. code-block:: python + + >>> npzfile = np.load('arr.npz') + >>> npzfile + NpzFile 'arr.npz' with keys arr_0, arr_1, arr_2, arr_3, arr_4... diff --git a/doc/release/upcoming_changes/23358.improvement.rst b/doc/release/upcoming_changes/23358.improvement.rst new file mode 100644 index 000000000..a8a0e56ef --- /dev/null +++ b/doc/release/upcoming_changes/23358.improvement.rst @@ -0,0 +1,5 @@ +NumPy now exposes DType classes in ``np.dtypes`` +------------------------------------------------ +The new `numpy.dtypes` module now exposes DType classes and +will contain future dtype related functionality. +Most users should have no need to use these classes directly. diff --git a/doc/release/upcoming_changes/23376.expired.rst b/doc/release/upcoming_changes/23376.expired.rst new file mode 100644 index 000000000..e289b087c --- /dev/null +++ b/doc/release/upcoming_changes/23376.expired.rst @@ -0,0 +1,9 @@ +Environment variable to disable dispatching removed +--------------------------------------------------- +Support for the ``NUMPY_EXPERIMENTAL_ARRAY_FUNCTION`` environment variable has +been removed. This variable disabled dispatching with ``__array_function__``. + +Support for ``y=`` as an alias of ``out=`` removed +-------------------------------------------------- +The ``fix``, ``isposinf`` and ``isneginf`` functions allowed using ``y=`` as a +(deprecated) alias for ``out=``. This is no longer supported. diff --git a/doc/release/upcoming_changes/23403.expired.rst b/doc/release/upcoming_changes/23403.expired.rst new file mode 100644 index 000000000..b099eb4e9 --- /dev/null +++ b/doc/release/upcoming_changes/23403.expired.rst @@ -0,0 +1,4 @@ +* ``np.clip`` now defaults to same-kind casting. Falling back to + unsafe casting was deprecated in NumPy 1.17. +* ``np.clip`` will now propagate ``np.nan`` values passed as ``min`` or ``max``. + Previously, a scalar NaN was usually ignored. This was deprecated in NumPy 1.17. diff --git a/doc/release/upcoming_changes/23480.expired.rst b/doc/release/upcoming_changes/23480.expired.rst new file mode 100644 index 000000000..164677b98 --- /dev/null +++ b/doc/release/upcoming_changes/23480.expired.rst @@ -0,0 +1 @@ +* The ``np.dual`` submodule has been removed. diff --git a/doc/release/upcoming_changes/23528.compatibility.rst b/doc/release/upcoming_changes/23528.compatibility.rst new file mode 100644 index 000000000..439fb6a27 --- /dev/null +++ b/doc/release/upcoming_changes/23528.compatibility.rst @@ -0,0 +1,16 @@ +By default, the exported NumPy C API is now compatible with NumPy 1.19 +---------------------------------------------------------------------- +Starting with NumPy 1.25 when including NumPy headers, NumPy now +defaults to exposing a backwards compatible API. +This means that by default binaries such as wheels build against +NumPy 1.25 will also work with NumPy 1.16 because it has the same API version +as NumPy 1.19 which is the oldest NumPy version compatible with Python 3.9. + +You can customize this behavior using:: + + #define NPY_TARGET_VERSION NPY_1_22_API_VERSION + +or the equivalent ``-D`` option to the compiler. For more details +please see `for-downstream-package-authors`_. +A change should only be required in rare cases when a package relies on newly +added C-API. diff --git a/doc/release/upcoming_changes/23601.change.rst b/doc/release/upcoming_changes/23601.change.rst new file mode 100644 index 000000000..e09bd50fe --- /dev/null +++ b/doc/release/upcoming_changes/23601.change.rst @@ -0,0 +1,6 @@ +C++ standard library usage +-------------------------- + +NumPy builds now depend on the C++ standard library, because +the ``numpy.core._multiarray_umath`` extension is linked with +the C++ linker. diff --git a/doc/release/upcoming_changes/23660.expired.rst b/doc/release/upcoming_changes/23660.expired.rst new file mode 100644 index 000000000..615367350 --- /dev/null +++ b/doc/release/upcoming_changes/23660.expired.rst @@ -0,0 +1,2 @@ +* NumPy now always ignores sequence behavior for an array-like (defining + one of the array protocols). (Deprecation started NumPy 1.20) diff --git a/doc/release/upcoming_changes/23661.performance.rst b/doc/release/upcoming_changes/23661.performance.rst new file mode 100644 index 000000000..e3e55f3d5 --- /dev/null +++ b/doc/release/upcoming_changes/23661.performance.rst @@ -0,0 +1,4 @@ +Faster membership test on ``NpzFile`` +------------------------------------- +Membership test on ``NpzFile`` will no longer +decompress the archive if it is successful. diff --git a/doc/release/upcoming_changes/23666.expired.rst b/doc/release/upcoming_changes/23666.expired.rst new file mode 100644 index 000000000..eb51c91f3 --- /dev/null +++ b/doc/release/upcoming_changes/23666.expired.rst @@ -0,0 +1,5 @@ +* The niche ``FutureWarning`` when casting to a subarray dtype in ``astype`` + or the array creation functions such as ``asarray`` is now finalized. + The behavior is now always the same as if the subarray dtype was + wrapped into a single field (which was the workaround, previously). + (FutureWarning since NumPy 1.20) diff --git a/doc/release/upcoming_changes/23713.improvement.rst b/doc/release/upcoming_changes/23713.improvement.rst new file mode 100644 index 000000000..15a4f412b --- /dev/null +++ b/doc/release/upcoming_changes/23713.improvement.rst @@ -0,0 +1,9 @@ +Signed and unsigned integers always compare correctly +----------------------------------------------------- +When ``uint64`` and ``int64`` are mixed in NumPy, NumPy typically +promotes both to ``float64``. This behavior may be argued about +but is confusing for comparisons ``==``, ``<=``, since the results +returned can be incorrect but the conversion is hidden since the +result is a boolean. +NumPy will now return the correct results for these by avoiding +the cast to float. 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_advanced_debugging.rst b/doc/source/dev/development_advanced_debugging.rst index efd78cfad..735ff7328 100644 --- a/doc/source/dev/development_advanced_debugging.rst +++ b/doc/source/dev/development_advanced_debugging.rst @@ -1,3 +1,5 @@ +.. _advanced_debugging: + ======================== Advanced debugging tools ======================== @@ -39,12 +41,33 @@ and means you do not have to worry about making reference counting errors, which can be intimidating. -Python debug build for finding memory leaks -=========================================== +Python debug build +================== + +Debug builds of Python are easily available for example via the system package +manager on Linux systems, but are also available on other platforms, possibly in +a less convenient format. If you cannot easily install a debug build of Python +from a system package manager, you can build one yourself using `pyenv +<https://github.com/pyenv/pyenv>`_. For example, to install and globally +activate a debug build of Python 3.10.8, one would do:: + + pyenv install -g 3.10.8 + pyenv global 3.10.8 -Debug builds of Python are easily available for example on ``debian`` systems, -and can be used on all platforms. -Running a test or terminal is usually as easy as:: +Note that ``pyenv install`` builds Python from source, so you must ensure that +Python's dependencies are installed before building, see the pyenv documentation +for platform-specific installation instructions. You can use ``pip`` to install +Python dependencies you may need for your debugging session. If there is no +debug wheel available on `pypi,` you will need to build the dependencies from +source and ensure that your dependencies are also compiled as debug builds. + +Often debug builds of Python name the Python executable ``pythond`` instead of +``python``. To check if you have a debug build of Python installed, you can run +e.g. ``pythond -m sysconfig`` to get the build configuration for the Python +executable. A debug build will be built with debug compiler options in +``CFLAGS`` (e.g. ``-g -Og``). + +Running the Numpy tests or an interactive terminal is usually as easy as:: python3.8d runtests.py # or @@ -63,6 +86,8 @@ A Python debug build will help: sys.gettotalrefcount() sys.getallocatedblocks() +- Python debug builds allow easier debugging with gdb and other C debuggers. + Use together with ``pytest`` ---------------------------- diff --git a/doc/source/dev/development_environment.rst b/doc/source/dev/development_environment.rst index 4772366d2..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:: @@ -267,6 +288,10 @@ Python is running inside gdb to verify your setup:: >end sys.version_info(major=3, minor=7, micro=0, releaselevel='final', serial=0) +Most python builds do not include debug symbols and are built with compiler +optimizations enabled. To get the best debugging experience using a debug build +of Python is encouraged, see :ref:`advanced_debugging`. + Next you need to write a Python script that invokes the C code whose execution you want to debug. For instance ``mytest.py``:: @@ -285,14 +310,28 @@ And then in the debugger:: The execution will now stop at the corresponding C function and you can step through it as usual. A number of useful Python-specific commands are available. -For example to see where in the Python code you are, use ``py-list``. For more -details, see `DebuggingWithGdb`_. Here are some commonly used commands: +For example to see where in the Python code you are, use ``py-list``, to see the +python traceback, use ``py-bt``. For more details, see +`DebuggingWithGdb`_. Here are some commonly used commands: - ``list``: List specified function or line. - ``next``: Step program, proceeding through subroutine calls. - ``step``: Continue program being debugged, after signal or breakpoint. - ``print``: Print value of expression EXP. +Rich support for Python debugging requires that the ``python-gdb.py`` script +distributed with Python is installed in a path where gdb can find it. If you +installed your Python build from your system package manager, you likely do +not need to manually do anything. However, if you built Python from source, +you will likely need to create a ``.gdbinit`` file in your home directory +pointing gdb at the location of your Python installation. For example, a +version of python installed via `pyenv <https://github.com/pyenv/pyenv>`_ +needs a ``.gdbinit`` file with the following contents: + +.. code-block:: text + + add-auto-load-safe-path ~/.pyenv + Instead of plain ``gdb`` you can of course use your favourite alternative debugger; run it on the python binary with arguments ``runtests.py -g --python mytest.py``. @@ -300,8 +339,6 @@ alternative debugger; run it on the python binary with arguments Building NumPy with a Python built with debug support (on Linux distributions typically packaged as ``python-dbg``) is highly recommended. - - .. _DebuggingWithGdb: https://wiki.python.org/moin/DebuggingWithGdb .. _tox: https://tox.readthedocs.io/ .. _virtualenv: http://www.virtualenv.org/ 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 a2fc61d2e..75b7fb2f8 100644 --- a/doc/source/dev/gitwash/development_setup.rst +++ b/doc/source/dev/gitwash/development_setup.rst @@ -103,6 +103,14 @@ Make the local copy git config branch.main.remote upstream git config branch.main.merge refs/heads/main +#. Initialize the required git submodules: :: + + 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 7edc6722f..23b454ee5 100644 --- a/doc/source/f2py/buildtools/meson.rst +++ b/doc/source/f2py/buildtools/meson.rst @@ -23,13 +23,12 @@ 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: -.. literalinclude:: ./../code/meson.build - :language: meson +.. literalinclude:: ../code/meson.build At this point the build will complete, but the import will fail: @@ -58,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 @@ -69,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 @@ -93,8 +92,7 @@ for reasons discussed in :ref:`f2py-bldsys`. However, we can augment our workflow in a straightforward to take into account files for which the outputs are known when the build system is set up. -.. literalinclude:: ./../code/meson_upd.build - :language: meson +.. literalinclude:: ../code/meson_upd.build This can be compiled and run as before. 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/code/meson.build b/doc/source/f2py/code/meson.build index 04276a176..1d409f2fb 100644 --- a/doc/source/f2py/code/meson.build +++ b/doc/source/f2py/code/meson.build @@ -1,31 +1,35 @@ project('f2py_examples', 'c', version : '0.1', - default_options : ['warning_level=2']) + license: 'BSD-3', + meson_version: '>=0.64.0', + default_options : ['warning_level=2'], +) add_languages('fortran') py_mod = import('python') -py3 = py_mod.find_installation('python3') -py3_dep = py3.dependency() -message(py3.path()) -message(py3.get_install_dir()) +py = py_mod.find_installation(pure: false) +py_dep = py.dependency() -incdir_numpy = run_command(py3, +incdir_numpy = run_command(py, ['-c', 'import os; os.chdir(".."); import numpy; print(numpy.get_include())'], check : true ).stdout().strip() -incdir_f2py = run_command(py3, +incdir_f2py = run_command(py, ['-c', 'import os; os.chdir(".."); import numpy.f2py; print(numpy.f2py.get_include())'], check : true ).stdout().strip() inc_np = include_directories(incdir_numpy, incdir_f2py) -py3.extension_module('fib2', - 'fib1.f', - 'fib2module.c', - incdir_f2py+'/fortranobject.c', - include_directories: inc_np, - dependencies : py3_dep, - install : true)
\ No newline at end of file +py.extension_module('fib2', + [ + 'fib1.f', + 'fib2module.c', # note: this assumes f2py was manually run before! + ], + incdir_f2py / 'fortranobject.c', + include_directories: inc_np, + dependencies : py_dep, + install : true +) diff --git a/doc/source/f2py/code/meson_upd.build b/doc/source/f2py/code/meson_upd.build index 44d69d182..5e4b13bae 100644 --- a/doc/source/f2py/code/meson_upd.build +++ b/doc/source/f2py/code/meson_upd.build @@ -1,37 +1,38 @@ project('f2py_examples', 'c', version : '0.1', - default_options : ['warning_level=2']) + license: 'BSD-3', + meson_version: '>=0.64.0', + default_options : ['warning_level=2'], +) add_languages('fortran') py_mod = import('python') -py3 = py_mod.find_installation('python3') -py3_dep = py3.dependency() -message(py3.path()) -message(py3.get_install_dir()) +py = py_mod.find_installation(pure: false) +py_dep = py.dependency() -incdir_numpy = run_command(py3, +incdir_numpy = run_command(py, ['-c', 'import os; os.chdir(".."); import numpy; print(numpy.get_include())'], check : true ).stdout().strip() -incdir_f2py = run_command(py3, +incdir_f2py = run_command(py, ['-c', 'import os; os.chdir(".."); import numpy.f2py; print(numpy.f2py.get_include())'], check : true ).stdout().strip() fibby_source = custom_target('fibbymodule.c', - input : ['fib1.f'], # .f so no F90 wrappers - output : ['fibbymodule.c', 'fibby-f2pywrappers.f'], - command : [ py3, '-m', 'numpy.f2py', '@INPUT@', - '-m', 'fibby', '--lower']) + input : ['fib1.f'], # .f so no F90 wrappers + output : ['fibbymodule.c', 'fibby-f2pywrappers.f'], + command : [py, '-m', 'numpy.f2py', '@INPUT@', '-m', 'fibby', '--lower'] +) inc_np = include_directories(incdir_numpy, incdir_f2py) -py3.extension_module('fibby', - 'fib1.f', - fibby_source, - incdir_f2py+'/fortranobject.c', - include_directories: inc_np, - dependencies : py3_dep, - install : true) +py.extension_module('fibby', + ['fib1.f', fibby_source], + incdir_f2py / 'fortranobject.c', + include_directories: inc_np, + dependencies : py_dep, + install : true +) 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/array_api.rst b/doc/source/reference/array_api.rst index 01c8787eb..6982ef310 100644 --- a/doc/source/reference/array_api.rst +++ b/doc/source/reference/array_api.rst @@ -152,8 +152,9 @@ Keyword Argument Renames The following functions have keyword arguments that have been renamed. The functionality of the keyword argument is identical unless otherwise stated. -Each new keyword argument is not already present on the given function in -``numpy``, so the changes are **compatible**. +Renamed keyword arguments with the same semantic definition may be considered +either **compatible** or **breaking**, depending on how the change is +implemented. Note, this page does not list function keyword arguments that are in the main ``numpy`` namespace but not in the array API. Such keyword arguments are @@ -189,7 +190,11 @@ functions to include additional keyword arguments from those required. - ``correction`` - ``ddof`` - - + * - ``reshape`` + - ``shape`` + - ``newshape`` + - The argument may be passed as a positional or keyword argument for both + NumPy and the array API. .. _array_api-type-promotion-differences: @@ -228,6 +233,12 @@ independently of values or shapes. promoted. - **Breaking** - Example: ``a = np.array(1, dtype=np.int8); a += np.array(1, dtype=np.int16)``. The spec explicitly disallows this. + * - In-place operators are disallowed when the right-hand side operand + cannot broadcast to the shape of the left-hand side operand. + - **Strictness** + - This so-called "reverse broadcasting" should not be allowed. Example: + ``a = np.empty((2, 3, 4)); a += np.empty((3, 4))`` should error. See + https://github.com/numpy/numpy/issues/10404. * - ``int`` promotion for operators is only specified for integers within the bounds of the dtype. - **Strictness** 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..baebfdb02 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) @@ -1202,17 +1186,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 +1463,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 +2249,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 +2448,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 +3351,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 +3581,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/config.rst b/doc/source/reference/c-api/config.rst index 87130699b..963a106f8 100644 --- a/doc/source/reference/c-api/config.rst +++ b/doc/source/reference/c-api/config.rst @@ -118,14 +118,3 @@ Compiler directives .. c:macro:: NPY_LIKELY .. c:macro:: NPY_UNLIKELY .. c:macro:: NPY_UNUSED - - -Interrupt Handling ------------------- - -.. c:macro:: NPY_INTERRUPT_H -.. c:macro:: NPY_SIGSETJMP -.. c:macro:: NPY_SIGLONGJMP -.. c:macro:: NPY_SIGJMP_BUF -.. c:macro:: NPY_SIGINT_ON -.. c:macro:: NPY_SIGINT_OFF diff --git a/doc/source/reference/c-api/coremath.rst b/doc/source/reference/c-api/coremath.rst index eb0990edb..2293f0ae8 100644 --- a/doc/source/reference/c-api/coremath.rst +++ b/doc/source/reference/c-api/coremath.rst @@ -55,30 +55,30 @@ Floating point classification .. c:macro:: npy_isnan(x) - This is a macro, and is equivalent to C99 isnan: works for single, double + This is an alias for C99 isnan: works for single, double and extended precision, and return a non 0 value if x is a NaN. .. c:macro:: npy_isfinite(x) - This is a macro, and is equivalent to C99 isfinite: works for single, + This is an alias for C99 isfinite: works for single, double and extended precision, and return a non 0 value if x is neither a NaN nor an infinity. .. c:macro:: npy_isinf(x) - This is a macro, and is equivalent to C99 isinf: works for single, double + This is an alias for C99 isinf: works for single, double and extended precision, and return a non 0 value if x is infinite (positive and negative). .. c:macro:: npy_signbit(x) - This is a macro, and is equivalent to C99 signbit: works for single, double + This is an alias for C99 signbit: works for single, double and extended precision, and return a non 0 value if x has the signbit set (that is the number is negative). .. c:macro:: npy_copysign(x, y) - This is a function equivalent to C99 copysign: return x with the same sign + This is an alias for C99 copysign: return x with the same sign as y. Works for any value, including inf and nan. Single and extended precisions are available with suffix f and l. @@ -141,7 +141,7 @@ Those can be useful for precise floating point comparison. .. c:function:: double npy_nextafter(double x, double y) - This is a function equivalent to C99 nextafter: return next representable + This is an alias to C99 nextafter: return next representable floating point value from x in the direction of y. Single and extended precisions are available with suffix f and l. 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 07187e7f1..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. -Simple Iteration Example ------------------------- +.. _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 @@ -115,10 +117,10 @@ number of non-zero elements in an array. return nonzero_count; } -Simple Multi-Iteration Example +Multi-Iteration Example ------------------------------ -Here is a simple copy function using the iterator. The ``order`` parameter +Here is a copy function using the iterator. The ``order`` parameter is used to control the memory layout of the allocated result, typically :c:data:`NPY_KEEPORDER` is desired. 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.dtype.rst b/doc/source/reference/routines.dtype.rst index e9189ca07..6cb036031 100644 --- a/doc/source/reference/routines.dtype.rst +++ b/doc/source/reference/routines.dtype.rst @@ -30,7 +30,6 @@ Data type information finfo iinfo - MachAr Data type testing ----------------- 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 a454841b3..4cc8719fb 100644 --- a/doc/source/reference/routines.math.rst +++ b/doc/source/reference/routines.math.rst @@ -39,8 +39,8 @@ Rounding .. autosummary:: :toctree: generated/ + round around - round_ rint fix floor @@ -149,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 e980406eb..769b3d910 100644 --- a/doc/source/reference/routines.other.rst +++ b/doc/source/reference/routines.other.rst @@ -58,9 +58,6 @@ Matlab-like Functions who disp -Exceptions ----------- -.. autosummary:: - :toctree: generated/ +.. automodule:: numpy.exceptions - AxisError +.. automodule:: numpy.dtypes diff --git a/doc/source/reference/routines.rst b/doc/source/reference/routines.rst index 593d017cc..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 @@ -44,4 +43,5 @@ indentation. routines.sort routines.statistics routines.testing + routines.testing.overrides routines.window diff --git a/doc/source/reference/routines.testing.overrides.rst b/doc/source/reference/routines.testing.overrides.rst new file mode 100644 index 000000000..262852633 --- /dev/null +++ b/doc/source/reference/routines.testing.overrides.rst @@ -0,0 +1,18 @@ +.. module:: numpy.testing.overrides + +Support for testing overrides (:mod:`numpy.testing.overrides`) +============================================================== + +.. currentmodule:: numpy.testing.overrides + +Support for testing custom array container implementations. + +Utility Functions +----------------- +.. autosummary:: + :toctree: generated/ + + allows_array_function_override + allows_array_ufunc_override + get_overridable_numpy_ufuncs + get_overridable_numpy_array_functions 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 5742f7e57..b8a877924 100644 --- a/doc/source/release.rst +++ b/doc/source/release.rst @@ -5,7 +5,12 @@ Release notes .. toctree:: :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> 1.23.3 <release/1.23.3-notes> 1.23.2 <release/1.23.2-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.23.5-notes.rst b/doc/source/release/1.23.5-notes.rst new file mode 100644 index 000000000..8e14794e4 --- /dev/null +++ b/doc/source/release/1.23.5-notes.rst @@ -0,0 +1,39 @@ +.. currentmodule:: numpy + +========================== +NumPy 1.23.5 Release Notes +========================== +NumPy 1.23.5 is a maintenance release that fixes bugs discovered after the +1.23.4 release and keeps the build infrastructure current. +The Python versions supported for this release are 3.8-3.11. + +Contributors +============ + +A total of 7 people contributed to this release. People with a "+" by their +names contributed a patch for the first time. + +* @DWesl +* Aayush Agrawal + +* Adam Knapp + +* Charles Harris +* Navpreet Singh + +* Sebastian Berg +* Tania Allard + +Pull requests merged +==================== + +A total of 10 pull requests were merged for this release. + +* `#22489 <https://github.com/numpy/numpy/pull/22489>`__: TST, MAINT: Replace most setup with setup_method (also teardown) +* `#22490 <https://github.com/numpy/numpy/pull/22490>`__: MAINT, CI: Switch to cygwin/cygwin-install-action@v2 +* `#22494 <https://github.com/numpy/numpy/pull/22494>`__: TST: Make test_partial_iteration_cleanup robust but require leak... +* `#22592 <https://github.com/numpy/numpy/pull/22592>`__: MAINT: Ensure graceful handling of large header sizes +* `#22593 <https://github.com/numpy/numpy/pull/22593>`__: TYP: Spelling alignment for array flag literal +* `#22594 <https://github.com/numpy/numpy/pull/22594>`__: BUG: Fix bounds checking for ``random.logseries`` +* `#22595 <https://github.com/numpy/numpy/pull/22595>`__: DEV: Update GH actions and Dockerfile for Gitpod +* `#22596 <https://github.com/numpy/numpy/pull/22596>`__: CI: Only fetch in actions/checkout +* `#22597 <https://github.com/numpy/numpy/pull/22597>`__: BUG: Decrement ref count in gentype_reduce if allocated memory... +* `#22625 <https://github.com/numpy/numpy/pull/22625>`__: BUG: Histogramdd breaks on big arrays in Windows + 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/release/1.25.0-notes.rst b/doc/source/release/1.25.0-notes.rst new file mode 100644 index 000000000..9b29b79df --- /dev/null +++ b/doc/source/release/1.25.0-notes.rst @@ -0,0 +1,45 @@ +.. currentmodule:: numpy + +========================== +NumPy 1.25.0 Release Notes +========================== + + +Highlights +========== + + +New functions +============= + + +Deprecations +============ + + +Future Changes +============== + + +Expired deprecations +==================== + + +Compatibility notes +=================== + + +C API changes +============= + + +New Features +============ + + +Improvements +============ + + +Changes +======= diff --git a/doc/source/release/1.4.0-notes.rst b/doc/source/release/1.4.0-notes.rst index 9480a054e..df7b72da6 100644 --- a/doc/source/release/1.4.0-notes.rst +++ b/doc/source/release/1.4.0-notes.rst @@ -110,7 +110,7 @@ Testing #. deprecated decorator: this decorator may be used to avoid cluttering testing output while testing DeprecationWarning is effectively raised by the decorated test. - #. assert_array_almost_equal_nulps: new method to compare two arrays of + #. assert_array_almost_equal_nulp: new method to compare two arrays of floating point values. With this function, two values are considered close if there are not many representable floating point values in between, thus being more robust than assert_array_almost_equal when the 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 0d0ddfcdb..a493ef769 100644 --- a/doc/source/user/basics.dispatch.rst +++ b/doc/source/user/basics.dispatch.rst @@ -271,6 +271,36 @@ array([[1., 0., 0., 0., 0.], [0., 0., 0., 1., 0.], [0., 0., 0., 0., 1.]]) + +The implementation of ``DiagonalArray`` in this example only handles the +``np.sum`` and ``np.mean`` functions for brevity. Many other functions in the +Numpy API are also available to wrap and a full-fledged custom array container +can explicitly support all functions that Numpy makes available to wrap. + +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 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 overridden via +``__array_function__`` using +:func:`~numpy.testing.overrides.allows_array_function_override`. + +Lists of every overridable function in the Numpy API are also available via +:func:`~numpy.testing.overrides.get_overridable_numpy_array_functions` for +functions that support the ``__array_function__`` protocol and +:func:`~numpy.testing.overrides.get_overridable_numpy_ufuncs` for functions that +support the ``__array_ufunc__`` protocol. Both functions return sets of +functions that are present in the Numpy public API. User-defined ufuncs or +ufuncs defined in other libraries that depend on Numpy are not present in +these sets. + Refer to the `dask source code <https://github.com/dask/dask>`_ and `cupy source code <https://github.com/cupy/cupy>`_ for more fully-worked examples of custom array containers. diff --git a/doc/source/user/basics.indexing.rst b/doc/source/user/basics.indexing.rst index 088d280a2..17fc9c0cc 100644 --- a/doc/source/user/basics.indexing.rst +++ b/doc/source/user/basics.indexing.rst @@ -294,10 +294,6 @@ basic slicing that returns a :term:`view`). the former will trigger advanced indexing. Be sure to understand why this occurs. - Also recognize that ``x[[1, 2, 3]]`` will trigger advanced indexing, - whereas due to the deprecated Numeric compatibility mentioned above, - ``x[[1, 2, slice(None)]]`` will trigger basic slicing. - Integer array indexing ~~~~~~~~~~~~~~~~~~~~~~ @@ -485,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 81f6d33a7..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 @@ -79,6 +62,10 @@ Building NumPy requires the following software installed: For building NumPy, you'll need a recent version of Cython. +5) The NumPy source code + + Clone the repository following the instructions in :doc:`/dev/index`. + Basic Installation ------------------ diff --git a/doc/source/user/how-to-index.rst b/doc/source/user/how-to-index.rst index 41061d5f4..97c451260 100644 --- a/doc/source/user/how-to-index.rst +++ b/doc/source/user/how-to-index.rst @@ -1,6 +1,6 @@ .. currentmodule:: numpy -.. _how-to-index.rst: +.. _how-to-index: ***************************************** How to index :class:`ndarrays <.ndarray>` @@ -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-partition.rst b/doc/source/user/how-to-partition.rst new file mode 100644 index 000000000..224519364 --- /dev/null +++ b/doc/source/user/how-to-partition.rst @@ -0,0 +1,268 @@ +.. _how-to-partition: + +================================================= +How to create arrays with regularly-spaced values +================================================= + +There are a few NumPy functions that are similar in application, but which +provide slightly different results, which may cause confusion if one is not sure +when and how to use them. The following guide aims to list these functions and +describe their recommended usage. + +The functions mentioned here are + +* `numpy.linspace` +* `numpy.arange` +* `numpy.geomspace` +* `numpy.logspace` +* `numpy.meshgrid` +* `numpy.mgrid` +* `numpy.ogrid` + +1D domains (intervals) +====================== + +``linspace`` vs. ``arange`` +--------------------------- + +Both `numpy.linspace` and `numpy.arange` provide ways to partition an interval +(a 1D domain) into equal-length subintervals. These partitions will vary +depending on the chosen starting and ending points, and the **step** (the length +of the subintervals). + +* **Use** `numpy.arange` **if you want integer steps.** + + `numpy.arange` relies on step size to determine how many elements are in the + returned array, which excludes the endpoint. This is determined through the + ``step`` argument to ``arange``. + + Example:: + + >>> np.arange(0, 10, 2) # np.arange(start, stop, step) + array([0, 2, 4, 6, 8]) + + The arguments ``start`` and ``stop`` should be integer or real, but not + complex numbers. `numpy.arange` is similar to the Python built-in + :py:class:`range`. + + Floating-point inaccuracies can make ``arange`` results with floating-point + numbers confusing. In this case, you should use `numpy.linspace` instead. + +* **Use** `numpy.linspace` **if you want the endpoint to be included in the + result, or if you are using a non-integer step size.** + + `numpy.linspace` *can* include the endpoint and determines step size from the + `num` argument, which specifies the number of elements in the returned + array. + + The inclusion of the endpoint is determined by an optional boolean + argument ``endpoint``, which defaults to ``True``. Note that selecting + ``endpoint=False`` will change the step size computation, and the subsequent + output for the function. + + Example:: + + >>> np.linspace(0.1, 0.2, num=5) # np.linspace(start, stop, num) + array([0.1 , 0.125, 0.15 , 0.175, 0.2 ]) + >>> np.linspace(0.1, 0.2, num=5, endpoint=False) + array([0.1, 0.12, 0.14, 0.16, 0.18]) + + `numpy.linspace` can also be used with complex arguments:: + + >>> np.linspace(1+1.j, 4, 5, dtype=np.complex64) + array([1. +1.j , 1.75+0.75j, 2.5 +0.5j , 3.25+0.25j, 4. +0.j ], + dtype=complex64) + +Other examples +-------------- + +1. Unexpected results may happen if floating point values are used as ``step`` + in ``numpy.arange``. To avoid this, make sure all floating point conversion + happens after the computation of results. For example, replace + + :: + + >>> list(np.arange(0.1,0.4,0.1).round(1)) + [0.1, 0.2, 0.3, 0.4] # endpoint should not be included! + + with + + :: + + >>> list(np.arange(1, 4, 1) / 10.0) + [0.1, 0.2, 0.3] # expected result + +2. Note that + + :: + + >>> np.arange(0, 1.12, 0.04) + array([0. , 0.04, 0.08, 0.12, 0.16, 0.2 , 0.24, 0.28, 0.32, 0.36, 0.4 , + 0.44, 0.48, 0.52, 0.56, 0.6 , 0.64, 0.68, 0.72, 0.76, 0.8 , 0.84, + 0.88, 0.92, 0.96, 1. , 1.04, 1.08, 1.12]) + + and + + :: + + >>> np.arange(0, 1.08, 0.04) + array([0. , 0.04, 0.08, 0.12, 0.16, 0.2 , 0.24, 0.28, 0.32, 0.36, 0.4 , + 0.44, 0.48, 0.52, 0.56, 0.6 , 0.64, 0.68, 0.72, 0.76, 0.8 , 0.84, + 0.88, 0.92, 0.96, 1. , 1.04]) + + These differ because of numeric noise. When using floating point values, it + is possible that ``0 + 0.04 * 28 < 1.12``, and so ``1.12`` is in the + interval. In fact, this is exactly the case:: + + >>> 1.12/0.04 + 28.000000000000004 + + But ``0 + 0.04 * 27 >= 1.08`` so that 1.08 is excluded:: + + >>> 1.08/0.04 + 27.0 + + Alternatively, you could use ``np.arange(0, 28)*0.04`` which would always + give you precise control of the end point since it is integral:: + + >>> np.arange(0, 28)*0.04 + array([0. , 0.04, 0.08, 0.12, 0.16, 0.2 , 0.24, 0.28, 0.32, 0.36, 0.4 , + 0.44, 0.48, 0.52, 0.56, 0.6 , 0.64, 0.68, 0.72, 0.76, 0.8 , 0.84, + 0.88, 0.92, 0.96, 1. , 1.04, 1.08]) + + +``geomspace`` and ``logspace`` +------------------------------ + +``numpy.geomspace`` is similar to ``numpy.linspace``, but with numbers spaced +evenly on a log scale (a geometric progression). The endpoint is included in the +result. + +Example:: + + >>> np.geomspace(2, 3, num=5) + array([2. , 2.21336384, 2.44948974, 2.71080601, 3. ]) + +``numpy.logspace`` is similar to ``numpy.geomspace``, but with the start and end +points specified as logarithms (with base 10 as default):: + + >>> np.logspace(2, 3, num=5) + array([ 100. , 177.827941 , 316.22776602, 562.34132519, 1000. ]) + +In linear space, the sequence starts at ``base ** start`` (``base`` to the power +of ``start``) and ends with ``base ** stop``:: + + >>> np.logspace(2, 3, num=5, base=2) + array([4. , 4.75682846, 5.65685425, 6.72717132, 8. ]) + +nD domains +========== + +nD domains can be partitioned into *grids*. This can be done using one of the +following functions. + +``meshgrid`` +------------ + +The purpose of ``numpy.meshgrid`` is to create a rectangular grid out of a set +of one-dimensional coordinate arrays. + +Given arrays + + :: + + >>> x = np.array([0, 1, 2, 3]) + >>> y = np.array([0, 1, 2, 3, 4, 5]) + +``meshgrid`` will create two coordinate arrays, which can be used to generate +the coordinate pairs determining this grid. + + :: + + >>> xx, yy = np.meshgrid(x, y) + >>> xx + array([[0, 1, 2, 3], + [0, 1, 2, 3], + [0, 1, 2, 3], + [0, 1, 2, 3], + [0, 1, 2, 3], + [0, 1, 2, 3]]) + >>> yy + array([[0, 0, 0, 0], + [1, 1, 1, 1], + [2, 2, 2, 2], + [3, 3, 3, 3], + [4, 4, 4, 4], + [5, 5, 5, 5]]) + + >>> import matplotlib.pyplot as plt + >>> plt.plot(xx, yy, marker='.', color='k', linestyle='none') + +.. plot:: user/plots/meshgrid_plot.py + :align: center + :include-source: 0 + +``mgrid`` +--------- + +``numpy.mgrid`` can be used as a shortcut for creating meshgrids. It is not a +function, but when indexed, returns a multidimensional meshgrid. + +:: + + >>> xx, yy = np.meshgrid(np.array([0, 1, 2, 3]), np.array([0, 1, 2, 3, 4, 5])) + >>> xx.T, yy.T + (array([[0, 0, 0, 0, 0, 0], + [1, 1, 1, 1, 1, 1], + [2, 2, 2, 2, 2, 2], + [3, 3, 3, 3, 3, 3]]), + array([[0, 1, 2, 3, 4, 5], + [0, 1, 2, 3, 4, 5], + [0, 1, 2, 3, 4, 5], + [0, 1, 2, 3, 4, 5]])) + + >>> np.mgrid[0:4, 0:6] + array([[[0, 0, 0, 0, 0, 0], + [1, 1, 1, 1, 1, 1], + [2, 2, 2, 2, 2, 2], + [3, 3, 3, 3, 3, 3]], + <BLANKLINE> + [[0, 1, 2, 3, 4, 5], + [0, 1, 2, 3, 4, 5], + [0, 1, 2, 3, 4, 5], + [0, 1, 2, 3, 4, 5]]]) + + +``ogrid`` +--------- + +Similar to ``numpy.mgrid``, ``numpy.ogrid`` returns an *open* multidimensional +meshgrid. This means that when it is indexed, only one dimension of each +returned array is greater than 1. This avoids repeating the data and thus saves +memory, which is often desirable. + +These sparse coordinate grids are intended to be use with :ref:`broadcasting`. +When all coordinates are used in an expression, broadcasting still leads to a +fully-dimensonal result array. + +:: + + >>> np.ogrid[0:4, 0:6] + [array([[0], + [1], + [2], + [3]]), array([[0, 1, 2, 3, 4, 5]])] + +All three methods described here can be used to evaluate function values on a +grid. + +:: + + >>> g = np.ogrid[0:4, 0:6] + >>> zg = np.sqrt(g[0]**2 + g[1]**2) + >>> g[0].shape, g[1].shape, zg.shape + ((4, 1), (1, 6), (4, 6)) + >>> m = np.mgrid[0:4, 0:6] + >>> zm = np.sqrt(m[0]**2 + m[1]**2) + >>> np.array_equal(zm, zg) + True 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 0582d82f2..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 @@ -15,3 +15,4 @@ the package, see the :ref:`API reference <reference>`. how-to-io how-to-index how-to-verify-bug + how-to-partition diff --git a/doc/source/user/plots/meshgrid_plot.py b/doc/source/user/plots/meshgrid_plot.py new file mode 100644 index 000000000..91032145a --- /dev/null +++ b/doc/source/user/plots/meshgrid_plot.py @@ -0,0 +1,7 @@ +import numpy as np +import matplotlib.pyplot as plt + +x = np.array([0, 1, 2, 3]) +y = np.array([0, 1, 2, 3, 4, 5]) +xx, yy = np.meshgrid(x, y) +plt.plot(xx, yy, marker='o', color='k', linestyle='none') 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> |
