通用函数 ( `ufunc` )#

参见

通用函数(简称 ufunc )是一种以元素方式对 ndarrays 进行操作的函数,支持 array broadcasting , type casting 和其他几个标准功能.也就是说,ufunc 是一个 “ vectorized ” 包装器,用于接受固定数量的特定输入并产生固定数量的特定输出的函数.有关通用函数的详细信息,请参阅通用函数( 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,因为广义 ufunc 采用非标量输入.

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

axes

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

axis

广义 ufunc 应该在其上运行的单个轴. 这是对在单个共享核心维度上运行的 ufunc 的快捷方式,相当于传入 axes ,其中每个单核心维度参数的条目为 (axis,) ,所有其他参数的条目为 () . 例如,对于签名 (i),(i)->() ,它等效于传入 axes=[(axis,), (axis,), ()] .

keepdims

如果将其设置为 True ,则缩减的轴将作为大小为 1 的维度保留在结果中,以便结果与输入正确广播. 此选项只能用于对所有具有相同数量的核心维度且输出没有核心维度的输入进行操作的广义 ufunc,即具有诸如 (i),(i)->() 或 (m,m)->() 之类的签名. 如果使用,可以使用 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 signature 混淆.

属性#

存在一些通用函数拥有的信息性属性.这些属性都不能设置.

__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, ...])	使用指定切片在单个轴上执行(本地)reduce.
`ufunc.outer` (A, B, /, \kwargs)	将ufunc op 应用于 A 中的 a 和 B 中的 b 的所有对 (a, b).
`ufunc.at` (a, indices[, b])	对由“索引”指定的元素执行操作数“a”上的非缓冲就地操作.

警告

如果一个数组的数据类型范围“太小”而无法处理结果,则此数组上的类似 reduce 的操作会默默地进行环绕.应该使用 dtype 来增加数据类型的大小,以便进行归约运算.

可用的 ufunc#

目前在 numpy 中定义了 60 多个通用函数,涵盖一个或多个类型,涵盖了各种各样的操作. 当使用相关的中缀表示法时,有些 ufunc 会自动在数组上调用(例如,当写入 a + b 并且 a 或 b 是 add(a, b) 时,会在内部调用 ndarray ). 尽管如此,您可能仍然需要使用 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 的 2p .
`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, ...])	三角正弦, element-wise.
`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, ...])	双曲正弦, element-wise.
`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() 方法不会给出您可能期望的维数大于 1 的数组的答案. 最小值 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, ...])	如果 signbit 被设置 (小于零),则返回 element-wise 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 * 2x2,逐个元素.
`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, ...])	返回输入的截断值,逐个元素.

如何运行和测试 NumPy 的代码？

在探索 NumPy 库的核心概念、常见问题和实用代码示例时，所有代码都可在 PythonRun 上直接运行测试。

请给出一个简单的 NumPy 代码示例

下面是一个简单的 NumPy 用法示例：

import numpy as np
a = np.array([1, 2, 3])
a = a * 2
print(a)

你可以在 PythonRun 上执行它，看看结果。

通用函数 ( ufunc )#

ufunc#