8000 DOC: Add documentation for maxdim increase (and related) changes · numpy/numpy@3026cd9 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3026cd9

Browse files
sebergseberg
committed
DOC: Add documentation for maxdim increase (and related) changes
1 parent f2340cc commit 3026cd9

File tree

4 files changed

+66
-6
lines changed

4 files changed

+66
-6
lines changed

‎doc/release/upcoming_changes/25149.c_api.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Lager ``NPY_MAXDIMS`` and ``NPY_MAXARGS``, ``NPY_RAVEL_AXIS`` introduced
2+
------------------------------------------------------------------------
3+
4+
``NPY_MAXDIMS`` is now 64, you may want to review its use. This is usually
5+
used in stack allocation, where the increase should be safe.
6+
However, we do encourage generally to remove any use of ``NPY_MAXDIMS`` and
7+
``NPY_MAXARGS`` to eventually allow removing the constraint completely.
8+
In some cases, ``NPY_MAXDIMS`` was passed (and returned) to mean ``axis=None``
9+
these must be replaced with ``NPY_RAVEL_AXIS``.
10+
See also :ref:`migration_maxdims`.

‎doc/release/upcoming_changes/25149.change.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Out-of-bound axis not the same as ``axis=None``
2+
-----------------------------------------------
3+
In some cases ``axis=32`` or for concatenate any large value
4+
was the same as ``axis=None``.
5+
Except for ``concatenate`` this was deprecate.
6+
Any out of bound axis value will now error, make sure to use
7+
``axis=None``.
8+

‎doc/source/numpy_2_0_migration_guide.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,30 @@ Some are defined in ``numpy/_core/include/numpy/npy_2_compat.h``
4141
(for example ``NPY_DEFAULT_INT``) which can be vendored in full or part
4242
to have the definitions available when compiling against NumPy 1.x.
4343

44+
If necessary, ``PyArray_RUNTIME_VERSION >= NPY_2_0_API_VERSION`` can be
45+
used to explicitly implement different behavior on NumPy 1.x and 2.0.
46+
(The compat header defines it in a way compatible with such use.)
47+
4448
Please let us know if you require additional workarounds here.
4549

50+
.. _migration_maxdims:
51+
52+
Increased maximum number of dimensions
53+
--------------------------------------
54+
The maximum number of dimensions (and arguments) was increased to 64, this
55+
affects the ``NPY_MAXDIMS`` and ``NPY_MAXARGS`` macros.
56+
It may be good to review their use, and we generally encourage you to
57+
not use this macros (especially ``NPY_MAXARGS``), so that a future version of
58+
NumPy can remove this limitation on the number of dimensions.
59+
60+
``NPY_MAXDIMS`` was also used to signal ``axis=None`` in the C-API, including
61+
the ``PyArray_AxisConverter``.
62+
If you run into this problem, you will see ``-2147483648``
63+
(the minimum integer value) or ``64`` being used as an invalid axis.
64+
Wherever you do, you must replace ``NPY_MAXDIMS`` with ``NPY_RAVEL_AXIS``.
65+
This is defined in the ``npy_2_compat.h`` header and runtime dependent.
66+
67+
4668
Namespace changes
4769
=================
4870

‎doc/source/reference/c-api/array.rst

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1949,7 +1949,7 @@ Calculation
19491949
19501950
.. tip::
19511951
1952-
Pass in :c:data:`NPY_MAXDIMS` for axis in order to achieve the same
1952+
Pass in :c:data:`NPY_RAVEL_AXIS` for axis in order to achieve the same
19531953
effect that is obtained by passing in ``axis=None`` in Python
19541954
(treating the array as a 1-d array).
19551955
@@ -2968,7 +2968,7 @@ to.
29682968
Convert a Python object, *obj*, representing an axis argument to
29692969
the proper value for passing to the functions that take an integer
29702970
axis. Specifically, if *obj* is None, *axis* is set to
2971-
:c:data:`NPY_MAXDIMS` which is interpreted correctly by the C-API
2971+
:c:data:`NPY_RAVEL_AXIS` which is interpreted correctly by the C-API
29722972
functions that take axis arguments.
29732973
29742974
.. c:function:: int PyArray_BoolConverter(PyObject* obj, npy_bool* value)
@@ -3411,14 +3411,26 @@ Other constants
34113411
34123412
.. c:macro:: NPY_MAXDIMS
34133413
3414+
The maximum number of dimensions that may be used by NumPy.
3415+
This is set to 64 and was 32 before NumPy 2.
3416+
34143417
.. note::
3415-
NumPy used to have a maximum number of dimensions set to 32 and now 64.
3416-
This was/is mostly useful for stack allocations. We now ask you to
3417-
define (and test) such a limit in your own project if needed.
3418+
We encourage you to avoid ``NPY_MAXDIMS``. A future version of NumPy
3419+
may wish to remove any dimension limitation (and thus the constant).
3420+
The limitation was created mainly a simplification for the liberal use
3421+
of small stack allocations as scratch space.
3422+
3423+
If your algorithm has a reasonable maximum number of dimension you
3424+
could check and use that locally.
34183425
34193426
.. c:macro:: NPY_MAXARGS
34203427
3421-
The maximum number of array arguments that can be used in functions.
3428+
The maximum number of array arguments that can be used in in some
3429+
functions. This used to be 32 before NumPy 2 and is now 64.
3430+
3431+
.. note::
3432+
You should never use this. We may remove it in future versions of
3433+
NumPy.
34223434
34233435
.. c:macro:: NPY_FALSE
34243436
@@ -3438,6 +3450,14 @@ Other constants
34383450
The return value of successful converter functions which are called
34393451
using the "O&" syntax in :c:func:`PyArg_ParseTuple`-like functions.
34403452
3453+
.. c:macro:: NPY_RAVEL_AXIS
3454+
3455+
Some NumPy functions (mainly the C-entrypoints for Python functions)
3456+
have an ``axis`` argument. This macro may be passed for ``axis=None``.
3457+
3458+
.. note::
3459+
This macro is a NumPy version dependent at runtime.
3460+
34413461
34423462
Miscellaneous Macros
34433463
~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)
0