通用函数 (ufunc)

另请参阅

通用函数 (ufunc) 基础

通用函数（简称 ufunc）是一种逐元素操作 ndarray 的函数，支持 数组广播、类型转换以及其他一些标准特性。也就是说，ufunc 是一个“矢量化”的包装器，用于接受固定数量的特定输入并产生固定数量的特定输出的函数。有关通用函数的详细信息，请参阅通用函数 (ufunc) 基础。

ufunc

numpy.ufunc()

对整个数组进行逐元素操作的函数。

可选关键字参数

所有 ufunc 都接受可选的关键字参数。其中大多数表示高级用法，通常不会被使用。

out

第一个输出可以作为位置参数或关键字参数提供。关键字“out”参数与位置参数不兼容。

“out”关键字参数预期是一个元组，每个输出有一个条目（对于由 ufunc 分配的数组，可以是 None）。对于单个输出的 ufunc，传递一个单个数组（而不是包含单个数组的元组）也是有效的。

如果“out”为 None（默认值），则会创建一个未初始化的输出数组，该数组将在 ufunc 中填充。最后，除非此数组是零维的，否则将返回此数组，零维数组将转换为标量；可以通过传入 out=... 来避免这种转换。如果您认为更清晰，也可以写成 out=Ellipsis。

请注意，输出仅在广播的“where”为 True 的位置填充。如果“where”是标量 True（默认），则对应于输出的所有元素，但在其他情况下，未显式填充的元素将保留其未初始化的值。

ufunc 输入和输出操作数具有内存重叠的操作被定义为与没有内存重叠的等效操作相同。受影响的操作会根据需要创建临时副本以消除数据依赖性。由于检测这些情况的计算成本很高，因此使用了一种启发式方法，在极少数情况下可能导致不必要的临时副本。对于数据依赖性足够简单以便启发式方法分析的操作，即使数组重叠，如果可以推断出不需要副本，也不会创建临时副本。例如，np.add(a, b, out=a) 不会涉及副本。

where

接受一个布尔数组，该数组与操作数一起广播。True 值表示在该位置计算 ufunc，False 值表示保留输出中的值不变。此参数不能用于广义 ufunc，因为它们接受非标量输入。

请注意，如果创建了未初始化的返回数组，则 False 值将使这些值未初始化。

axes

一个元组列表，包含广义 ufunc 应该操作的轴的索引。例如，对于适用于矩阵乘法的签名 (i,j),(j,k)->(i,k)，基本元素是二维矩阵，并且这些矩阵被视为存储在每个参数的最后两个轴中。相应的 axes 关键字将是 [(-2, -1), (-2, -1), (-2, -1)]。为简单起见，对于操作 1 维数组（向量）的广义 ufunc，接受单个整数而不是单元素元组；对于所有输出都是标量的广义 ufunc，可以省略输出元组。

axis

一个广义 ufunc 应该操作的单一轴。这是操作单个共享核心维度的 ufunc 的快捷方式，等同于为每个单核心维度参数传入带有 (axis,) 条目的 axes，并为所有其他参数传入 ()。例如，对于签名 (i),(i)->()，它等同于传入 axes=[(axis,), (axis,), ()]。

keepdims

如果设置为 True，则被约简的轴将作为大小为一的维度保留在结果中，以便结果能够正确地与输入广播。此选项仅适用于操作具有相同核心维度数量的输入且输出没有核心维度的广义 ufunc，即具有 (i),(i)->() 或 (m,m)->() 等签名的 ufunc。如果使用，输出中维度的位置可以通过 axes 和 axis 控制。

casting

可以是“no”、“equiv”、“safe”、“same_kind”或“unsafe”。有关参数值的解释，请参阅 can_cast。

提供允许哪种类型转换的策略。为了与 NumPy 早期版本兼容，对于 numpy < 1.7，此值默认为“unsafe”。在 numpy 1.7 中，开始向“same_kind”过渡，在此过程中，ufuncs 对于在“unsafe”规则下允许但在“same_kind”规则下不允许的调用会产生 DeprecationWarning。从 numpy 1.10 及更高版本开始，默认值为“same_kind”。

order

指定输出数组的计算迭代顺序/内存布局。默认为“K”。“C”表示输出应该是 C 连续的，“F”表示 F 连续的，“A”表示如果输入是 F 连续且不是 C 连续的，则为 F 连续，否则为 C 连续，“K”表示尽可能匹配输入的元素顺序。

dtype

以与 signature 相同的方式覆盖输出数组的 DType。这应确保计算的精度匹配。所选的具体计算 DType 可能取决于 ufunc，并且输入可能会被转换为此 DType 以执行计算。

subok

默认为 true。如果设置为 false，输出将始终是严格数组，而不是子类型。

signature

可以是 DType、DTypes 元组或指示 ufunc 输入和输出类型的特殊签名字符串。

此参数允许用户指定用于计算的确切 DType。必要时将使用类型转换。除非该数组的 signature 为 None，否则不会考虑输入数组的实际 DType。

当所有 DType 都固定时，将选择一个特定的循环，如果不存在匹配的循环，则会引发错误。如果某些 DType 未指定并保留为 None，则行为可能取决于 ufunc。目前，ufunc 的 types 属性提供了可用签名列表。（此列表可能缺少 NumPy 未定义的 DType。）

signature 仅指定 DType 类/类型。例如，它可以指定操作应该是 datetime64 或 float64 操作。它不指定 datetime64 时间单位或 float64 字节顺序。

为了向后兼容，此参数也可以作为 sig 提供，尽管首选长格式。请注意，这不应与存储在 ufunc 对象的 signature 属性中的广义 ufunc 签名 混淆。

属性

通用函数具有一些信息属性。所有属性都不能设置。

__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])	对由“indices”指定的元素，在操作数“a”上执行无缓冲的就地操作。

警告

对数据类型范围“太小”而无法处理结果的数组执行类似约简的操作时，将静默回绕。应该使用 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, ...])	逐元素计算两个数组的位与。
bitwise_or(x1, x2, /[, out, where, casting, ...])	逐元素计算两个数组的位或。
bitwise_xor(x1, x2, /[, out, where, ...])	逐元素计算两个数组的位异或。
invert(x, /[, out, where, casting, order, ...])	逐元素计算按位反转，或按位非。
left_shift(x1, x2, /[, out, where, casting, ...])	将整数的位向左移动。
right_shift(x1, x2, /[, out, where, ...])	将整数的位向右移动。

比较函数

greater(x1, x2, /[, out, where, casting, ...])	逐元素返回 (x1 > x2) 的真值。
greater_equal(x1, x2, /[, out, where, ...])	逐元素返回 (x1 >= x2) 的真值。
less(x1, x2, /[, out, where, casting, ...])	逐元素返回 (x1 < x2) 的真值。
less_equal(x1, x2, /[, out, where, casting, ...])	逐元素返回 (x1 <= x2) 的真值。
not_equal(x1, x2, /[, out, where, casting, ...])	逐元素返回 (x1 != x2)。
equal(x1, x2, /[, out, where, casting, ...])	逐元素返回 (x1 == x2)。

警告

不要使用 Python 关键字 and 和 or 来组合逻辑数组表达式。这些关键字将测试整个数组的真值（而不是您可能期望的逐元素真值）。请改用位运算符 & 和 |。

logical_and(x1, x2, /[, out, where, ...])	逐元素计算 x1 AND x2 的真值。
logical_or(x1, x2, /[, out, where, casting, ...])	逐元素计算 x1 OR x2 的真值。
logical_xor(x1, x2, /[, out, where, ...])	逐元素计算 x1 XOR x2 的真值。
logical_not(x, /[, out, where, casting, ...])	逐元素计算 NOT x 的真值。

警告

位运算符 & 和 | 是执行逐元素数组比较的正确方式。请务必理解运算符优先级：(a > 2) & (a < 5) 是正确的语法，因为 a > 2 & a < 5 会导致错误，因为 2 & a 会先被评估。

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

数组元素的逐元素最大值。

提示

Python 函数 max() 会找到一维数组的最大值，但它使用较慢的序列接口。maximum ufunc 的 reduce 方法要快得多。此外，max() 方法对于多维数组可能不会给出您期望的结果。minimum 的 reduce 方法也允许您计算数组的总最小值。

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

数组元素的逐元素最小值。

警告

maximum(a, b) 的行为与 max(a, b) 不同。作为 ufunc，maximum(a, b) 对 a 和 b 进行逐元素比较，并根据两个数组中哪个元素更大来选择结果的每个元素。相比之下，max(a, b) 将对象 a 和 b 视为一个整体，查看 a > b 的（总）真值，并用它来返回 a 或 b（作为一个整体）。minimum(a, b) 和 min(a, b) 之间也存在类似的区别。

fmax(x1, x2, /[, out, where, casting, ...])	数组元素的逐元素最大值。
fmin(x1, x2, /[, out, where, casting, ...])	数组元素的逐元素最小值。

浮点函数

请记住，所有这些函数都对数组进行逐元素操作，返回一个数组输出。描述中只详细说明了单个操作。

isfinite(x, /[, out, where, casting, order, ...])	逐元素测试有限性（不是无穷大且不是非数字）。
isinf(x, /[, out, where, casting, order, ...])	逐元素测试正无穷大或负无穷大。
isnan(x, /[, out, where, casting, order, ...])	逐元素测试 NaN 并将结果作为布尔数组返回。
isnat(x, /[, out, where, casting, order, ...])	逐元素测试 NaT（非时间）并将结果作为布尔数组返回。
fabs(x, /[, out, where, casting, order, ...])	逐元素计算绝对值。
signbit(x, /[, out, where, casting, order, ...])	逐元素返回符号位设置（小于零）为 True 的位置。
copysign(x1, x2, /[, out, where, casting, ...])	逐元素将 x1 的符号更改为 x2 的符号。
nextafter(x1, x2, /[, out, where, casting, ...])	逐元素返回 x1 向 x2 方向的下一个浮点值。
spacing(x, /[, out, where, casting, order, ...])	返回 x 与最近相邻数字之间的距离。
modf(x[, out1, out2], / [[, out, where, ...])	逐元素返回数组的小数部分和整数部分。
ldexp(x1, x2, /[, out, where, casting, ...])	逐元素返回 x1 * 2**x2。
frexp(x[, out1, out2], / [[, out, where, ...])	将 x 的元素分解为尾数和以 2 为底的指数。
fmod(x1, x2, /[, out, where, casting, ...])	返回除法的逐元素余数。
floor(x, /[, out, where, casting, order, ...])	逐元素返回输入的向下取整值。
ceil(x, /[, out, where, casting, order, ...])	逐元素返回输入的向上取整值。
trunc(x, /[, out, where, casting, order, ...])	逐元素返回输入的截断值。