通用函数 (ufunc)

参见

通用函数 (ufunc) 基础

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

ufunc

numpy.ufunc()

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

可选的关键字参数

所有ufuncs都接受可选的关键字参数.这些参数大多数代表高级用法,通常不会被使用.

out

在 1.6 版本加入.

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

在 1.10 版本加入.

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

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

如果 ‘out’ 是 None（默认值）,则创建一个未初始化的返回数组.然后,在广播 ‘where’ 为 True 的位置,输出数组会填充 ufunc 的结果.如果 ‘where’ 是标量 True（默认值）,则这对应于整个输出被填充.请注意,未明确填充的输出将保留其未初始化的值.

在 1.13 版本加入.

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

where

在 1.7 版本加入.

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

请注意,如果创建了一个未初始化的返回数组,值为 False 将使这些值 未初始化.

axes

在 1.15 版本加入.

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

axis

在 1.15 版本加入.

一个泛型ufunc应操作的单个轴.这是对操作单个共享核心维度的ufunc的快捷方式,相当于将 axes 传递为每个单核心维度参数的 (axis,) 条目和其他所有参数的 () 条目.例如,对于签名 (i),(i)->() ,它相当于传递 axes=[(axis,), (axis,), ()].

keepdims

在 1.15 版本加入.

如果设置为 True,被缩减的轴将保留在结果中作为一个大小为一的维度,以便结果能正确地与输入进行广播.此选项只能用于对所有输入具有相同核心维度的广义ufuncs,并且输出没有核心维度,即签名如 (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’ 的过渡,其中 ufuncs 为在 ‘unsafe’ 规则下允许但在 ‘same_kind’ 规则下不允许的调用产生一个弃用警告.从 numpy 1.10 及以后,默认值为 ‘same_kind’.

order

在 1.6 版本加入.

指定输出数组的计算迭代顺序/内存布局.默认为 ‘K’.’C’ 表示输出应为 C-contiguous,’F’ 表示 F-contiguous,’A’ 表示如果输入是 F-contiguous 且不是 C-contiguous,则为 F-contiguous,否则为 C-contiguous,’K’ 表示尽可能匹配输入的元素顺序.

dtype

在 1.6 版本加入.

覆盖输出数组的DType,方式与 signature 相同.这应确保计算的精度匹配.所选的确切计算DTypes可能取决于ufunc和输入,可能被转换为此DType以执行计算.

subok

在 1.6 版本加入.

默认为真.如果设置为假,输出将始终是一个严格的数组,而不是一个子类型.

signature

一个 Dtype、一个 DTypes 的元组,或一个特殊的签名字符串,指示 ufunc 的输入和输出类型.

此参数允许用户指定用于计算的确切 DTypes.必要时将使用强制转换.除非该数组的 signature 为 None,否则不考虑输入数组的实际 DType.

当所有 DTypes 都固定时,会选择一个特定的循环,或者如果没有匹配的循环则引发错误.如果某些 DTypes 未指定并保留为 None,行为可能取决于 ufunc.此时,可通过 ufunc 的 types 属性提供可用签名的列表.（此列表可能缺少 NumPy 未定义的 DTypes.）

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, b),其中 a 在 A 中,b 在 B 中.
ufunc.at(a, indices[, b])	对操作数 'a' 中由 'indices' 指定的元素执行无缓冲的就地操作.

警告

在一个数组上进行类似 reduce 的操作,如果数据类型的范围”太小”而无法处理结果,将会静默地回绕.应使用 dtype 来增加进行归约的数据类型的大小.

可用的 ufuncs

目前,在 numpy 中定义了超过 60 个通用函数,涵盖了一个或多个类型,覆盖了广泛的操作.其中一些 ufuncs 在使用相关的中缀表示法时会自动调用（例如,当 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, ...])	返回输入数组加一的自然对数,逐元素计算.
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 和 x2 的逐元素逻辑与值.
logical_or(x1, x2, /[, out, where, casting, ...])	计算 x1 或 x2 的元素级真值.
logical_xor(x1, x2, /[, out, where, ...])	计算 x1 和 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 的元素分解为尾数和二的指数.
fmod(x1, x2, /[, out, where, casting, ...])	返回逐元素除法的余数.
floor(x, /[, out, where, casting, order, ...])	返回输入的向下取整结果,逐元素进行.
ceil(x, /[, out, where, casting, order, ...])	返回输入的上限,逐元素进行.
trunc(x, /[, out, where, casting, order, ...])	返回输入的截断值,逐元素进行.