通用函數 (ufunc)

另請參閱

通用函數 (ufunc) 基礎

通用函數（或簡稱 ufunc）是一種函數，它以元素對元素的方式對 ndarrays 進行操作，並支援 陣列廣播、類型轉換 和其他幾個標準功能。也就是說，ufunc 是「向量化」包裝函式，用於接受固定數量的特定輸入並產生固定數量的特定輸出的函數。有關通用函數的詳細資訊，請參閱通用函數 (ufunc) 基礎。

ufunc

numpy.ufunc()

對整個陣列逐元素運算的函數。

選用性關鍵字參數

所有 ufunc 都接受選用性關鍵字參數。其中大多數代表進階用法，通常不會使用。

out

第一個輸出可以作為位置參數或關鍵字參數提供。「out」關鍵字引數與位置引數不相容。

「out」關鍵字引數預期為元組，每個輸出一個條目（對於要由 ufunc 配置的陣列，可以為 None）。對於具有單個輸出的 ufunc，傳遞單個陣列（而不是包含單個陣列的元組）也有效。

在具有多個輸出的 ufunc 的「out」關鍵字引數中傳遞單個陣列已被棄用，並將在 numpy 1.10 中引發警告，並在未來版本中引發錯誤。

如果「out」為 None（預設值），則會建立未初始化的傳回陣列。然後，在廣播「where」為 True 的位置，輸出陣列會填入 ufunc 的結果。如果「where」是純量 True（預設值），則這對應於填滿整個輸出。請注意，未明確填滿的輸出會保留其未初始化的值。

ufunc 輸入和輸出運算元具有記憶體重疊的運算，其定義與沒有記憶體重疊的等效運算相同。受影響的運算會根據需要建立暫時副本，以消除資料依賴性。由於偵測這些情況在計算上很昂貴，因此使用了一種啟發式方法，在極少數情況下可能會導致不必要的暫時副本。對於資料依賴性足夠簡單，啟發式方法可以分析的運算，即使陣列重疊，也不會建立暫時副本（如果可以推斷出副本不是必要的）。例如，np.add(a, b, out=a) 將不涉及副本。

where

接受一個布林陣列，該陣列與運算元一起廣播。True 值表示在該位置計算 ufunc，False 值表示將輸出中的值保持不變。此引數不能用於廣義 ufunc，因為這些 ufunc 採用非純量輸入。

請注意，如果建立未初始化的傳回陣列，False 值將使這些值保持未初始化狀態。

axes

軸索引元組的列表，廣義 ufunc 應在其上運算。例如，對於適用於矩陣乘法的 (i,j),(j,k)->(i,k) 簽名，基本元素是二維矩陣，並且這些矩陣被認為儲存在每個引數的最後兩個軸中。對應的 axes 關鍵字將是 [(-2, -1), (-2, -1), (-2, -1)]。為了簡單起見，對於在 1 維陣列（向量）上運算的廣義 ufunc，接受單個整數而不是單元素元組，而對於所有輸出都是純量的廣義 ufunc，可以省略輸出元組。

axis

廣義 ufunc 應在其上運算的單個軸。這是對在單個共用核心維度上運算的 ufunc 的快捷方式，相當於為每個單核心維度引數傳遞 axes，條目為 (axis,)，而對所有其他引數傳遞 ()。例如，對於簽名 (i),(i)->()，它相當於傳遞 axes=[(axis,), (axis,), ()]。

keepdims

如果將其設定為 True，則縮減的軸將保留在結果中，作為大小為一的維度，以便結果將針對輸入正確廣播。此選項只能用於在所有具有相同核心維度數量的輸入上運算，且輸出沒有核心維度的廣義 ufunc，即具有類似 (i),(i)->() 或 (m,m)->() 的簽名。如果使用，則可以使用 axes 和 axis 控制輸出中維度的位置。

casting

可能是 ‘no’、‘equiv’、‘safe’、‘same_kind’ 或 ‘unsafe’。有關參數值的說明，請參閱 can_cast。

提供允許哪種類型轉換的策略。為了與以前版本的 NumPy 相容，對於 numpy < 1.7，預設值為 ‘unsafe’。在 numpy 1.7 中，開始過渡到 ‘same_kind’，其中 ufunc 對於在 ‘unsafe’ 規則下允許但在 ‘same_kind’ 規則下不允許的呼叫產生 DeprecationWarning。從 numpy 1.10 開始，預設值為 ‘same_kind’。

order

指定輸出陣列的計算迭代順序/記憶體佈局。預設值為 ‘K’。‘C’ 表示輸出應為 C 相鄰，‘F’ 表示 F 相鄰，‘A’ 表示如果輸入為 F 相鄰且不也為 C 相鄰，則為 F 相鄰，否則為 C 相鄰，而 ‘K’ 表示盡可能符合輸入的元素順序。

dtype

以與簽名相同的方式覆寫輸出陣列的 DType。這應確保計算的精確度相符。選擇的確切計算 DType 可能取決於 ufunc，並且輸入可能會轉換為此 DType 以執行計算。

subok

預設為 true。如果設定為 false，則輸出將始終是嚴格陣列，而不是子類型。

signature

Dtype、DType 元組或特殊簽名字串，指示 ufunc 的輸入和輸出類型。

此引數允許使用者指定用於計算的確切 DType。將根據需要使用類型轉換。除非陣列的 signature 為 None，否則不會考慮輸入陣列的實際 DType。

當所有 DType 都是固定的時，將選擇特定的迴圈，如果不存在相符的迴圈，則會引發錯誤。如果某些 DType 未指定且保留為 None，則行為可能取決於 ufunc。此時，ufunc 的 types 屬性提供了可用簽名的列表。（此列表可能缺少 NumPy 未定義的 DType。）

signature 僅指定 DType 類別/類型。例如，它可以指定運算應為 datetime64 或 float64 運算。它不指定 datetime64 時間單位或 float64 位元組順序。

為了向後相容性，此引數也可以作為 sig 提供，但建議使用長格式。請注意，這不應與廣義 ufunc 簽名 混淆，後者儲存在 ufunc 物件的 signature 屬性中。

屬性

通用函數具有一些資訊性屬性。任何屬性都不能設定。

__doc__	每個 ufunc 的文件字串。文件字串的第一部分是根據輸出數量、名稱和輸入數量動態產生的。文件字串的第二部分是在建立時提供的，並與 ufunc 一起儲存。
__name__	ufunc 的名稱。

ufunc.nin	輸入的數量。
ufunc.nout	輸出的數量。
ufunc.nargs	引數的數量。
ufunc.ntypes	類型的數量。
ufunc.types	傳回類型列表，這些類型按輸入->輸出分組。
ufunc.identity	識別值。
ufunc.signature	廣義 ufunc 運算的核心元素定義。

方法

ufunc.reduce(array[, axis, dtype, out, ...])	透過沿一個軸套用 ufunc，將 array 的維度縮減一維。
ufunc.accumulate(array[, axis, dtype, out])	累計將運算子套用到所有元素的結果。
ufunc.reduceat(array, indices[, axis, ...])	使用指定的切片在單個軸上執行（局部）縮減。
ufunc.outer(A, B, /, **kwargs)	將 ufunc op 套用於 A 中的 a 和 B 中的 b 的所有配對 (a, b)。
ufunc.at(a, indices[, b])	對運算元 'a' 執行非緩衝就地運算，用於由 'indices' 指定的元素。

警告

在資料類型範圍「太小」而無法處理結果的陣列上進行類似縮減的運算會靜默包裝。應使用 dtype 來增加執行縮減的資料類型的大小。

可用的 ufunc

目前在 numpy 中定義了 60 多個通用函數，涵蓋一個或多個類型，涵蓋各種運算。當使用相關的中綴表示法時（例如，當寫入 a + b 且 a 或 b 是 ndarray 時，會在內部呼叫 add(a, b)），會自動在陣列上呼叫其中一些 ufunc。儘管如此，您可能仍然希望使用 ufunc 呼叫，以便使用選用性輸出引數將輸出放置在您選擇的物件中。

請記住，每個 ufunc 都逐元素運算。因此，每個純量 ufunc 都將被描述為作用於一組純量輸入以傳回一組純量輸出。

注意

即使您使用選用性輸出引數，ufunc 仍然會傳回其輸出。

數學運算

add(x1, x2, /[, out, where, casting, order, ...])	逐元素相加引數。
subtract(x1, x2, /[, out, where, casting, ...])	逐元素相減引數。
multiply(x1, x2, /[, out, where, casting, ...])	逐元素相乘引數。
matmul(x1, x2, /[, out, casting, order, ...])	兩個陣列的矩陣乘積。
divide(x1, x2, /[, out, where, casting, ...])	逐元素相除引數。
logaddexp(x1, x2, /[, out, where, casting, ...])	輸入的指數和的對數。
logaddexp2(x1, x2, /[, out, where, casting, ...])	輸入的指數和的以 2 為底的對數。
true_divide(x1, x2, /[, out, where, ...])	逐元素相除引數。
floor_divide(x1, x2, /[, out, where, ...])	傳回小於或等於輸入除法的最大整數。
negative(x, /[, out, where, casting, order, ...])	數值負數，逐元素。
positive(x, /[, out, where, casting, order, ...])	數值正數，逐元素。
power(x1, x2, /[, out, where, casting, ...])	第一個陣列元素從第二個陣列逐元素取冪。
float_power(x1, x2, /[, out, where, ...])	第一個陣列元素從第二個陣列逐元素取冪。
remainder(x1, x2, /[, out, where, casting, ...])	傳回逐元素除法餘數。
mod(x1, x2, /[, out, where, casting, order, ...])	傳回逐元素除法餘數。
fmod(x1, x2, /[, out, where, casting, ...])	傳回逐元素除法餘數。
divmod(x1, x2[, out1, out2], / [[, out, ...])	同時傳回逐元素商和餘數。
absolute(x, /[, out, where, casting, order, ...])	逐元素計算絕對值。
fabs(x, /[, out, where, casting, order, ...])	逐元素計算絕對值。
rint(x, /[, out, where, casting, order, ...])	將陣列的元素四捨五入到最接近的整數。
sign(x, /[, out, where, casting, order, ...])	傳回數字符號的逐元素指示。
heaviside(x1, x2, /[, out, where, casting, ...])	計算 Heaviside 階躍函數。
conj(x, /[, out, where, casting, order, ...])	逐元素傳回複數共軛。
conjugate(x, /[, out, where, casting, ...])	逐元素傳回複數共軛。
exp(x, /[, out, where, casting, order, ...])	計算輸入陣列中所有元素的指數。
exp2(x, /[, out, where, casting, order, ...])	計算輸入陣列中所有 p 的 2**p。
log(x, /[, out, where, casting, order, ...])	自然對數，逐元素。
log2(x, /[, out, where, casting, order, ...])	x 的以 2 為底的對數。
log10(x, /[, out, where, casting, order, ...])	逐元素傳回輸入陣列的以 10 為底的對數。
expm1(x, /[, out, where, casting, order, ...])	計算陣列中所有元素的 exp(x) - 1。
log1p(x, /[, out, where, casting, order, ...])	逐元素傳回輸入陣列加一的自然對數。
sqrt(x, /[, out, where, casting, order, ...])	逐元素傳回陣列的非負平方根。
square(x, /[, out, where, casting, order, ...])	傳回輸入的逐元素平方。
cbrt(x, /[, out, where, casting, order, ...])	逐元素傳回陣列的立方根。
reciprocal(x, /[, out, where, casting, ...])	逐元素傳回引數的倒數。
gcd(x1, x2, /[, out, where, casting, order, ...])	傳回 |x1| 和 |x2| 的最大公約數
lcm(x1, x2, /[, out, where, casting, order, ...])	傳回 |x1| 和 |x2| 的最小公倍數

提示

選用性輸出引數可用於幫助您為大型計算節省記憶體。如果您的陣列很大，則由於暫時計算空間的建立和（稍後的）銷毀，複雜的表達式可能需要比絕對必要的時間更長的時間。例如，表達式 G = A * B + C 等效於 T1 = A * B; G = T1 + C; del T1。它將更快地執行為 G = A * B; add(G, C, G)，這與 G = A * B; G += C 相同。

三角函數

所有三角函數在需要角度時都使用弧度。度與弧度的比率為 \(180^{\circ}/\pi.\)

sin(x, /[, out, where, casting, order, ...])	三角正弦，逐元素。
cos(x, /[, out, where, casting, order, ...])	餘弦，逐元素。
tan(x, /[, out, where, casting, order, ...])	逐元素計算正切。
arcsin(x, /[, out, where, casting, order, ...])	反正弦，逐元素。
arccos(x, /[, out, where, casting, order, ...])	三角反餘弦，逐元素。
arctan(x, /[, out, where, casting, order, ...])	三角反正切，逐元素。
arctan2(x1, x2, /[, out, where, casting, ...])	逐元素計算 x1/x2 的反正切，正確選擇象限。
hypot(x1, x2, /[, out, where, casting, ...])	給定直角三角形的「邊長」，傳回其斜邊。
sinh(x, /[, out, where, casting, order, ...])	雙曲正弦，逐元素。
cosh(x, /[, out, where, casting, order, ...])	雙曲餘弦，逐元素。
tanh(x, /[, out, where, casting, order, ...])	逐元素計算雙曲正切。
arcsinh(x, /[, out, where, casting, order, ...])	反雙曲正弦，逐元素。
arccosh(x, /[, out, where, casting, order, ...])	反雙曲餘弦，逐元素。
arctanh(x, /[, out, where, casting, order, ...])	反雙曲正切，逐元素。
degrees(x, /[, out, where, casting, order, ...])	將角度從弧度轉換為度。
radians(x, /[, out, where, casting, order, ...])	將角度從度轉換為弧度。
deg2rad(x, /[, out, where, casting, order, ...])	將角度從度轉換為弧度。
rad2deg(x, /[, out, where, casting, order, ...])	將角度從弧度轉換為度。

位元運算函數

這些函數都要求整數引數，並且它們會操作這些引數的位元模式。

bitwise_and(x1, x2, /[, out, where, ...])	逐元素計算兩個陣列的位元 AND。
bitwise_or(x1, x2, /[, out, where, casting, ...])	逐元素計算兩個陣列的位元 OR。
bitwise_xor(x1, x2, /[, out, where, ...])	逐元素計算兩個陣列的位元 XOR。
invert(x, /[, out, where, casting, order, ...])	逐元素計算位元反轉或位元 NOT。
left_shift(x1, x2, /[, out, where, casting, ...])	將整數的位元向左移動。
right_shift(x1, x2, /[, out, where, ...])	將整數的位元向右移動。

比較函數

greater(x1, x2, /[, out, where, casting, ...])	element-wise 傳回 (x1 > x2) 的真值。
greater_equal(x1, x2, /[, out, where, ...])	element-wise 傳回 (x1 >= x2) 的真值。
less(x1, x2, /[, out, where, casting, ...])	element-wise 傳回 (x1 < x2) 的真值。
less_equal(x1, x2, /[, out, where, casting, ...])	element-wise 傳回 (x1 <= x2) 的真值。
not_equal(x1, x2, /[, out, where, casting, ...])	element-wise 傳回 (x1 != x2)。
equal(x1, x2, /[, out, where, casting, ...])	element-wise 傳回 (x1 == x2)。

警告

請勿使用 Python 關鍵字 and 和 or 來組合邏輯陣列運算式。這些關鍵字將測試整個陣列的真值（而不是您可能預期的逐元素測試）。請改用位元運算子 & 和 |。

logical_and(x1, x2, /[, out, where, ...])	element-wise 計算 x1 AND x2 的真值。
logical_or(x1, x2, /[, out, where, casting, ...])	element-wise 計算 x1 OR x2 的真值。
logical_xor(x1, x2, /[, out, where, ...])	element-wise 計算 x1 XOR x2 的真值。
logical_not(x, /[, out, where, casting, ...])	element-wise 計算 NOT x 的真值。

警告

位元運算子 & 和 | 是執行逐元素陣列比較的正確方法。請務必理解運算子優先順序：(a > 2) & (a < 5) 是正確的語法，因為 a > 2 & a < 5 會因為 2 & a 先被評估而導致錯誤。

maximum(x1, x2, /[, out, where, casting, ...])

陣列元素的 element-wise 最大值。

提示

Python 函式 max() 將找到一維陣列的最大值，但它將使用較慢的序列介面來完成。maximum ufunc 的 reduce 方法要快得多。此外，對於維度大於一的陣列，max() 方法不會給出您可能預期的答案。minimum 的 reduce 方法也允許您計算陣列的總最小值。

minimum(x1, x2, /[, out, where, casting, ...])

陣列元素的 element-wise 最小值。

警告

maximum(a, b) 的行為與 max(a, b) 的行為不同。作為一個 ufunc，maximum(a, b) 執行 a 和 b 的 element-wise 比較，並根據兩個陣列中哪個元素較大，來選擇結果的每個元素。相反，max(a, b) 將物件 a 和 b 視為整體，查看 a > b 的（總）真值，並使用它來傳回 a 或 b（作為整體）。minimum(a, b) 和 min(a, b) 之間也存在類似的差異。

fmax(x1, x2, /[, out, where, casting, ...])	陣列元素的 element-wise 最大值。
fmin(x1, x2, /[, out, where, casting, ...])	陣列元素的 element-wise 最小值。

浮點數函數

請記住，所有這些函數都對陣列執行 element-wise 操作，並傳回陣列輸出。描述僅詳細說明單一操作。

isfinite(x, /[, out, where, casting, order, ...])	element-wise 測試是否為有限值（非無限大且非非數字）。
isinf(x, /[, out, where, casting, order, ...])	element-wise 測試是否為正或負無限大。
isnan(x, /[, out, where, casting, order, ...])	element-wise 測試是否為 NaN 並傳回布林陣列結果。
isnat(x, /[, out, where, casting, order, ...])	element-wise 測試是否為 NaT（非時間）並傳回布林陣列結果。
fabs(x, /[, out, where, casting, order, ...])	逐元素計算絕對值。
signbit(x, /[, out, where, casting, order, ...])	element-wise 傳回 True，如果符號位元已設定（小於零）。
copysign(x1, x2, /[, out, where, casting, ...])	element-wise 將 x1 的符號更改為 x2 的符號。
nextafter(x1, x2, /[, out, where, casting, ...])	element-wise 傳回 x1 朝向 x2 之後的下一個浮點數值。
spacing(x, /[, out, where, casting, order, ...])	傳回 x 與最接近的相鄰數字之間的距離。
modf(x[, out1, out2], / [[, out, where, ...])	element-wise 傳回陣列的分數和整數部分。
ldexp(x1, x2, /[, out, where, casting, ...])	element-wise 傳回 x1 * 2**x2。
frexp(x[, out1, out2], / [[, out, where, ...])	將 x 的元素分解為假數和 2 的指數。
fmod(x1, x2, /[, out, where, casting, ...])	傳回逐元素除法餘數。
floor(x, /[, out, where, casting, order, ...])	element-wise 傳回輸入值的 floor（向下取整）。
ceil(x, /[, out, where, casting, order, ...])	element-wise 傳回輸入值的 ceiling（向上取整）。
trunc(x, /[, out, where, casting, order, ...])	element-wise 傳回輸入值的 truncated value（截斷值）。