diff --git a/doc/release/upcoming_changes/21468.new_feature.rst b/doc/release/upcoming_changes/21468.new_feature.rst index 64678b1c3b92..c37f057358fa 100644 --- a/doc/release/upcoming_changes/21468.new_feature.rst +++ b/doc/release/upcoming_changes/21468.new_feature.rst @@ -1,6 +1,6 @@ -New function `np.show_runtime` ------------------------------- +New function ``np.show_runtime`` +-------------------------------- -A new function `np.show_runtime` has been added to display the runtime -information of the machine in addition to `np.show_config` which displays +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/source/release/2.25.0-notes.rst b/doc/source/release/2.25.0-notes.rst new file mode 100644 index 000000000000..3ffb35264a09 --- /dev/null +++ b/doc/source/release/2.25.0-notes.rst @@ -0,0 +1,293 @@ +========================== +NumPy 2.25.0 Release Notes +========================== + + +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 `__) + +* Ragged array creation will now always raise a ``ValueError`` unless + ``dtype=object`` is passed. This includes very deeply nested sequences. + + (`gh-22004 `__) + + +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 `__) + +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 `__) + + +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 `__) + +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 `__) + +New function `numpy.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 `__) + +``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 `__) + +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 `__) + +``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 `__) + +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) + +(`gh-21976 `__) + + +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 `__) + +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 `__) + +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 dependend. For example:: + + arr = np.full(100, value=1000, dtype=np.float64) + arr.astype(np.int8) + +May give a result equivalent to (the intermediat means no warning is given):: + + arr.astype(np.int64).astype(np.int8) + +May may return an undefined result, with a warning set:: + + RuntimeWarning: invalid value encountered in cast + +The precise behavior if subject to the C99 standard and its implementation +in both software and hardware. + +(`gh-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 `__) + +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 `__) + + +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 `__) + +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 `__) diff --git a/numpy/lib/utils.py b/numpy/lib/utils.py index 479535dcc11d..52567aacce7b 100644 --- a/numpy/lib/utils.py +++ b/numpy/lib/utils.py @@ -29,10 +29,10 @@ def show_runtime(): Notes ----- - 1. Information is derived with the help of `threadpoolctl` - library. - 2. SIMD related information is derived from `__cpu_features__`, - `__cpu_baseline__` and `__cpu_dispatch__` + 1. Information is derived with the help of `threadpoolctl + `_ library. + 2. SIMD related information is derived from ``__cpu_features__``, + ``__cpu_baseline__`` and ``__cpu_dispatch__`` Examples --------