Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR contains the following updates:
==1.26.4
->==2.1.0
Release Notes
numpy/numpy (numpy)
v2.1.0
Compare Source
v2.0.1
Compare Source
v2.0.0
Compare Source
NumPy 2.0.0 Release Notes
NumPy 2.0.0 is the first major release since 2006. It is the result of
11 months of development since the last feature release and is the work
of 212 contributors spread over 1078 pull requests. It contains a large
number of exciting new features as well as changes to both the Python
and C APIs.
This major release includes breaking changes that could not happen in a
regular minor (feature) release - including an ABI break, changes to
type promotion rules, and API changes which may not have been emitting
deprecation warnings in 1.26.x. Key documents related to how to adapt to
changes in NumPy 2.0, in addition to these release notes, include:
Highlights
Highlights of this release include:
numpy.dtypes.StringDType
and a newnumpy.strings
namespace with performant ufuncs for string operations,float32
andlongdouble
in allnumpy.fft
functions,numpy
namespace.
sort
,argsort
,partition
,argpartition
have beenaccelerated through the use of the Intel x86-simd-sort and
Google Highway libraries, and may see large (hardware-specific)
speedups,
significant performance improvements for linear algebra
operations on macOS, and wheels that are about 3 times smaller,
numpy.char
fixed-length string operations havebeen accelerated by implementing ufuncs that also support
numpy.dtypes.StringDType
in addition to thefixed-length string dtypes,
numpy.lib.introspect.opt_func_info
, to determinewhich hardware-specific kernels are available and will be
dispatched to.
numpy.save
now uses pickle protocol version 4 for savingarrays with object dtype, which allows for pickle objects larger
than 4GB and improves saving speed by about 5% for large arrays.
structure and each public function now available in a single place.
should make it easier to learn and use NumPy. The number of
objects in the main namespace decreased by ~10% and in
numpy.lib
by ~80%.Canonical dtype names and a new
numpy.isdtype` introspectionfunction,
internals hidden to ease future extensibility,
PyArray_ImportNumPyAPI
and
PyUFunc_ImportUFuncAPI
.This fixes many user surprises about promotions which previously often
depended on data values of input arrays rather than only their dtypes.
Please see the NEP and the numpy-2-migration-guide for details as this
change can lead to changes in output dtypes and lower precision results
for mixed-dtype operations.
int64
rather thanint32
, matching the behavior on other platforms,there is now documentation on NumPy's
module structure,
Furthermore there are many changes to NumPy internals, including
continuing to migrate code from C to C++, that will make it easier to
improve and maintain NumPy in the future.
The "no free lunch" theorem dictates that there is a price to pay for
all these API and behavior improvements and better future extensibility.
This price is:
Backwards compatibility. There are a significant number of breaking
changes to both the Python and C APIs. In the majority of cases,
there are clear error messages that will inform the user how to
adapt their code. However, there are also changes in behavior for
which it was not possible to give such an error message - these
cases are all covered in the Deprecation and Compatibility sections
below, and in the numpy-2-migration-guide.
Note that there is a
ruff
mode to auto-fix many things in Pythoncode.
Breaking changes to the NumPy ABI. As a result, binaries of packages
that use the NumPy C API and were built against a NumPy 1.xx release
will not work with NumPy 2.0. On import, such packages will see an
ImportError
with a message about binary incompatibility.It is possible to build binaries against NumPy 2.0 that will work at
runtime with both NumPy 2.0 and 1.x. See numpy-2-abi-handling for more
details.
All downstream packages that depend on the NumPy ABI are advised
to do a new release built against NumPy 2.0 and verify that that
release works with both 2.0 and 1.26 - ideally in the period between
2.0.0rc1 (which will be ABI-stable) and the final 2.0.0 release to
avoid problems for their users.
The Python versions supported by this release are 3.9-3.12.
NumPy 2.0 Python API removals
np.geterrobj
,np.seterrobj
and the related ufunc keywordargument
extobj=
have been removed. The preferred replacement forall of these is using the context manager
with np.errstate():
.(gh-23922)
np.cast
has been removed. The literal replacement fornp.cast[dtype](arg)
isnp.asarray(arg, dtype=dtype)
.np.source
has been removed. The preferred replacement isinspect.getsource
.np.lookfor
has been removed.(gh-24144)
numpy.who
has been removed. As an alternative for the removedfunctionality, one can use a variable explorer that is available in
IDEs such as Spyder or Jupyter Notebook.
(gh-24321)
Warnings and exceptions present in
numpy.exceptions
,e.g,
numpy.exceptions.ComplexWarning
,numpy.exceptions.VisibleDeprecationWarning
, are nolonger exposed in the main namespace.
Multiple niche enums, expired members and functions have been
removed from the main namespace, such as:
ERR_*
,SHIFT_*
,np.fastCopyAndTranspose
,np.kernel_version
,np.numarray
,np.oldnumeric
andnp.set_numeric_ops
.(gh-24316)
Replaced
from ... import *
in thenumpy/__init__.py
withexplicit imports. As a result, these main namespace members got
removed:
np.FLOATING_POINT_SUPPORT
,np.FPE_*
,np.NINF
,np.PINF
,np.NZERO
,np.PZERO
,np.CLIP
,np.WRAP
,np.WRAP
,np.RAISE
,np.BUFSIZE
,np.UFUNC_BUFSIZE_DEFAULT
,np.UFUNC_PYVALS_NAME
,np.ALLOW_THREADS
,np.MAXDIMS
,np.MAY_SHARE_EXACT
,np.MAY_SHARE_BOUNDS
,add_newdoc
,np.add_docstring
andnp.add_newdoc_ufunc
.(gh-24357)
Alias
np.float_
has been removed. Usenp.float64
instead.Alias
np.complex_
has been removed. Usenp.complex128
instead.Alias
np.longfloat
has been removed. Usenp.longdouble
instead.Alias
np.singlecomplex
has been removed. Usenp.complex64
instead.
Alias
np.cfloat
has been removed. Usenp.complex128
instead.Alias
np.longcomplex
has been removed. Usenp.clongdouble
instead.
Alias
np.clongfloat
has been removed. Usenp.clongdouble
instead.
Alias
np.string_
has been removed. Usenp.bytes_
instead.Alias
np.unicode_
has been removed. Usenp.str_
instead.Alias
np.Inf
has been removed. Usenp.inf
instead.Alias
np.Infinity
has been removed. Usenp.inf
instead.Alias
np.NaN
has been removed. Usenp.nan
instead.Alias
np.infty
has been removed. Usenp.inf
instead.Alias
np.mat
has been removed. Usenp.asmatrix
instead.np.issubclass_
has been removed. Use theissubclass
builtininstead.
np.asfarray
has been removed. Usenp.asarray
with a proper dtypeinstead.
np.set_string_function
has been removed. Usenp.set_printoptions
instead with a formatter for custom printing of NumPy objects.
np.tracemalloc_domain
is now only available fromnp.lib
.np.recfromcsv
andrecfromtxt
are now only available fromnp.lib.npyio
.np.issctype
,np.maximum_sctype
,np.obj2sctype
,np.sctype2char
,np.sctypes
,np.issubsctype
were all removedfrom the main namespace without replacement, as they where niche
members.
Deprecated
np.deprecate
andnp.deprecate_with_doc
has beenremoved from the main namespace. Use
DeprecationWarning
instead.Deprecated
np.safe_eval
has been removed from the main namespace.Use
ast.literal_eval
instead.(gh-24376)
np.find_common_type
has been removed. Usenumpy.promote_types
ornumpy.result_type
instead. To achieve semantics for thescalar_types
argument, usenumpy.result_type
and pass0
,0.0
, or0j
as a Python scalar instead.np.round_
has been removed. Usenp.round
instead.np.nbytes
has been removed. Usenp.dtype(<dtype>).itemsize
instead.
(gh-24477)
np.compare_chararrays
has been removed from the main namespace.Use
np.char.compare_chararrays
instead.The
charrarray
in the main namespace has been deprecated. It canbe imported without a deprecation warning from
np.char.chararray
for now, but we are planning to fully deprecate and remove
chararray
in the future.np.format_parser
has been removed from the main namespace. Usenp.rec.format_parser
instead.(gh-24587)
Support for seven data type string aliases has been removed from
np.dtype
:int0
,uint0
,void0
,object0
,str0
,bytes0
and
bool8
.(gh-24807)
The experimental
numpy.array_api
submodule has been removed. Usethe main
numpy
namespace for regular usage instead, or theseparate
array-api-strict
package for the compliance testing usecase for which
numpy.array_api
was mostly used.(gh-25911)
__array_prepare__
is removedUFuncs called
__array_prepare__
before running computations for normalufunc calls (not generalized ufuncs, reductions, etc.). The function was
also called instead of
__array_wrap__
on the results of some linearalgebra functions.
It is now removed. If you use it, migrate to
__array_ufunc__
or relyon
__array_wrap__
which is called with a context in all cases,although only after the result array is filled. In those code paths,
__array_wrap__
will now be passed a base class, rather than a subclassarray.
(gh-25105)
Deprecations
np.compat
has been deprecated, as Python 2 is no longer supported.numpy.int8
and similar classes will no longer support conversionof out of bounds python integers to integer arrays. For example,
conversion of 255 to int8 will not return -1.
numpy.iinfo(dtype)
can be used to check the machine limits for data types. For example,
np.iinfo(np.uint16)
returns min = 0 and max = 65535.np.array(value).astype(dtype)
will give the desired result.np.safe_eval
has been deprecated.ast.literal_eval
should beused instead.
(gh-23830)
np.recfromcsv
,np.recfromtxt
,np.disp
,np.get_array_wrap
,np.maximum_sctype
,np.deprecate
andnp.deprecate_with_doc
havebeen deprecated.
(gh-24154)
np.trapz
has been deprecated. Usenp.trapezoid
or ascipy.integrate
function instead.np.in1d
has been deprecated. Usenp.isin
instead.Alias
np.row_stack
has been deprecated. Usenp.vstack
directly.(gh-24445)
__array_wrap__
is now passedarr, context, return_scalar
andsupport for implementations not accepting all three are deprecated.
Its signature should be
__array_wrap__(self, arr, context=None, return_scalar=False)
(gh-25409)
Arrays of 2-dimensional vectors for
np.cross
have been deprecated.Use arrays of 3-dimensional vectors instead.
(gh-24818)
np.dtype("a")
alias fornp.dtype(np.bytes_)
was deprecated. Usenp.dtype("S")
alias instead.(gh-24854)
Use of keyword arguments
x
andy
with functionsassert_array_equal
andassert_array_almost_equal
has beendeprecated. Pass the first two arguments as positional arguments
instead.
(gh-24978)
numpy.fft
deprecations for n-D transforms with None values in argumentsUsing
fftn
,ifftn
,rfftn
,irfftn
,fft2
,ifft2
,rfft2
orirfft2
with thes
parameter set to a value that is notNone
andthe
axes
parameter set toNone
has been deprecated, in line with thearray API standard. To retain current behaviour, pass a sequence [0,
..., k-1] to
axes
for an array of dimension k.Furthermore, passing an array to
s
which containsNone
values isdeprecated as the parameter is documented to accept a sequence of
integers in both the NumPy docs and the array API specification. To use
the default behaviour of the corresponding 1-D transform, pass the value
matching the default for its
n
parameter. To use the default behaviourfor every axis, the
s
argument can be omitted.(gh-25495)
np.linalg.lstsq
now defaults to a newrcond
valuenumpy.linalg.lstsq
now uses the new rcond value of themachine precision times
max(M, N)
. Previously, the machine precisionwas used but a FutureWarning was given to notify that this change will
happen eventually. That old behavior can still be achieved by passing
rcond=-1
.(gh-25721)
Expired deprecations
The
np.core.umath_tests
submodule has been removed from the publicAPI. (Deprecated in NumPy 1.15)
(gh-23809)
The
PyDataMem_SetEventHook
deprecation has expired and it isremoved. Use
tracemalloc
and thenp.lib.tracemalloc_domain
domain. (Deprecated in NumPy 1.23)
(gh-23921)
The deprecation of
set_numeric_ops
and the C functionsPyArray_SetNumericOps
andPyArray_GetNumericOps
has been expiredand the functions removed. (Deprecated in NumPy 1.16)
(gh-23998)
The
fasttake
,fastclip
, andfastputmask
ArrFuncs
deprecationis now finalized.
The deprecated function
fastCopyAndTranspose
and its C counterpartare now removed.
The deprecation of
PyArray_ScalarFromObject
is now finalized.(gh-24312)
np.msort
has been removed. For a replacement,np.sort(a, axis=0)
should be used instead.
(gh-24494)
np.dtype(("f8", 1)
will now return a shape 1 subarray dtype ratherthan a non-subarray one.
(gh-25761)
Assigning to the
.data
attribute of an ndarray is disallowed andwill raise.
np.binary_repr(a, width)
will raise if width is too small.Using
NPY_CHAR
inPyArray_DescrFromType()
will raise, useNPY_STRING
NPY_UNICODE
, orNPY_VSTRING
instead.(gh-25794)
Compatibility notes
loadtxt
andgenfromtxt
default encoding changedloadtxt
andgenfromtxt
now both default toencoding=None
which maymainly modify how
converters
work. These will now be passedstr
rather than
bytes
. Pass the encoding explicitly to always get the newor old behavior. For
genfromtxt
the change also means that returnedvalues will now be unicode strings rather than bytes.
(gh-25158)
f2py
compatibility notesf2py
will no longer accept ambiguous-m
and.pyf
CLIcombinations. When more than one
.pyf
file is passed, an error israised. When both
-m
and a.pyf
is passed, a warning is emittedand the
-m
provided name is ignored.(gh-25181)
The
f2py.compile()
helper has been removed because it leakedmemory, has been marked as experimental for several years now, and
was implemented as a thin
subprocess.run
wrapper. It was also oneof the test bottlenecks. See
gh-25122 for the full
rationale. It also used several
np.distutils
features which aretoo fragile to be ported to work with
meson
.Users are urged to replace calls to
f2py.compile
with calls tosubprocess.run("python", "-m", "numpy.f2py",...
instead, and touse environment variables to interact with
meson
. Nativefiles are also an
option.
(gh-25193)
Minor changes in behavior of sorting functions
Due to algorithmic changes and use of SIMD code, sorting functions with
methods that aren't stable may return slightly different results in
2.0.0 compared to 1.26.x. This includes the default method of
numpy.argsort
andnumpy.argpartition
.Removed ambiguity when broadcasting in
np.solve
The broadcasting rules for
np.solve(a, b)
were ambiguous whenb
had1 fewer dimensions than
a
. This has been resolved in abackward-incompatible way and is now compliant with the Array API. The
old behaviour can be reconstructed by using
np.solve(a, b[..., None])[..., 0]
.(gh-25914)
Modified representation for
Polynomial
The representation method for
numpy.polynomial.polynomial.Polynomial
was updated toinclude the domain in the representation. The plain text and latex
representations are now consistent. For example the output of
str(np.polynomial.Polynomial([1, 1], domain=[.1, .2]))
used to be1.0 + 1.0 x
, but now is1.0 + 1.0 (-3.0000000000000004 + 20.0 x)
.(gh-21760)
C API changes
The
PyArray_CGT
,PyArray_CLT
,PyArray_CGE
,PyArray_CLE
,PyArray_CEQ
,PyArray_CNE
macros have been removed.PyArray_MIN
andPyArray_MAX
have been moved fromndarraytypes.h
tonpy_math.h
.(gh-24258)
A C API for working with
numpy.dtypes.StringDType
arrays has been exposed. This includes functions for acquiring and
releasing mutexes which lock access to the string data, as well as
packing and unpacking UTF-8 bytestreams from array entries.
NPY_NTYPES
has been renamed toNPY_NTYPES_LEGACY
as it does notinclude new NumPy built-in DTypes. In particular the new string
DType will likely not work correctly with code that handles legacy
DTypes.
(gh-25347)
The C-API now only exports the static inline function versions of
the array accessors (previously this depended on using "deprecated
API"). While we discourage it, the struct fields can still be used
directly.
(gh-25789)
NumPy now defines
PyArray_Pack
to set an individual memory address.Unlike
PyArray_SETITEM
this function is equivalent to setting anindividual array item and does not require a NumPy array input.
(gh-25954)
The
->f
slot has been removed fromPyArray_Descr
. If you use this slot,replace accessing it with
PyDataType_GetArrFuncs
(see its documentationand the
numpy-2-migration-guide
). In some cases using other functionslike
PyArray_GETITEM
may be an alternatives.PyArray_GETITEM
andPyArray_SETITEM
now require the import ofthe NumPy API table to be used and are no longer defined in
ndarraytypes.h
.(gh-25812)
Due to runtime dependencies, the definition for functionality
accessing the dtype flags was moved from
numpy/ndarraytypes.h
andis only available after including
numpy/ndarrayobject.h
as itrequires
import_array()
. This includesPyDataType_FLAGCHK
,PyDataType_REFCHK
andNPY_BEGIN_THREADS_DESCR
.The dtype flags on
PyArray_Descr
must now be accessed through thePyDataType_FLAGS
inline function to be compatible with both 1.xand 2.x. This function is defined in
npy_2_compat.h
to allowbackporting. Most or all users should use
PyDataType_FLAGCHK
whichis available on 1.x and does not require backporting. Cython users
should use Cython 3. Otherwise access will go through Python unless
they use
PyDataType_FLAGCHK
instead.(gh-25816)
Datetime functionality exposed in the C API and Cython bindings
The functions
NpyDatetime_ConvertDatetime64ToDatetimeStruct
,NpyDatetime_ConvertDatetimeStructToDatetime64
,NpyDatetime_ConvertPyDateTimeToDatetimeStruct
,NpyDatetime_GetDatetimeISO8601StrLen
,NpyDatetime_MakeISO8601Datetime
, andNpyDatetime_ParseISO8601Datetime
have been added to the C API tofacilitate converting between strings, Python datetimes, and NumPy
datetimes in external libraries.
(gh-21199)
Const correctness for the generalized ufunc C API
The NumPy C API's functions for constructing generalized ufuncs
(
PyUFunc_FromFuncAndData
,PyUFunc_FromFuncAndDataAndSignature
,PyUFunc_FromFuncAndDataAndSignatureAndIdentity
) taketypes
anddata
arguments that are not modified by NumPy's internals. Like thename
anddoc
arguments, third-party Python extension modules arelikely to supply these arguments from static constants. The
types
anddata
arguments are now const-correct: they are declared asconst char *types
andvoid *const *data
, respectively. C code shouldnot be affected, but C++ code may be.
(gh-23847)
Larger
NPY_MAXDIMS
andNPY_MAXARGS
,NPY_RAVEL_AXIS
introducedNPY_MAXDIMS
is now 64, you may want to review its use. This is usuallyused in a stack allocation, where the increase should be safe. However,
we do encourage generally to remove any use of
NPY_MAXDIMS
andNPY_MAXARGS
to eventually allow removing the constraint completely.For the conversion helper and C-API functions mirroring Python ones such as
take
,NPY_MAXDIMS
was used to meanaxis=None
. Such usage must be replacedwith
NPY_RAVEL_AXIS
. See alsomigration_maxdims
.(gh-25149)
NPY_MAXARGS
not constant andPyArrayMultiIterObject
size changeSince
NPY_MAXARGS
was increased, it is now a runtime constant and notcompile-time constant anymore. We expect almost no users to notice this.
But if used for stack allocations it now must be replaced with a custom
constant using
NPY_MAXARGS
as an additional runtime check.The
sizeof(PyArrayMultiIterObject)
no longer includes the full size ofthe object. We expect nobody to notice this change. It was necessary to
avoid issues with Cython.
(gh-25271)
Required changes for custom legacy user dtypes
In order to improve our DTypes it is unfortunately necessary to break
the ABI, which requires some changes for dtypes registered with
PyArray_RegisterDataType
. Please see the documentation ofPyArray_RegisterDataType
for how to adapt your code and achievecompatibility with both 1.x and 2.x.
(gh-25792)
New Public DType API
The C implementation of the NEP 42 DType API is now public. While the
DType API has shipped in NumPy for a few versions, it was only usable in
sessions with a special environment variable set. It is now possible to
write custom DTypes outside of NumPy using the new DType API and the
normal
import_array()
mechanism for importing the numpy C API.See
dtype-api
for more details about the API. As always with a new feature,please report any bugs you run into implementing or using a new DType. It is
likely that downstream C code that works with dtypes will need to be updated to
work correctly with new DTypes.
(gh-25754)
New C-API import functions
We have now added
PyArray_ImportNumPyAPI
andPyUFunc_ImportUFuncAPI
as static inline functions to import the NumPy C-API tables. The new
functions have two advantages over
import_array
andimport_ufunc
:light-weight if not, allowing to add them judiciously (although this
is not preferable in most cases).
a
return
statement.The
PyArray_ImportNumPyAPI()
function is included innpy_2_compat.h
for simpler backporting.
(gh-25866)
Structured dtype information access through functions
The dtype structures fields
c_metadata
,names
,fields
, andsubarray
must now be accessed through new functions following the samenames, such as
PyDataType_NAMES
. Direct access of the fields is notvalid as they do not exist for all
PyArray_Descr
instances. Themetadata
field is kept, but the macro version should also bepreferred.
(gh-25802)
Descriptor
elsize
andalignment
accessUnless compiling only with NumPy 2 support, the
elsize
andaligment
fields must now be accessed via
PyDataType_ELSIZE
,PyDataType_SET_ELSIZE
, andPyDataType_ALIGNMENT
. In cases where thedescriptor is attached to an array, we advise using
PyArray_ITEMSIZE
as it exists on all NumPy versions. Please see
migration_c_descr
for more information.(gh-25943)
NumPy 2.0 C API removals
npy_interrupt.h
and the corresponding macros likeNPY_SIGINT_ON
have been removed. We recommend querying
PyErr_CheckSignals()
orPyOS_InterruptOccurred()
periodically (these do currently requireholding the GIL though).
The
noprefix.h
header has been removed. Replace missing symbolswith their prefixed counterparts (usually an added
NPY_
ornpy_
).(gh-23919)
PyUFunc_GetPyVals
,PyUFunc_handlefperr
, andPyUFunc_checkfperr
have been removed. If needed, a new backwards compatible function to
raise floating point errors could be restored. Reason for removal:
there are no known users and the functions would have made
with np.errstate()
fixes much more difficult).(gh-23922)
The
numpy/old_defines.h
which was part of the API deprecated sinceNumPy 1.7 has been removed. This removes macros of the form
PyArray_CONSTANT
. Thereplace_old_macros.sed
script may be useful to convert them to the
NPY_CONSTANT
version.(gh-24011)
The
legacy_inner_loop_selector
member of the ufunc struct isremoved to simplify improvements to the dispatching system. There
are no known users overriding or directly accessing this member.
(gh-24271)
NPY_INTPLTR
has been removed to avoid confusion (seeintp
redefinition).
(gh-24888)
The advanced indexing
MapIter
and related API has been removed.The (truly) public part of it was not well tested and had only one
known user (Theano). Making it private will simplify improvements to
speed up
ufunc.at
, make advanced indexing more maintainable, andwas important for increasing the maximum number of dimensions of
arrays to 64. Please let us know if this API is important to you so
we can find a solution together.
(gh-25138)
The
NPY_MAX_ELSIZE
macro has been removed, as it only everreflected builtin numeric types and served no internal purpose.
(gh-25149)
PyArray_REFCNT
andNPY_REFCOUNT
are removed. UsePy_REFCNT
instead.
(gh-25156)
PyArrayFlags_Type
andPyArray_NewFlagsObject
as well asPyArrayFlagsObject
are private now. There is no known use-case;use the Python API if needed.
PyArray_MoveInto
,PyArray_CastTo
,PyArray_CastAnyTo
areremoved use
PyArray_CopyInto
and if absolutely neededPyArray_CopyAnyInto
(the latter does a flat copy).PyArray_FillObjectArray
is removed, its only true use was forimplementing
np.empty
. Create a new empty array or usePyArray_FillWithScalar()
(decrefs existing objects).PyArray_CompareUCS4
andPyArray_CompareString
are removed. Usethe standard C string comparison functions.
PyArray_ISPYTHON
is removed as it is misleading, has no knownuse-cases, and is easy to replace.
PyArray_FieldNames
is removed, as it is unclear what it would beuseful for. It also has incorrect semantics in some possible
use-cases.
PyArray_TypestrConvert
is removed, since it seems a misnomer andunlikely to be used by anyone. If you know the size or are limited
to few types, just use it explicitly, otherwise go via Python
strings.
(gh-25292)
PyDataType_GetDatetimeMetaData
is removed, it did not actually doanything since at least NumPy 1.7.
(gh-25802)
PyArray_GetCastFunc
is removed. Note that custom legacy userdtypes can still provide a castfunc as their implementation, but any
access to them is now removed. The reason for this is that NumPy
never used these internally for many years. If you use simple
numeric types, please just use C casts directly. In case you require
an alternative, please let us know so we can create new API such as
PyArray_CastBuffer()
which could use old or new cast functionsdepending on the NumPy version.
(gh-25161)
New Features
np.add
was extended to work withunicode
andbytes
dtypes.A new
bitwise_count
functionThis new function counts the number of 1-bits in a number.
numpy.bitwise_count
works on all the numpy integer typesand integer-like objects.
(gh-19355)
macOS Accelerate support, including the ILP64
Support for the updated Accelerate BLAS/LAPACK library, including ILP64
(64-bit integer) support, in macOS 13.3 has been added. This brings
arm64 support, and significant performance improvements of up to 10x for
commonly used linear algebra operations. When Accelerate is selected at
build time, or if no explicit BLAS library selection is done, the 13.3+
version will automatically be used if available.
(gh-24053)
Binary wheels are also available. On macOS >=14.0, users who install
NumPy from PyPI will get wheels built against Accelerate rather than
OpenBLAS.
(gh-25255)
Option to use weights for quantile and percentile functions
A
weights
keyword is now available fornumpy.quantile
,numpy.percentile
,numpy.nanquantile
andnumpy.nanpercentile
. Onlymethod="inverted_cdf"
supports weights.
(gh-24254)
Improved CPU optimization tracking
A new tracer mechanism is available which enables tracking of the
enabled targets for each optimized function (i.e., that uses
hardware-specific SIMD instructions) in the NumPy library. With this
enhancement, it becomes possible to precisely monitor the enabled CPU
dispatch targets for the dispatched functions.
A new function named
opt_func_info
has been added to the new namespacenumpy.lib.introspect
, offering this tracing capability. This function allowsyou to retrieve information about the enabled targets based on function names
and data type signatures.
(gh-24420)
A new Meson backend for
f2py
f2py
in compile mode (i.e.f2py -c
) now accepts the--backend meson
option. This is the default option for Python >=3.12.For older Python versions,
f2py
will still default to--backend distutils
.To support this in realistic use-cases, in compile mode
f2py
takes a--dep
flag one or many times which maps todependency()
calls in themeson
backend, and does nothing in thedistutils
backend.There are no changes for users of
f2py
only as a code generator, i.e.without
-c
.(gh-24532)
bind(c)
support forf2py
Both functions and subroutines can be annotated with
bind(c)
.f2py
will handle both the correct type mapping, and preserve the unique label
for other C interfaces.
Note:
bind(c, name = 'routine_name_other_than_fortran_routine')
isnot honored by the
f2py
bindings by design, sincebind(c)
with thename
is meant to guarantee only the same name in C and Fortran, not inPython and Fortran.
(gh-24555)
A new
strict
option for several testing functionsThe
strict
keyword is now available fornumpy.testing.assert_allclose
,numpy.testing.assert_equal
, andnumpy.testing.assert_array_less
. Settingstrict=True
will disable the broadcasting behaviour for scalars and ensurethat input arrays have the same data type.
(gh-24680,
gh-24770,
gh-24775)
Add
np.core.umath.find
andnp.core.umath.rfind
UFuncsAdd two
find
andrfind
UFuncs that operate on unicode or bytestrings and are used in
np.char
. They operate similar tostr.find
and
str.rfind
.(gh-24868)
diagonal
andtrace
fornumpy.linalg
numpy.linalg.diagonal
andnumpy.linalg.trace
have been added, which arearray API standard-compatible variants of
numpy.diagonal
andnumpy.trace
.They differ in the default axis selection which define 2-D sub-arrays.
(gh-24887)
New
long
andulong
dtypesnumpy.long
andnumpy.ulong
have been added as NumPy integers mapping toC's
long
andunsigned long
. Prior to NumPy 1.24,numpy.long
was an aliasto Python's
int
.(gh-24922)
svdvals
fornumpy.linalg
numpy.linalg.svdvals
has been added. It computes singular values for (a stackof) matrices. Executing
np.svdvals(x)
is the same as callingnp.svd(x, compute_uv=False, hermitian=False)
. This function is compatible with the arrayAPI standard.
(gh-24940)
A new
isdtype
functionnumpy.isdtype
was added to provide a canonical way to classify NumPy'sdtypes in compliance with the array API standard.
(gh-25054)
A new
astype
functionnumpy.astype
was added to provide an array API standard-compatiblealternative to the
numpy.ndarray.astype
method.(gh-25079)
Array API compatible functions' aliases
13 aliases for existing functions were added to improve compatibility
with the array API standard:
acos
,acosh
,asin
,asinh
,atan
,atanh
,atan2
.bitwise_left_shift
,bitwise_invert
,bitwise_right_shift
.concat
,permute_dims
,pow
.numpy.linalg
:tensordot
,matmul
.(gh-25086)
New
unique_*
functionsThe
numpy.unique_all
,numpy.unique_counts
,numpy.unique_inverse
, andnumpy.unique_values
functions have been added. They provide functionality ofnumpy.unique
with different sets of flags. They are array APIstandard-compatible, and because the number of arrays they return does not
depend on the values of input arguments, they are easier to target for JIT
compilation.
(gh-25088)
Matrix transpose support for ndarrays
NumPy now offers support for calculating the matrix transpose of an
array (or stack of arrays). The matrix transpose is equivalent to
swapping the last two axes of an array. Both
np.ndarray
andnp.ma.MaskedArray
now expose a.mT
attribute, and there is amatching new
numpy.matrix_transpose
function.(gh-23762)
Array API compatible functions for
numpy.linalg
Six new functions and two aliases were added to improve compatibility
with the Array API standard for `numpy.linalg`:
numpy.linalg.matrix_norm
- Computes the matrix norm ofa matrix (or a stack of matrices).
numpy.linalg.vector_norm
- Computes the vector norm ofa vector (or batch of vectors).
numpy.vecdot
- Computes the (vector) dot product oftwo arrays.
numpy.linalg.vecdot
- An alias fornumpy.vecdot
.numpy.linalg.matrix_transpose
- An alias fornumpy.matrix_transpose
.(gh-25155)
numpy.linalg.outer
has been added. It computes theouter product of two vectors. It differs from
numpy.outer
by accepting one-dimensional arrays only.This function is compatible with the array API standard.
(gh-25101)
numpy.linalg.cross
has been added. It computes thecross product of two (arrays of) 3-dimensional vectors. It differs
from
numpy.cross
by accepting three-dimensionalvectors only. This function is compatible with the array API
standard.
(gh-25145)
A
correction
argument forvar
andstd
A
correction
argument was added tonumpy.var
andnumpy.std
, which is anarray API standard compatible alternative to
ddof
. As both arguments serve asimilar purpose, only one of them can be provided at the same time.
(gh-25169)
ndarray.device
andndarray.to_device
An
ndarray.device
attribute andndarray.to_device
method were addedto
numpy.ndarray
for array API standard compatibility.Additionally,
device
keyword-only arguments were added to:numpy.asarray
,numpy.arange
,numpy.empty
,numpy.empty_like
,numpy.eye
,numpy.full
,numpy.full_like
,numpy.linspace
,numpy.ones
,numpy.ones_like
,numpy.zeros
, andnumpy.zeros_like
.For all these new arguments, only
device="cpu"
is supported.(gh-25233)
StringDType has been added to NumPy
We have added a new variable-width UTF-8 encoded string data type, implementing
a "NumPy array of Python strings", including support for a user-provided
missing data sentinel. It is intended as a drop-in replacement for arrays of
Python strings and missing data sentinels using the object dtype. See
NEP 55 and the documentation
of stringdtype for more details.
(gh-25347)
New keywords for
cholesky
andpinv
The
upper
andrtol
keywords were added tonumpy.linalg.cholesky
andnumpy.linalg.pinv
,respectively, to improve array API standard compatibility.
For
numpy.linalg.pinv
, if neitherrcond
norrtol
isspecified, the
rcond
's default is used. We plan to deprecate andremove
rcond
in the future.(gh-25388)
New keywords for
sort
,argsort
andlinalg.matrix_rank
New keyword parameters were added to improve array API standard
compatibility:
rtol
was added tonumpy.linalg.matrix_rank
.stable
was added tonumpy.sort
andnumpy.argsort
.(gh-25437)
New
numpy.strings
namespace for string ufuncsNumPy now implements some string operations as ufuncs. The old
np.char
namespace is still available, and where possible the string manipulation
functions in that namespace have been updated to use the new ufuncs,
substantially improving their performance.
Where possible, we suggest updating code to use functions in
np.strings
instead ofnp.char
. In the future we may deprecatenp.char
in favor ofnp.strings
.(gh-25463)
numpy.fft
support for different precisions and in-place calculationsThe various FFT routines in
numpy.fft
now do theircalculations natively in float, double, or long double precision,
depending on the input precision, instead of always calculating in
double precision. Hence, the calculation will now be less precise for
single and more precise for long double precision. The data type of the
output array will now be adjusted accordingly.
Furthermore, all FFT routines have gained an
out
argument that can beused for in-place calculations.
(gh-25536)
configtool and pkg-config support
A new
numpy-config
CLI script is available that can be queried for theNumPy version and for compile flags needed to use the NumPy C API. This
will allow build systems to better support the use of NumPy as a
dependency. Also, a
numpy.pc
pkg-config file is now included withNumpy. In order to find its location for use with
PKG_CONFIG_PATH
, usenumpy-config --pkgconfigdir
.(gh-25730)
Array API standard support in the main namespace
The main
numpy
namespace now supports the array API standard. Seearray-api-standard-compatibility
fordetails.
(gh-25911)
Improvements
Strings are now supported by
any
,all
, and the logical ufuncs.Integer sequences as the shape argument for
memmap
numpy.memmap
can now be created with any integer sequenceas the
shape
argument, such as a list or numpy array of integers.Previously, only the types of tuple and int could be used without
raising an error.
(gh-23729)
errstate
is now faster and context safeThe
numpy.errstate
context manager/decorator is now fasterand safer. Previously, it was not context safe and had (rare) issues
with thread-safety.
(gh-23936)
AArch64 quicksort speed improved by using Highway's VQSort
The first introduction of the Google Highway library, using VQSort on
AArch64. Execution time is improved by up to 16x in some cases, see the
PR for benchmark results. Extensions to other platforms will be done in
the future.
(gh-24018)
Complex types - underlying C type changes
The underlying C types for all of NumPy's complex types have been
changed to use C99 complex types.
While this change does not affect the memory layout of complex
types, it changes the API to be used to directly retrieve or write
the real or complex part of the complex number, since direct field
access (as in
c.real
orc.imag
) is no longer an option. You cannow use utilities provided in
numpy/npy_math.h
to do theseoperations, like this:
To ease cross-version compatibility, equivalent macros and a
compatibility layer have been added which can be used by downstream
packages to continue to support both NumPy 1.x and 2.x. See
complex-numbers
for more info.numpy/npy_common.h
now includescomplex.h
, which means thatcomplex
is now a reserved keyword.(gh-24085)
iso_c_binding
support and improved common blocks forf2py
Previously, users would have to define their own custom
f2cmap
file touse type mappings defined by the Fortran2003
iso_c_binding
intrinsicmodule. These type maps are now natively supported by
f2py
(gh-24555)
f2py
now handlescommon
blocks which havekind
specifications frommodules. This further expands the usability of intrinsics like
iso_fortran_env
andiso_c_binding
.(gh-25186)
Call
str
automatically on third argument to functions likeassert_equal
The third argument to functions like
numpy.testing.assert_equal
now hasstr
called on itautomatically. This way it mimics the built-in
assert
statement, whereassert_equal(a, b, obj)
works likeassert a == b, obj
.(gh-24877)
Support for array-like
atol
/rtol
inisclose
,allclose
The keywords
atol
andrtol
innumpy.isclose
andnumpy.allclose
now accept both scalars and arrays. Anarray, if given, must broadcast to the shapes of the first two array
arguments.
(gh-24878)
Consistent failure messages in test functions
Previously, some
numpy.testing
assertions printed messagesthat referred to the actual and desired results as
x
andy
. Now,these values are consistently referred to as
ACTUAL
andDESIRED
.(gh-24931)
n-D FFT transforms allow
s[i] == -1
The
numpy.fft.fftn
,numpy.fft.ifftn
,numpy.fft.rfftn
,numpy.fft.irfftn
,numpy.fft.fft2
,numpy.fft.ifft2
,numpy.fft.rfft2
andnumpy.fft.irfft2
functions now use the whole input array along the axis
i
ifs[i] == -1
, in line with the array API standard.(gh-25495)
Guard PyArrayScalar_VAL and PyUnicodeScalarObject for the limited API
PyUnicodeScalarObject
holds aPyUnicodeObject
, which is notavailable when using
Py_LIMITED_API
. Add guards to hide it andconsequently also make the
PyArrayScalar_VAL
macro hidden.(gh-25531)
Changes
np.gradient()
now returns a tuple rather than a list making thereturn value immutable.
(gh-23861)
Being fully context and thread-safe,
np.errstate
can only beentered once now.
np.setbufsize
is now tied tonp.errstate()
: leaving annp.errstate
context will also reset thebufsize
.(gh-23936)
A new public
np.lib.array_utils
submodule has been introduced andit currently contains three functions:
byte_bounds
(moved fromnp.lib.utils
),normalize_axis_tuple
andnormalize_axis_index
.(gh-24540)
Introduce
numpy.bool
as the new canonical name forNumPy's boolean dtype, and make
numpy.bool\_
an aliasto it. Note that until NumPy 1.24,
np.bool
was an alias toPython's builtin
bool
. The new name helps with array API standardcompatibility and is a more intuitive name.
(gh-25080)
The
dtype.flags
value was previously stored as a signed integer.This means that the aligned dtype struct flag lead to negative flags
being set (-128 rather than 128). This flag is now stored unsigned
(positive). Code which checks flags manually may need to adapt. This
may include code compiled with Cython 0.29.x.
(gh-25816)
Representation of NumPy scalars changed
As per NEP 51, the scalar representation has been updated to include the type
information to avoid confusion with Python scalars.
Scalars are now printed as
np.float64(3.0)
rather than just3.0
.This may disrupt workflows that store representations of numbers (e.g.,
to files) making it harder to read them. They should be stored as
explicit strings, for example by using
str()
orf"{scalar!s}"
. Forthe time being, affected users can use
np.set_printoptions(legacy="1.25")
to get the old behavior (withpossibly a few exceptions). Documentation of downstream projects may
require larger updates, if code snippets are tested. We are working on
tooling for
doctest-plus
to facilitate updates.
(gh-22449)
Truthiness of NumPy strings changed
NumPy strings previously were inconsistent about how they defined if the
string is
True
orFalse
and the definition did not match the oneused by Python. Strings are now considered
True
when they arenon-empty and
False
when they are empty. This changes the followingdistinct cases:
string_array.astype(np.int64).astype(bool)
, meaning that onlyvalid integers could be cast. Now a string of
"0"
will beconsidered
True
since it is not empty. If you need the oldbehavior, you may use the above step (casting to integer first) or
string_array == "0"
(if the input is only ever0
or1
). To getthe new result on old NumPy versions use
string_array != ""
.np.nonzero(string_array)
previously ignored whitespace so that astring only containing whitespace was considered
False
. Whitespaceis now considered
True
.This change does not affect
np.loadtxt
,np.fromstring
, ornp.genfromtxt
. The first two still use the integer definition, whilegenfromtxt
continues to match for"true"
(ignoring case). However,if
np.bool_
is used as a converter the result will change.The change does affect
np.fromregex
as it uses direct assignments.(gh-23871)
A
mean
keyword was added to var and std functionOften when the standard deviation is needed the mean is also needed. The
same holds for the variance and the mean. Until now the mean is then
calculated twice, the change introduced here for the
numpy.var
andnumpy.std
functions allows for passing in a precalculated mean as an keywordargument. See the docstrings for details and an example illustrating the
speed-up.
(gh-24126)
Remove datetime64 deprecation warning when constructing with timezone
The
numpy.datetime64
method now issues a UserWarning rather than aDeprecationWarning whenever a timezone is included in the datetime string that
is provided.
(gh-24193)
Default integer dtype is now 64-bit on 64-bit Windows
The default NumPy integer is now 64-bit on all 64-bit systems as the
historic 32-bit default on Windows was a common source of issues. Most
users should not notice this. The main issues may occur with code
interfacing with libraries written in a compiled language like C. For
more information see
migration_windows_int64
.(gh-24224)
Renamed
numpy.core
tonumpy._core
Accessing
numpy.core
now emits a DeprecationWarning. In practice wehave found that most downstream usage of
numpy.core
was to accessfunctionality that is available in the main
numpy
namespace. If forsome reason you are using functionality in
numpy.core
that is notavailable in the main
numpy
namespace, this means you are likely usingprivate NumPy internals. You can still access these internals via
numpy._core
without a deprecation warning but we do not provide anybackward compatibility guarantees for NumPy internals. Please open an
issue if you think a mistake was made and something needs to be made
public.
(gh-24634)
The "relaxed strides" debug build option, which was previously enabled
through the
NPY_RELAXED_STRIDES_DEBUG
environment variable or the-Drelaxed-strides-debug
config-settings flag has been removed.(gh-24717)
Redefinition of
np.intp
/np.uintp
(almost never a change)Due to the actual use of these types almost always matching the use of
size_t
/Py_ssize_t
this is now the definition in C. Previously, itmatched
intptr_t
anduintptr_t
which would often have been subtlyincorrect. This has no effect on the vast majority of machines since the
size of these types only differ on extremely niche platforms.
However, it means that:
intp
typed array anymore.The
p
andP
character codes can still be used, however.intptr_t
oruintptr_t
typed arrays in C remainspossible in a cross-platform way via
PyArray_DescrFromType('p')
.nN
were introduced.npy_intp
typed arguments.(gh-24888)
numpy.fft.helper
made privatenumpy.fft.helper
was renamed tonumpy.fft._helper
to indicate thatit is a private submodule. All public functions exported by it should be
accessed from
numpy.fft
.(gh-24945)
numpy.linalg.linalg
made privatenumpy.linalg.linalg
was renamed tonumpy.linalg._linalg
to indicatethat it is a private submodule. All public functions exported by it
should be accessed from
numpy.linalg
.(gh-24946)
Out-of-bound axis not the same as
axis=None
In some cases
axis=32
or for concatenate any large value was the sameas
axis=None
. Except forconcatenate
this was deprecate. Any out ofbound axis value will now error, make sure to use
axis=None
.(gh-25149)
New
copy
keyword meaning forarray
andasarray
constructorsNow
numpy.array
andnumpy.asarray
supportthree values for
copy
parameter:None
- A copy will only be made if it is necessary.True
- Always make a copy.False
- Never make a copy. If a copy is required aValueError
israised.
The meaning of
False
changed as it now raises an exception if a copyis needed.
(gh-25168)
The
__array__
special method now takes acopy
keyword argument.NumPy will pass
copy
to the__array__
special method in situationswhere it would be set to a non-default value (e.g. in a call to
np.asarray(some_object, copy=False)
). Currently, if an unexpectedkeyword argument error is raised after this, NumPy will print a warning
and re-try without the
copy
keyword argument. Implementations ofobjects implementing the
__array__
protocol should accept acopy
keyword argument with the same meaning as when passed to
numpy.array
ornumpy.asarray
.([gh-251
Configuration
📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR was generated by Mend Renovate. View the repository job log.