NumPy 1.24 發行說明#

NumPy 1.24.0 版本持續進行中的工作，旨在改進 dtype 的處理和提升、提高執行速度，並釐清文件。由於提升和清理方面的變更，也有大量新的和過期的棄用。這可能被稱為棄用版本。重點包括

  • 許多新的棄用，請查看它們。

  • 許多過期的棄用，

  • 新的 F2PY 功能和修正。

  • 堆疊函數的新「dtype」和「casting」關鍵字。

詳細資訊請見下方，

此版本支援 Python 版本 3.8-3.11。

棄用#

棄用 fastCopyAndTranspose 和 PyArray_CopyAndTranspose#

numpy.fastCopyAndTranspose 函數已被棄用。請直接使用對應的 copy 和 transpose 方法

arr.T.copy()

底層 C 函數 PyArray_CopyAndTranspose 也已從 NumPy C-API 中棄用。

(gh-22313)

超出範圍的 Python 整數的轉換#

嘗試從 Python 整數轉換為 NumPy 值現在將始終檢查結果是否可以由 NumPy 表示。這表示以下範例在未來將會失敗，並且現在會給出 DeprecationWarning

np.uint8(-1)
np.array([3000], dtype=np.int8)

其中許多之前都成功了。此類程式碼主要用於帶有負值的無號整數，例如 np.uint8(-1) 給出 np.iinfo(np.uint8).max。

請注意，NumPy 整數之間的轉換不受影響，因此 np.array(-1).astype(np.uint8) 繼續運作並使用 C 整數溢位邏輯。對於負值，檢視陣列也有效：np.array(-1, dtype=np.int8).view(np.uint8)。在某些情況下，使用 np.iinfo(np.uint8).max 或 val % 2**8 也可能運作良好。

在極少數情況下，輸入資料可能會混合負值和非常大的無號值（即 -1 和 2**63）。在這種情況下，不幸的是必須在 Python 值上使用 %，或根據是否預期負值來使用帶號或無號轉換。

(gh-22385)

棄用 msort#

numpy.msort 函數已被棄用。請改用 np.sort(a, axis=0)。

(gh-22456)

np.str0 和類似的現在已被棄用#

以 0 位元大小結尾的純量型別別名：np.object0、np.str0、np.bytes0、np.void0、np.int0、np.uint0 以及 np.bool8 現在已被棄用，最終將會移除。

(gh-22607)

過期的棄用#

  • normed 關鍵字引數已從 np.histogram、np.histogram2d 和 np.histogramdd 中移除。請改用 density。如果 normed 是按位置傳遞的，則現在使用 density。

    (gh-21645)

  • 不規則陣列建立現在將始終引發 ValueError，除非傳遞 dtype=object。這包括非常深層巢狀的序列。

    (gh-22004)

  • 已移除對 Visual Studio 2015 及更早版本的支援。

  • 已移除對 Windows Interix POSIX 互通層的支援。

    (gh-22139)

  • 已移除對 Cygwin < 3.3 的支援。

    (gh-22159)

  • 已移除 np.ma.MaskedArray 的 mini() 方法。請使用 np.ma.MaskedArray.min() 或 np.ma.minimum.reduce()。

  • 已移除 np.ma.minimum 和 np.ma.maximum 的單一引數形式。請改用 np.ma.minimum.reduce() 或 np.ma.maximum.reduce()。

    (gh-22228)

  • 將非標準（主要是原生位元組順序）的 dtype 實例傳遞給 ufuncs 中的 dtype= 或 signature= 現在將引發 TypeError。我們建議傳遞字串 "int8" 或純量型別 np.int8，因為位元組順序、datetime/timedelta 單位等永遠不會強制執行。（最初在 NumPy 1.21 中棄用。）

    (gh-22540)

  • 現在已正確套用比較 ufuncs 的 dtype= 引數。這表示只有 bool 和 object 是有效值，並且強制執行 dtype=object。

    (gh-22541)

  • 別名 np.object、np.bool、np.float、np.complex、np.str 和 np.int 的棄用已過期（在 NumPy 1.20 中引入）。其中一些現在將給出 FutureWarning，並且會引發錯誤，因為它們將在未來對應到 NumPy 純量。

    (gh-22607)

相容性注意事項#

array.fill(scalar) 的行為可能略有不同#

由於邏輯與項目指派對齊，numpy.ndarray.fill 在某些情況下現在行為可能略有不同

arr = np.array([1])  # with any dtype/value
arr.fill(scalar)
# is now identical to:
arr[0] = scalar

先前，當使用無法在目標 dtype 中表示的值，或當目標具有 object dtype 時，轉換可能會產生略有不同的答案。

(gh-20924)

子陣列到物件的轉換現在會複製#

將包含子陣列的 dtype 轉換為物件現在將確保子陣列的副本。先前傳回了不安全的檢視

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)

現在始終為 false。雖然先前對於特定轉換為 true。

(gh-21925)

傳回的陣列尊重 dtype kwarg 物件的唯一性#

當 dtype 關鍵字引數與 array 或 asarray 一起使用時，傳回陣列的 dtype 現在始終完全符合呼叫者提供的 dtype。

在某些情況下，此變更表示傳回的是檢視而不是輸入陣列。以下是在 64 位元 Linux 上的一個範例，其中 long 和 longlong 具有相同的精度，但 dtypes 不同

>>> arr = np.array([1, 2, 3], dtype="long")
>>> new_dtype = np.dtype("longlong")
>>> new = np.asarray(arr, dtype=new_dtype)
>>> new.dtype is new_dtype
True
>>> new is arr
False

在變更之前，dtype 不符，因為 new is arr 為 True。

(gh-21995)

DLPack 匯出引發 BufferError#

當陣列緩衝區無法透過 DLPack 匯出時，現在始終會引發 BufferError，而先前會引發 TypeError 或 RuntimeError。這允許在首先嘗試 DLPack 時，回退到緩衝區協定或 __array_interface__。

(gh-22542)

NumPy 建置不再在 GCC-6 上測試#

Ubuntu 18.04 已棄用 GitHub 動作，且 Ubuntu 20.04 上不提供 GCC-6，因此不再測試使用該編譯器的建置。我們仍然測試使用 GCC-7 和 GCC-8 的建置。

(gh-22598)

新功能#

新的屬性 symbol 已新增至多項式類別#

numpy.polynomial 套件中的多項式類別有一個新的 symbol 屬性，用於表示多項式的不定元。這可用於在列印時變更變數的值

>>> P_y = np.polynomial.Polynomial([1, 0, -1], symbol="y")
>>> print(P_y)
1.0 + 0.0·y¹ - 1.0·y²

請注意，多項式類別僅支援 1D 多項式，因此當結果為多元時，不允許涉及具有不同符號的多項式的運算

>>> 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

符號可以是任何有效的 Python 識別符。預設值為 symbol=x，與現有行為一致。

(gh-16154)

F2PY 支援 Fortran character 字串#

F2PY 現在支援封裝具有以下項目的 Fortran 函數

  • character (例如 character x)

  • character 陣列 (例如 character, dimension(n) :: x)

  • character 字串 (例如 character(len=10) x)

  • 和 character 字串陣列 (例如 character(len=10), dimension(n, m) :: x)

引數，包括將 Python Unicode 字串作為 Fortran character 字串引數傳遞。

(gh-19388)

新函數 np.show_runtime#

已新增一個新函數 numpy.show_runtime，除了顯示建置相關資訊的 numpy.show_config 之外，還顯示機器的執行時間資訊。

(gh-21468)

testing.assert_array_equal 的 strict 選項#

testing.assert_array_equal 現在提供 strict 選項。設定 strict=True 將停用純量的廣播行為，並確保輸入陣列具有相同的資料型別。

(gh-21595)

新增至 np.unique 的新參數 equal_nan#

np.unique 在 1.21 中變更為將所有 NaN 值視為相等，並傳回單個 NaN。設定 equal_nan=False 將還原 1.21 之前的行為，將 NaN 視為唯一值。預設值為 True。

(gh-21623)

numpy.stack 的 casting 和 dtype 關鍵字引數#

現在 numpy.stack 提供 casting 和 dtype 關鍵字引數。若要使用它們，請寫入 np.stack(..., dtype=None, casting='same_kind')。

numpy.vstack 的 casting 和 dtype 關鍵字引數#

現在 numpy.vstack 提供 casting 和 dtype 關鍵字引數。若要使用它們，請寫入 np.vstack(..., dtype=None, casting='same_kind')。

numpy.hstack 的 casting 和 dtype 關鍵字引數#

現在 numpy.hstack 提供 casting 和 dtype 關鍵字引數。若要使用它們，請寫入 np.hstack(..., dtype=None, casting='same_kind')。

(gh-21627)

可以變更單例 RandomState 底層的位元產生器#

在啟動時，numpy.random 模組中公開的單例 RandomState 實例會使用 MT19937 位元產生器初始化。新的函數 set_bit_generator 允許將預設位元產生器替換為使用者提供的位元產生器。引入此函數是為了提供一種方法，允許在新程式碼中無縫整合高品質、現代的位元產生器，並與使用單例提供的隨機變數產生函數的現有程式碼整合。配套函數 get_bit_generator 傳回單例 RandomState 目前使用的位元產生器。提供此函數是為了簡化在需要時還原原始隨機來源。

產生可重現的隨機數的首選方法是在 Generator 實例中使用現代位元產生器。default_rng 函數簡化了實例化

>>> rg = np.random.default_rng(3728973198)
>>> rg.random()

然後可以與單例實例共用相同的位元產生器，以便呼叫 random 模組中的函數將使用相同的位元產生器

>>> orig_bit_gen = np.random.get_bit_generator()
>>> np.random.set_bit_generator(rg.bit_generator)
>>> np.random.normal()

交換是永久性的（直到反轉），因此任何對 random 模組中的函數的呼叫都將使用新的位元產生器。如果需要程式碼正確執行，可以還原原始產生器

>>> np.random.set_bit_generator(orig_bit_gen)

(gh-21976)

np.void 現在具有 dtype 引數#

NumPy 現在允許透過將 dtype 引數傳遞給 np.void 來直接建構結構化的 void 純量。

(gh-22316)

改進#

F2PY 改進#

  • 產生的擴充模組不再使用已棄用的 NumPy-C API

  • 改進的 f2py 產生的例外訊息

  • 大量的錯誤和 flake8 警告修正

  • 可以在簽名檔案的 C 運算式中使用的各種 CPP 巨集都加上了 f2py_ 前綴。例如，應該使用 f2py_len(x) 而不是 len(x)

  • 引入了一個新的建構 character(f2py_len=...)，以支援從包裝函式傳回假定長度的 character 字串（例如 character(len=*)）

引入了一個勾點，以支援在讀取所有輸入檔案後重寫 f2py 內部資料結構。例如，SciPy 支援的 BC 需要此功能，其中 character 引數在 C 運算式中被視為 character 字串引數。

(gh-19388)

IBM zSystems 向量擴充功能設施 (SIMD)#

透過通用內建函數介面，新增了對 zSystem（z13、z14、z15）SIMD 擴充功能的支援。此支援提高了使用通用內建函數實作的所有 SIMD 核心的效能，包括以下運算：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 現在在轉換中給出浮點錯誤#

在大多數情況下，NumPy 先前在轉換期間發生浮點錯誤時，不會給出浮點警告或錯誤。例如，像這樣的轉換

np.array([2e300]).astype(np.float32)  # overflow for float32
np.array([np.inf]).astype(np.int64)

現在通常應該給出浮點警告。這些警告應該警告發生了浮點溢位。對於將浮點值轉換為整數時發生的錯誤，使用者應該預期會出現無效值警告。

使用者可以使用 np.errstate 修改這些警告的行為。

請注意，對於浮點數到整數的轉換，給出的確切警告可能與平台相關。例如

arr = np.full(100, fill_value=1000, dtype=np.float64)
arr.astype(np.int8)

可能會給出等效於以下的結果（中間轉換表示未給出警告）

arr.astype(np.int64).astype(np.int8)

可能會傳回未定義的結果，並設定警告

RuntimeWarning: invalid value encountered in cast

精確的行為受 C99 標準及其在軟體和硬體中的實作的約束。

(gh-21437)

F2PY 支援 value 屬性#

Fortran 標準要求使用 value 屬性宣告的變數必須按值而不是按參照傳遞。F2PY 現在正確支援此使用模式。因此，Fortran 程式碼中的 integer, intent(in), value :: x 將產生正確的包裝函式。

(gh-21807)

為第三方 BitGenerator 新增 pickle 支援#

位元產生器的 pickle 格式已擴充，允許每個位元產生器在 pickle 期間提供自己的建構函式。先前版本的 NumPy 僅支援 unpickling 使用 NumPy 隨附的核心位元產生器集之一建立的 Generator 實例。嘗試 unpickle 使用第三方位元產生器的 Generator 將會失敗，因為 unpickling 期間使用的建構函式僅知道 NumPy 中包含的位元產生器。

(gh-22014)

arange() 現在明確地在使用 dtype=str 時失敗#

先前，np.arange(n, dtype=str) 函數對於 n=1 和 n=2 運作正常，但對於 n 的其他值，會引發非特定的例外訊息。現在，它會引發 TypeError，告知 arange 不支援字串 dtype

>>> np.arange(2, dtype=str)
Traceback (most recent call last)
   ...
TypeError: arange() not supported for inputs with DType <class 'numpy.dtype[str_]'>.

(gh-22055)

numpy.typing 協定現在可進行執行時間檢查#

numpy.typing.ArrayLike 和 numpy.typing.DTypeLike 中使用的協定現在已正確標記為可進行執行時間檢查，使其更易於用於執行時間型別檢查器。

(gh-22357)

效能改進和變更#

適用於整數陣列的更快版本的 np.isin 和 np.in1d#

np.in1d（由 np.isin 使用）現在可以在傳遞兩個整數陣列時切換到更快的演算法（速度最高可快 10 倍以上）。這通常會自動使用，但您可以使用 kind="sort" 或 kind="table" 來強制使用舊方法或新方法。

(gh-12065)

更快的比較運算子#

比較函數（numpy.equal、numpy.not_equal、numpy.less、numpy.less_equal、numpy.greater 和 numpy.greater_equal）現在更快了，因為它們現在使用通用內建函數進行向量化。對於具有 SIMD 擴充功能 AVX512BW 的 CPU，整數、浮點數和布林資料型別的效能增益分別高達 2.57 倍、1.65 倍和 19.15 倍（N=50000）。

(gh-21483)

變更#

更好地報告整數除法溢位#

純量和陣列的整數除法溢位過去會提供 RuntimeWarning，且傳回值未定義，偶爾會導致崩潰

>>> np.array([np.iinfo(np.int32).min]*10, dtype=np.int32) // np.int32(-1)
<stdin>:1: RuntimeWarning: divide by zero encountered in floor_divide
array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0], dtype=int32)

整數除法溢位現在傳回輸入 dtype 的最小值，並引發以下 RuntimeWarning

>>> np.array([np.iinfo(np.int32).min]*10, dtype=np.int32) // np.int32(-1)
<stdin>:1: RuntimeWarning: overflow encountered in floor_divide
array([-2147483648, -2147483648, -2147483648, -2147483648, -2147483648,
       -2147483648, -2147483648, -2147483648, -2147483648, -2147483648],
      dtype=int32)

(gh-21506)

masked_invalid 現在就地修改遮罩#

當與 copy=False 一起使用時，numpy.ma.masked_invalid 現在就地修改輸入的遮罩陣列。這使其行為與 masked_where 完全相同，並更好地符合文件。

(gh-22046)

nditer/NpyIter 允許分配所有運算元#

透過 Python 中的 np.nditer 和 C 中的 NpyIter 提供的 NumPy 迭代器現在支援分配所有陣列。在這種情況下，迭代器形狀預設為 ()。必須提供運算元 dtype，因為無法從其他輸入推斷「通用 dtype」。

(gh-22457)