The NumPy 1.25.0 release continues the ongoing work to improve the handling andpromotion of dtypes, increase the execution speed, and clarify thedocumentation. There has also been work to prepare for the future NumPy 2.0.0release, resulting in a large number of new and expired deprecation.Highlights are:
Support for MUSL, there are now MUSL wheels.
Support the Fujitsu C/C++ compiler.
Object arrays are now supported in einsum
Support for inplace matrix multiplication (
@=
).
We will be releasing a NumPy 1.26 when Python 3.12 comes out. That is neededbecause distutils has been dropped by Python 3.12 and we will be switching to usingmeson for future builds. The next mainline release will be NumPy 2.0.0. We planthat the 2.0 series will still support downstream projects built against earlierversions of NumPy.
The Python versions supported in this release are 3.9-3.11.
Deprecations#
np.core.MachAr
is deprecated. It is private API. In namesdefined innp.core
should generally be considered private.(gh-22638)
np.finfo(None)
is deprecated.(gh-23011)
np.round_
is deprecated. Use np.round instead.(gh-23302)
np.product
is deprecated. Use np.prod instead.(gh-23314)
np.cumproduct
is deprecated. Use np.cumprod instead.(gh-23314)
np.sometrue
is deprecated. Use np.any instead.(gh-23314)
np.alltrue
is deprecated. Use np.all instead.(gh-23314)
Only ndim-0 arrays are treated as scalars. NumPy used to treat all arrays ofsize 1 (e.g.,
np.array([3.14])
) as scalars. In the future, this will belimited to arrays of ndim 0 (e.g.,np.array(3.14)
). The followingexpressions will report a deprecation warning: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]
(gh-10615)
np.find_common_type
is deprecated.numpy.find_common_type is now deprecated and its use should be replacedwith either numpy.result_type or numpy.promote_types.Most users leave the secondscalar_types
argument tofind_common_type
as[]
in which casenp.result_type
andnp.promote_types
are bothfaster and more robust.When not usingscalar_types
the main difference is that the replacementintentionally converts non-native byte-order to native byte order.Further,find_common_type
returnsobject
dtype rather than failingpromotion. This leads to differences when the inputs are not all numeric.Importantly, this also happens for e.g. timedelta/datetime for which NumPypromotion rules are currently sometimes surprising.When the
scalar_types
argument is not[]
things are more complicated.In most cases, usingnp.result_type
and passing the Python values0
,0.0
, or0j
has the same result as usingint
,float
,orcomplex
in scalar_types.When
scalar_types
is constructed,np.result_type
is thecorrect replacement and it may be passed scalar values likenp.float32(0.0)
.Passing values other than 0, may lead to value-inspecting behavior(whichnp.find_common_type
never used and NEP 50 may change in the future).The main possible change in behavior in this case, is when the array typesare signed integers and scalar types are unsigned.If you are unsure about how to replace a use of
scalar_types
or whennon-numeric dtypes are likely, please do not hesitate to open a NumPy issueto ask for help.(gh-22539)
Expired deprecations#
np.core.machar
andnp.finfo.machar
have been removed.(gh-22638)
+arr
will now raise an error when the dtype is notnumeric (and positive is undefined).(gh-22998)
A sequence must now be passed into the stacking family of functions(
stack
,vstack
,hstack
,dstack
andcolumn_stack
).(gh-23019)
np.clip
now defaults to same-kind casting. Falling back tounsafe casting was deprecated in NumPy 1.17.(gh-23403)
np.clip
will now propagatenp.nan
values passed asmin
ormax
.Previously, a scalar NaN was usually ignored. This was deprecated in NumPy 1.17.(gh-23403)
The
np.dual
submodule has been removed.(gh-23480)
NumPy now always ignores sequence behavior for an array-like (definingone of the array protocols). (Deprecation started NumPy 1.20)
(gh-23660)
The niche
FutureWarning
when casting to a subarray dtype inastype
or the array creation functions such asasarray
is now finalized.The behavior is now always the same as if the subarray dtype waswrapped into a single field (which was the workaround, previously).(FutureWarning since NumPy 1.20)(gh-23666)
==
and!=
warnings have been finalized. The==
and!=
operators on arrays now always:See Also3. An Informal Introduction to PythonTop 100 Model-Based Development Using MATLAB Simulink Interview Questions - CS Electrical & ElectronicsNumPy 1.12.0 Release Notes — NumPy v2.0 ManualNumPy 1.24 Release Notes — NumPy v2.0 Manualraise errors that occur during comparisons such as when the arrayshave incompatible shapes (
np.array([1, 2]) == np.array([1, 2, 3])
).return an array of all
True
or allFalse
when values arefundamentally not comparable (e.g. have different dtypes). An exampleisnp.array(["a"]) == np.array([1])
.This mimics the Python behavior of returning
False
andTrue
when comparing incompatible types like"a" == 1
and"a" != 1
.For a long time these gaveDeprecationWarning
orFutureWarning
.
(gh-22707)
Nose support has been removed. NumPy switched to using pytest in 2018 and nosehas been unmaintained for many years. We have kept NumPy’s nose support toavoid breaking downstream projects who might have been using it and not yetswitched to pytest or some other testing framework. With the arrival ofPython 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
(gh-23041)
The
numpy.testing.utils
shim has been removed. Importing from thenumpy.testing.utils
shim has been deprecated since 2019, the shim has nowbeen removed. All imports should be made directly fromnumpy.testing
.(gh-23060)
The environment variable to disable dispatching has been removed.Support for the
NUMPY_EXPERIMENTAL_ARRAY_FUNCTION
environment variable hasbeen removed. This variable disabled dispatching with__array_function__
.(gh-23376)
Support for
y=
as an alias ofout=
has been removed.Thefix
,isposinf
andisneginf
functions allowed usingy=
as a(deprecated) alias forout=
. This is no longer supported.(gh-23376)
Compatibility notes#
The
busday_count
method now correctly handles cases where thebegindates
is later in timethan theenddates
. Previously, theenddates
was included, even though the documentation statesit is always excluded.(gh-23229)
When comparing datetimes and timedelta using
np.equal
ornp.not_equal
numpy previously allowed the comparison withcasting="unsafe"
.This operation now fails. Forcing the output dtype using thedtype
kwarg can make the operation succeed, but we do not recommend it.(gh-22707)
When loading data from a file handle using
np.load
,if the handle is at the end of file, as can happen when readingmultiple arrays by callingnp.load
repeatedly, numpy previouslyraisedValueError
ifallow_pickle=False
, andOSError
ifallow_pickle=True
. Now it raisesEOFError
instead, in both cases.(gh-23105)
np.pad
with mode=wrap
pads with strict multiples of original data#
Code based on earlier version of pad
that uses mode="wrap"
will returndifferent results when the padding size is larger than initial array.
np.pad
with mode=wrap
now always fills the space withstrict multiples of original data even if the padding size is larger than theinitial array.
(gh-22575)
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 ofcnp.intp_t
which is 32 bits on 32 bit systems and 64 bits on 64 bitsystems (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.)
(gh-22637)
Changed error message and type for bad axes
argument to ufunc
#
The error message and type when a wrong axes
value is passed toufunc(..., axes=[...])`
has changed. The message is now more indicative ofthe problem, and if the value is mismatched an AxisError
will be raised.A TypeError
will still be raised for invalid input types.
(gh-22675)
Array-likes that define __array_ufunc__
can now override ufuncs if used as where
#
If the where
keyword argument of a numpy.ufunc is a subclass ofnumpy.ndarray or is a duck type that definesnumpy.class.__array_ufunc__ it can override the behavior of the ufuncusing 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 thedefault implementation of the ufunc
or, for numpy.ndarraysubclasses before using super().__array_ufunc__
.
(gh-23240)
Compiling against the NumPy C API is now backwards compatible by default#
NumPy now defaults to exposing a backwards compatible subset of the C-API.This makes the use of oldest-supported-numpy
unnecessary.Libraries can override the default minimal version to be compatible withusing:
#define NPY_TARGET_VERSION NPY_1_22_API_VERSION
before including NumPy or by passing the equivalent -D
option to thecompiler.The NumPy 1.25 default is NPY_1_19_API_VERSION
. Because the NumPy 1.19C API was identical to the NumPy 1.16 one resulting programs will be compatiblewith NumPy 1.16 (from a C-API perspective).This default will be increased in future non-bugfix releases.You can still compile against an older NumPy version and run on a newer one.
For more details please see For downstream package authors.
(gh-23528)
New Features#
np.einsum
now accepts arrays with object
dtype#
The code path will call python operators on object dtype arrays, muchlike np.dot
and np.matmul
.
(gh-18053)
Add support for inplace matrix multiplication#
It is now possible to perform inplace matrix multiplicationvia the @=
operator.
>>> 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]]
(gh-21120)
Added NPY_ENABLE_CPU_FEATURES
environment variable#
Users may now choose to enable only a subset of the built CPU features atruntime by specifying the NPY_ENABLE_CPU_FEATURES environment variable.Note that these specified features must be outside the baseline, since thoseare always assumed. Errors will be raised if attempting to enable a featurethat is either not supported by your CPU, or that NumPy was not built with.
(gh-22137)
NumPy now has an np.exceptions
namespace#
NumPy now has a dedicated namespace making most exceptionsand warnings available. All of these remain available in themain namespace, although some may be moved slowly in the future.The main reason for this is to increase discoverability and addfuture exceptions.
(gh-22644)
np.linalg
functions return NamedTuples#
np.linalg
functions that return tuples now return namedtuples. Thesefunctions are eig()
, eigh()
, qr()
, slogdet()
, and svd()
.The return type is unchanged in instances where these functions returnnon-tuples with certain keyword arguments (like svd(compute_uv=False)
).
(gh-22786)
String functions in np.char
are compatible with NEP 42 custom dtypes#
Custom dtypes that represent unicode strings or byte strings can now bepassed to the string functions in np.char
.
(gh-22863)
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 withoutusing 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 featureis most useful when writing generic code dealing with string dtypeclasses.
(gh-22963)
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 OpenBLAScompatible GEMM functions. To enable SSL2, it need to edit site.cfg and buildwith Fujitsu compiler. See site.cfg.example.
(gh-22982)
Improvements#
NDArrayOperatorsMixin
specifies that it has no __slots__
#
The NDArrayOperatorsMixin
class now specifies that it contains no__slots__
, ensuring that subclasses can now make use of this feature inPython.
(gh-23113)
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 whenthe real part of the exponent is larger than zero.Previously, NaN was returned unless the imaginary part was strictlyzero. The return value is either 0+0j
or 0-0j
.
(gh-18535)
New DTypePromotionError
#
NumPy now has a new DTypePromotionError
which is used when twodtypes cannot be promoted to a common one, for example:
np.result_type("M8[s]", np.complex128)
raises this new exception.
(gh-22707)
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 helpcustomize the output.
(gh-22769)
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 aMaskedArray
with the input mask preserved.
Previously, a MaskedArray
without the mask was returned.
(gh-22776)
Corrected error handling for NumPy C-API in Cython#
Many NumPy C functions defined for use in Cython were lacking thecorrect error indicator like except -1
or except *
.These have now been added.
(gh-22997)
Ability to directly spawn random number generators#
numpy.random.Generator.spawn now allows to directly spawn newindependent child generators via the numpy.random.SeedSequence.spawnmechanism.numpy.random.BitGenerator.spawn does the same for the underlyingbit generator.
Additionally, numpy.random.BitGenerator.seed_seq now gives directaccess to the seed sequence used for initializing the bit generator.This allows for example:
seed = 0x2e09b90939db40c400f8f22dae617151rng = 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.
(gh-23195)
numpy.logspace
now supports a non-scalar base
argument#
The base
argument of numpy.logspace
can now be array-like if it isbroadcastable against the start
and stop
arguments.
(gh-23275)
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()
.
(gh-23322)
Explicitly show keys of .npz file in repr#
NpzFile
shows keys of loaded .npz file when printed.
>>> npzfile = np.load('arr.npz')>>> npzfileNpzFile 'arr.npz' with keys arr_0, arr_1, arr_2, arr_3, arr_4...
(gh-23357)
NumPy now exposes DType classes in np.dtypes
#
The new numpy.dtypes
module now exposes DType classes andwill contain future dtype related functionality.Most users should have no need to use these classes directly.
(gh-23358)
Drop dtype metadata before saving in .npy or .npz files#
Currently, a *.npy
file containing a table with a dtype withmetadata cannot be read back.Now, np.save and np.savez drop metadata before saving.
(gh-23371)
numpy.lib.recfunctions.structured_to_unstructured
returns views in more cases#
structured_to_unstructured
now returns a view, if the stride between thefields is constant. Prior, padding between the fields or a reversed fieldwould lead to a copy.This change only applies to ndarray
, memmap
and recarray
. For allother array subclasses, the behavior remains unchanged.
(gh-23652)
Signed and unsigned integers always compare correctly#
When uint64
and int64
are mixed in NumPy, NumPy typicallypromotes both to float64
. This behavior may be argued aboutbut is confusing for comparisons ==
, <=
, since the resultsreturned can be incorrect but the conversion is hidden since theresult is a boolean.NumPy will now return the correct results for these by avoidingthe cast to float.
(gh-23713)
Performance improvements and changes#
Faster np.argsort
on AVX-512 enabled processors#
32-bit and 64-bit quicksort algorithm for np.argsort gain up to 6x speed up onprocessors that support AVX-512 instruction set.
Thanks to Intel corporation for sponsoring thiswork.
(gh-23707)
Faster np.sort
on AVX-512 enabled processors#
Quicksort for 16-bit and 64-bit dtypes gain up to 15x and 9x speed up onprocessors that support AVX-512 instruction set.
Thanks to Intel corporation for sponsoring thiswork.
(gh-22315)
__array_function__
machinery is now much faster#
The overhead of the majority of functions in NumPy is now smallerespecially when keyword arguments are used. This change significantlyspeeds up many simple function calls.
(gh-23020)
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 aboveconditions, 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
, andfmin
.
The internal logic is similar to the logic used for regular ufuncs, which alsohave fast paths.
Thanks to the D. E. Shaw group for sponsoring thiswork.
(gh-23136)
Faster membership test on NpzFile
#
Membership test on NpzFile
will no longerdecompress the archive if it is successful.
(gh-23661)
Changes#
np.r_[]
and np.c_[]
with certain scalar values#
In rare cases, using mainly np.r_
with scalars can lead to differentresults. The main potential changes are highlighted by the following:
>>> np.r_[np.arange(5, dtype=np.uint8), -1].dtypeint16 # rather than the default integer (int64 or int32)>>> np.r_[np.arange(5, dtype=np.int8), 255]array([ 0, 1, 2, 3, 4, 255], dtype=int16)
Where the second example returned:
array([ 0, 1, 2, 3, 4, -1], dtype=int8)
The first one is due to a signed integer scalar with an unsigned integerarray, while the second is due to 255
not fitting into int8
andNumPy currently inspecting values to make this work.(Note that the second example is expected to change in the future due toNEP 50; it will then raise an error.)
(gh-22539)
Most NumPy functions are wrapped into a C-callable#
To speed up the __array_function__
dispatching, most NumPy functionsare now wrapped into C-callables and are not proper Python functions orC methods.They still look and feel the same as before (like a Python function), and thisshould only improve performance and user experience (cleaner tracebacks).However, please inform the NumPy developers if this change confuses yourprogram for some reason.
(gh-23020)
C++ standard library usage#
NumPy builds now depend on the C++ standard library, becausethe numpy.core._multiarray_umath
extension is linked withthe C++ linker.
(gh-23601)