通用函数（ufunc）ufunc

另请参阅

通用函数 (ufunc) 基础知识

通用函数（universal function），简称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)]。为了简化，对于操作一维数组（向量）的广义 ufunc，接受单个整数而不是单元素元组，并且对于所有输出都是标量的广义 ufunc，可以省略输出元组。

axis

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

keepdims

如果将其设置为 True，则将在此基础上进行约简的轴将在结果中保留为大小为一的维度，从而使结果能够正确地与输入进行广播。此选项只能用于操作所有核心维度数量相同的输入且输出没有核心维度（即，签名如 (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”，此时 ufunc 会对允许在“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、DType 元组或表示 ufunc 输入和输出类型的特殊签名字符串。

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

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

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

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

属性

通用函数具有一些信息性属性。其中任何属性都不能设置。

__doc__	每个 ufunc 的文档字符串。文档字符串的第一部分是根据输出数量、名称和输入数量动态生成的。文档字符串的第二部分是在创建时提供的，并与 ufunc 一起存储。
__name__	ufunc 的名称。
__signature__	ufunc 的调用签名，作为 inspect.Signature 对象。

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 来增加规约所用数据类型的范围。

可用的 ufuncs

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, ...])	计算单位阶跃函数。
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, ...])	逐元素计算两个数组的按位 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, ...])	逐元素返回 (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 的元素分解为尾数和二的幂指数。
fmod(x1, x2, /[, out, where, casting, ...])	返回除法的元素余数。
floor(x, /[, out, where, casting, order, ...])	逐元素返回输入的下取整值。
ceil(x, /[, out, where, casting, order, ...])	逐元素返回输入的上取整值。
trunc(x, /[, out, where, casting, order, ...])	逐元素返回输入的截断值。