通用函数 (`ufunc`) 基础#

另请参阅

通用函数（简称 ufunc）是一种以逐元素方式对 ndarrays 进行操作的函数，支持数组广播、类型转换以及其他一些标准特性。也就是说，ufunc 是一个“向量化”包装器，用于封装一个接受固定数量的特定输入并产生固定数量的特定输出的函数。

在 NumPy 中，通用函数是 numpy.ufunc 类的一个实例。许多内置函数都是用编译后的 C 代码实现的。基本的 ufuncs 操作标量，但也有泛化类型，其中基本元素是子数组（向量、矩阵等），并且广播在其他维度上进行。最简单的例子是加法运算符

>>> np.array([0,2,3,4]) + np.array([1,1,-1,2])
array([1, 3, 2, 6])

还可以使用 numpy.frompyfunc 工厂函数生成自定义的 numpy.ufunc 实例。

Ufunc 方法#

所有 ufunc 都有四个方法。它们可以在方法中找到。然而，这些方法仅对接受两个输入参数并返回一个输出参数的标量 ufuncs 有意义。尝试对其他 ufuncs 调用这些方法将导致 ValueError。

所有类似 reduce 的方法都接受一个 axis 关键字、一个 dtype 关键字和一个 out 关键字，并且数组的维度必须都 >= 1。axis 关键字指定了要进行归约运算的数组轴（负值表示倒数）。通常，它是一个整数，但对于 numpy.ufunc.reduce，它也可以是 int 的元组，用于一次性在多个轴上进行归约，或者 None，用于在所有轴上进行归约。例如

>>> x = np.arange(9).reshape(3,3)
>>> x
array([[0, 1, 2],
      [3, 4, 5],
      [6, 7, 8]])
>>> np.add.reduce(x, 1)
array([ 3, 12, 21])
>>> np.add.reduce(x, (0, 1))
36

dtype 关键字允许您管理在使用 ufunc.reduce 时常见的一个问题。有时您可能有一个特定数据类型的数组，并希望将其所有元素相加，但结果不适合该数组的数据类型。如果您有一个单字节整数数组，这种情况通常会发生。dtype 关键字允许您更改归约操作发生时的数据类型（从而也改变输出的类型）。因此，您可以确保输出的数据类型具有足够大的精度来处理您的结果。更改归约类型的责任主要在于您。有一个例外：如果在“add”或“multiply”操作的归约中没有给出 dtype，那么如果输入类型是整数（或布尔）数据类型且小于 numpy.int_ 数据类型的大小，它将内部向上转换为 int_（或 numpy.uint）数据类型。在之前的例子中

>>> x.dtype
dtype('int64')
>>> np.multiply.reduce(x, dtype=float)
array([ 0., 28., 80.])

最后，out 关键字允许您提供一个输出数组（对于多输出 ufunc 而言，可以是一个输出数组元组）。如果提供了 out，则 dtype 参数仅用于内部计算。考虑到上一个示例中的 x

>>> y = np.zeros(3, dtype=int)
>>> y
array([0, 0, 0])
>>> np.multiply.reduce(x, dtype=float, out=y)
array([ 0, 28, 80])

Ufunc 还有第五个方法，numpy.ufunc.at，它允许使用高级索引执行原地操作。在使用高级索引的维度上不使用缓冲，因此高级索引可以多次列出同一个项目，并且操作将基于该项目上一次操作的结果执行。

输出类型确定#

如果 ufunc（或其方法）的输入参数是 ndarrays，则输出也将是。唯一的例外是当结果为零维度时，此时输出将被转换为数组标量。可以通过传入 out=... 或 out=Ellipsis 来避免这种情况。

如果部分或所有输入参数不是 ndarrays，则输出也可能不是 ndarray。实际上，如果任何输入定义了 __array_ufunc__ 方法，控制权将完全传递给该函数，即 ufunc 将被重写。

如果没有输入重写 ufunc，那么所有输出数组都将传递给定义了 __array_wrap__ 方法的输入（除了 ndarrays 和标量），并且该输入在通用函数的任何其他输入中具有最高的 __array_priority__。ndarray 的默认 __array_priority__ 是 0.0，子类型的默认 __array_priority__ 也是 0.0。矩阵的 __array_priority__ 等于 10.0。

所有 ufunc 也可以接受输出参数，这些参数必须是数组或子类。如有必要，结果将被转换为所提供的输出数组的数据类型。如果输出具有 __array_wrap__ 方法，则会调用该方法，而不是输入中找到的方法。

广播#

另请参阅

广播基础

每个通用函数都接受数组输入并通过对输入逐元素执行核心函数来生成数组输出（其中元素通常是标量，但对于泛化 ufunc 来说可以是向量或更高阶的子数组）。应用标准的广播规则，以便形状不完全相同的输入仍能有效地进行操作。

根据这些规则，如果输入的形状中某个维度的大小为 1，则该维度的第一个数据条目将用于该维度上的所有计算。换句话说，ufunc 的步进机制将简单地不沿该维度步进（该维度的步幅将为 0）。

类型转换规则#

注意

在 NumPy 1.6.0 中，创建了一个类型提升 API，用于封装确定输出类型的机制。有关更多详细信息，请参阅函数 numpy.result_type、numpy.promote_types 和 numpy.min_scalar_type。

每个 ufunc 的核心是一个一维跨步循环，它为特定的类型组合实现实际功能。创建 ufunc 时，会为其提供一个内部循环的静态列表以及一个 ufunc 操作的相应类型签名列表。ufunc 机制使用此列表来确定在特定情况下使用哪个内部循环。您可以检查特定 ufunc 的 .types 属性，以查看哪些类型组合具有已定义的内部循环以及它们产生哪种输出类型（字符代码在该输出中用于简洁）。

当 ufunc 没有为提供的输入类型实现核心循环时，必须对一个或多个输入进行类型转换。如果找不到输入类型的实现，则算法会搜索一个类型签名，所有输入都可以“安全地”转换为该类型签名的实现。它在其内部循环列表中找到的第一个将被选中并执行，在所有必要的类型转换之后。请记住，ufunc 期间的内部复制（即使是为了类型转换）也受限于内部缓冲区的大小（这是用户可设置的）。

注意

NumPy 中的通用函数足够灵活，可以拥有混合类型签名。因此，例如，可以定义一个处理浮点值和整数值的通用函数。请参阅 numpy.ldexp 以获取示例。

根据上述描述，类型转换规则本质上是通过“何时可以将一种数据类型‘安全地’转换为另一种数据类型”的问题来实现的。这个问题的答案可以在 Python 中通过函数调用确定：can_cast(fromtype, totype)。下面的示例显示了作者的 64 位系统上 24 种内部支持类型的此调用结果。您可以使用示例中给出的代码为您的系统生成此表。

示例

显示 64 位系统上“可以安全转换”表的代码片段。通常，输出取决于系统；您的系统可能会产生不同的表。

>>> mark = {False: ' -', True: ' Y'}
>>> def print_table(ntypes):
...     print('X ' + ' '.join(ntypes))
...     for row in ntypes:
...         print(row, end='')
...         for col in ntypes:
...             print(mark[np.can_cast(row, col)], end='')
...         print()
...
>>> print_table(np.typecodes['All'])
X ? b h i l q n p B H I L Q N P e f d g F D G S U V O M m
? Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Y
b - Y Y Y Y Y Y Y - - - - - - - Y Y Y Y Y Y Y Y Y Y Y - Y
h - - Y Y Y Y Y Y - - - - - - - - Y Y Y Y Y Y Y Y Y Y - Y
i - - - Y Y Y Y Y - - - - - - - - - Y Y - Y Y Y Y Y Y - Y
l - - - - Y Y Y Y - - - - - - - - - Y Y - Y Y Y Y Y Y - Y
q - - - - Y Y Y Y - - - - - - - - - Y Y - Y Y Y Y Y Y - Y
n - - - - Y Y Y Y - - - - - - - - - Y Y - Y Y Y Y Y Y - Y
p - - - - Y Y Y Y - - - - - - - - - Y Y - Y Y Y Y Y Y - Y
B - - Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y - Y
H - - - Y Y Y Y Y - Y Y Y Y Y Y - Y Y Y Y Y Y Y Y Y Y - Y
I - - - - Y Y Y Y - - Y Y Y Y Y - - Y Y - Y Y Y Y Y Y - Y
L - - - - - - - - - - - Y Y Y Y - - Y Y - Y Y Y Y Y Y - -
Q - - - - - - - - - - - Y Y Y Y - - Y Y - Y Y Y Y Y Y - -
N - - - - - - - - - - - Y Y Y Y - - Y Y - Y Y Y Y Y Y - -
P - - - - - - - - - - - Y Y Y Y - - Y Y - Y Y Y Y Y Y - -
e - - - - - - - - - - - - - - - Y Y Y Y Y Y Y Y Y Y Y - -
f - - - - - - - - - - - - - - - - Y Y Y Y Y Y Y Y Y Y - -
d - - - - - - - - - - - - - - - - - Y Y - Y Y Y Y Y Y - -
g - - - - - - - - - - - - - - - - - - Y - - Y Y Y Y Y - -
F - - - - - - - - - - - - - - - - - - - Y Y Y Y Y Y Y - -
D - - - - - - - - - - - - - - - - - - - - Y Y Y Y Y Y - -
G - - - - - - - - - - - - - - - - - - - - - Y Y Y Y Y - -
S - - - - - - - - - - - - - - - - - - - - - - Y Y Y Y - -
U - - - - - - - - - - - - - - - - - - - - - - - Y Y Y - -
V - - - - - - - - - - - - - - - - - - - - - - - - Y Y - -
O - - - - - - - - - - - - - - - - - - - - - - - - - Y - -
M - - - - - - - - - - - - - - - - - - - - - - - - Y Y Y -
m - - - - - - - - - - - - - - - - - - - - - - - - Y Y - Y

您应该注意，尽管为了完整性而包含在表中，但 ufunc 无法对“S”、“U”和“V”类型进行操作。此外，请注意，在 32 位系统上，整数类型可能具有不同的大小，从而导致表格略有不同。

混合标量-数组操作使用一组不同的类型转换规则，这些规则确保标量不能“向上转换”数组，除非该标量与数组的数据类型从根本上不同（即，在数据类型层次结构中属于不同的层次）。此规则使您可以在代码中使用标量常量（作为 Python 类型，它们在 ufunc 中相应地进行解释），而无需担心标量常量的精度是否会导致大型（小精度）数组的向上转换。

内部缓冲区的使用#

在内部，缓冲区用于未对齐的数据、交换的数据以及需要从一种数据类型转换为另一种数据类型的数据。内部缓冲区的大小可以按线程设置。可以创建多达 \(2 (n_{\mathrm{inputs}} + n_{\mathrm{outputs}})\) 个指定大小的缓冲区来处理 ufunc 的所有输入和输出数据。缓冲区的默认大小为 10,000 个元素。每当需要基于缓冲区的计算时，但所有输入数组都小于缓冲区大小时，这些行为不当或类型不正确的数组将在计算进行之前被复制。因此，调整缓冲区大小可能会改变各种 ufunc 计算完成的速度。可以使用函数 numpy.setbufsize 访问用于设置此变量的简单接口。

错误处理#

通用函数可能会触发硬件中的特殊浮点状态寄存器（例如除以零）。如果您的平台上可用，这些寄存器将在计算期间定期检查。错误处理是按线程控制的，可以使用函数 numpy.seterr 和 numpy.seterrcall 进行配置。

重写 ufunc 行为#

类（包括 ndarray 子类）可以通过定义某些特殊方法来重写 ufunc 对它们的作用方式。有关详细信息，请参阅标准数组子类。

通用函数 (ufunc) 基础#