DOC: Add release notes for ufunc (and FASTCALL) refactor

2 files changed, 49 insertions, 0 deletions

diff --git a/doc/release/upcoming_changes/15271.compatibility.rst b/doc/release/upcoming_changes/15271.compatibility.rst
new file mode 100644
index 000000000..b37a98977
--- /dev/null
+++ b/doc/release/upcoming_changes/15271.compatibility.rst
@@ -0,0 +1,33 @@
+Error type changes in universal functions
+-----------------------------------------
+The universal functions may now raise different errors
+on invalid input in some cases.
+The main changes should be that a ``RuntimeError`` was
+replaced with a more fitting ``TypeError``.
+When multiple errors were present in the same call,
+NumPy may now raise a different one.
+
+
+``__array_ufunc__`` argument validation
+---------------------------------------
+NumPy will now partially validate arguments before calling
+``__array_ufunc__``.  Previously, it was possible to pass
+on invalid arguments (such as a non-existing keyword
+argument) when dispatch was known to occur.
+This was always the intended behaviour, if existing
+``__array_ufunc__`` users rely on certain keyword arguments
+to be passed on, it may be possible to make an exception.
+
+
+``__array_ufunc__`` and additional positional arguments
+-------------------------------------------------------
+Previously, all positionally passed arguments were used
+where used for ``__array_ufunc__``.  In the case of reduce,
+accumulate, and reduceat all arguments may be passed by
+position.  This means that when they were passed by
+position, they could previously have been asked to handle
+the ufunc call via ``__array_ufunc__``.
+Since this depended on the way the arguments were passed
+(by position or by keyword), NumPy will now only dispatch
+on the input and output array.
+For example, it will never dispatch on the ``where`` array.
diff --git a/doc/release/upcoming_changes/15271.performance.rst b/doc/release/upcoming_changes/15271.performance.rst
new file mode 100644
index 000000000..43502fb79
--- /dev/null
+++ b/doc/release/upcoming_changes/15271.performance.rst
@@ -0,0 +1,16 @@
+Reduced call overheads with keyword arguments
+---------------------------------------------
+In the following cases NumPy now has a much reduced call
+overhead:
+
+* The array creation functions ``np.asarray``,
+  ``np.asanyarray``, ``np.ascontiguousarray``, and
+  ``np.asfortranarray``.  These are now always as fast
+  as ``np.array`` itself.
+* Universal functions (partially limited to Python 3.8+).
+* Many NumPy array methods when keyword arguments are used.
+
+This can lead to large performance improvements for some
+function calls when working with small arrays.
+For functions improved here, the use of keyword arguments
+will only have a minimal performance impact.