通用函数 (ufunc)

另请参阅

通用函数 (ufunc) 基础知识

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

ufunc

numpy.ufunc()

在整个数组上逐元素操作的函数。

可选关键字参数

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

out

版本 1.6 中的新功能。

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

版本 1.10 中的新功能。

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

在“out”关键字参数中传递单个数组到具有多个输出的 ufunc 已弃用，并且将在 numpy 1.10 中引发警告，在将来的版本中引发错误。

如果“out”为 None（默认值），则会创建一个未初始化的返回数组。然后，输出数组将使用 ufunc 的结果填充广播“where”为 True 的位置。如果“where”是标量 True（默认值），则这对应于填充整个输出。请注意，未显式填充的输出将保留其未初始化的值。

版本 1.13 中的新功能。

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

where

版本 1.7 中的新功能。

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

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

axes

版本 1.15 中的新功能。

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

axis

版本 1.15 中的新功能。

广义 ufunc 应在其上操作的单个轴。这是用于跨单个共享核心维度操作的 ufunc 的快捷方式，相当于传递具有每个单核心维度参数的 (axis,) 条目和所有其他参数的 () 的 axes。例如，对于签名 (i),(i)->()，它等效于传递 axes=[(axis,), (axis,), ()]。

keepdims

版本 1.15 中的新功能。

如果将其设置为True，则将减少的轴保留在结果中作为大小为一的维度，以便结果可以针对输入正确广播。此选项仅可用于对所有具有相同核心维度数量的输入进行操作并且输出没有核心维度的广义 ufunc，即签名类似于 (i),(i)->() 或 (m,m)->()。如果使用，则可以使用 axes 和 axis 控制输出中维度的位置。

casting

版本 1.6 中的新功能。

可以是“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

版本 1.6 中的新功能。

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

dtype

版本 1.6 中的新功能。

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

subok

版本 1.6 中的新功能。

默认为 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 对象的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 多个通用函数，涵盖了各种各样的操作。其中一些 ufunc 在使用相关的中缀表示法时会自动在数组上调用（例如，当编写 a + b 且a或b为 ndarray 时，内部会调用 add(a, b)）。但是，您可能仍然希望使用 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, ...])	逐元素返回输入数组加 1 后的自然对数。
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() 将找到一维数组的最大值，但它将使用较慢的序列接口来实现。最大 ufunc 的 reduce 方法要快得多。此外，max() 方法对于维度大于一的数组不会给出您可能期望的答案。最小值的 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, ...])	逐元素返回输入的截断值。