通用函数 (ufunc)

另请参阅

通用函数 (ufunc) 基础

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

ufunc

numpy.ufunc()

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

可选关键字参数

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

out

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

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

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

如果 'out' 为 None（默认），则会创建一个未初始化的返回数组。 然后，输出数组将填充 ufunc 的结果，其中广播的“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，则将保留缩减的轴作为大小为 1 的维度留在结果中，以便结果可以针对输入正确广播。此选项只能用于对所有具有相同数量的核心维度的输入以及没有核心维度的输出（即具有 (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

以与*签名*相同的方式覆盖输出数组的 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 签名混淆。

属性

通用函数有一些信息性属性。 没有一个属性可以设置。

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

ufunc.nin	输入的数量。
ufunc.nout	输出的数量。
ufunc.nargs	参数的数量。
ufunc.ntypes	类型的数量。
ufunc.types	返回一个列表，其中类型按 input->output 分组。
ufunc.identity	单位值。
ufunc.signature	定义通用ufunc操作的核心元素。

方法

ufunc.reduce(array[, axis, dtype, out, ...])	通过沿一个轴应用ufunc，将array的维度减少一维。
ufunc.accumulate(array[, axis, dtype, out])	累积将运算符应用于所有元素的结果。
ufunc.reduceat(array, indices[, axis, ...])	对单个轴上的指定切片执行（局部）reduce操作。
ufunc.outer(A, B, /, **kwargs)	将ufunc op 应用于 A 中的所有 a 和 B 中的所有 b 的所有对 (a, b)。
ufunc.at(a, indices[, b])	对由“indices”指定的元素，在操作数“a”上执行无缓冲的原地操作。

警告

如果数组的数据类型范围“太小”而无法处理结果，则 reduce 类操作将静默换行。应该使用dtype来增加进行reduce操作的数据类型的大小。

可用的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, ...])	逐元素返回输入数组加 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() 将找到一维数组的最大值，但它会使用较慢的序列接口执行此操作。maximum ufunc 的 reduce 方法速度更快。此外，对于维度大于 1 的数组，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, ...])	逐元素返回输入的截断值。