NEP 5 — 广义通用函数#
- 状态:
最终
如 https://scipy.org.cn/scipy/numpy/wiki/GeneralLoopingFunctions 所述,普遍存在对不仅标量函数而且向量(或数组)函数进行循环的需求。我们建议通过推广通用函数 (ufuncs) 来实现这一概念,并提供一个 C 实现,为 NumPy 代码库增加约 500 行。在当前(专门的)ufunc 中,基本函数限于逐元素操作,而广义版本支持“子数组”逐“子数组”操作。Perl 向量库 PDL 提供了类似的功能,其术语在下文中重复使用。
每个广义 ufunc 都附带有信息,说明其输入和相应的输出的“核心”维度(逐元素的 ufunc 具有零核心维度)。所有参数的核心维度列表称为 ufunc 的“签名”。例如,ufunc numpy.add 的签名是 (),()->()
,定义了两个标量输入和一个标量输出。
另一个例子是(参见 GeneralLoopingFunctions 页面)函数 inner1d(a,b)
,其签名是 (i),(i)->()
。这会沿每个输入的最后一个轴应用内积,但保持剩余索引不变。例如,当 a
的形状为 (3,5,N)
且 b
的形状为 (5,N)
时,这将返回形状为 (3,5)
的输出。底层基本函数被调用 3*5 次。在签名中,我们为每个输入指定一个核心维度 (i)
,为输出指定零核心维度 ()
,因为它接受两个一维数组并返回一个标量。通过使用相同的名称 i
,我们指定了两个相应的维度应该大小相同(或者其中一个大小为 1 并将被广播)。
核心维度之外的维度称为“循环”维度。在上述示例中,这对应于 (3,5)
。
通常的 NumPy“广播”规则适用,其中签名决定了每个输入/输出对象的维度如何划分为核心维度和循环维度
当输入数组的维度小于相应的核心维度数量时,会在其形状前面添加 1。
从所有输入中移除核心维度,其余维度进行广播;定义循环维度。
输出由循环维度加上输出核心维度给出。
定义#
- 基本函数
每个 ufunc 都包含一个基本函数,该函数对数组参数的最小部分执行最基本的操作(例如,将两个数字相加是两个数组相加中最基本的操作)。ufunc 对数组的不同部分多次应用基本函数。基本函数的输入/输出可以是向量;例如,inner1d 的基本函数接受两个向量作为输入。
- 签名
签名是一个字符串,描述 ufunc 的基本函数的输入/输出维度。更多详情请参见以下章节。
- 核心维度
基本函数每个输入/输出的维度由其核心维度定义(零核心维度对应于标量输入/输出)。核心维度映射到输入/输出数组的最后维度。
- 维度名称
维度名称表示签名中的一个核心维度。不同的维度可以共享一个名称,表示它们大小相同(或可广播)。
- 维度索引
维度索引是一个整数,表示一个维度名称。它根据每个名称在签名中首次出现的顺序枚举维度名称。
签名详情#
签名定义了输入和输出变量的“核心”维度,从而也定义了维度的收缩。签名由以下格式的字符串表示:
每个输入或输出数组的核心维度用括号中的维度名称列表表示,例如
(i_1,...,i_N)
;标量输入/输出用()
表示。可以使用任何有效的 Python 变量名代替i_1
、i_2
等。不同参数的维度列表用
","
分隔。输入/输出参数用"->"
分隔。如果在一个签名中使用相同的维度名称,则会强制相应的维度具有相同的大小(或可广播的大小)。
签名的正式语法如下:
<Signature> ::= <Input arguments> "->" <Output arguments>
<Input arguments> ::= <Argument list>
<Output arguments> ::= <Argument list>
<Argument list> ::= nil | <Argument> | <Argument> "," <Argument list>
<Argument> ::= "(" <Core dimension list> ")"
<Core dimension list> ::= nil | <Dimension name> |
<Dimension name> "," <Core dimension list>
<Dimension name> ::= valid Python variable name
备注
所有引号仅为清晰起见。
共享相同名称的核心维度必须是可广播的,就像我们上面例子中的两个
i
一样。每个维度名称通常对应于基本函数实现中的一个循环级别。空白符将被忽略。
以下是一些签名的示例:
加法 |
|
|
内积1d |
|
|
求和1d |
|
|
点积2d |
|
矩阵乘法 |
外积内积 |
|
沿最后一个维度求内积,沿倒数第二个维度求外积,其余维度进行循环/广播。 |
实现基本函数的 C-API#
当前接口保持不变,PyUFunc_FromFuncAndData
仍然可用于实现由标量基本函数组成的(专门的)ufunc。
可以使用 PyUFunc_FromFuncAndDataAndSignature
声明一个更通用的 ufunc。参数列表与 PyUFunc_FromFuncAndData
相同,额外增加一个参数,将签名指定为 C 字符串。
此外,回调函数类型与之前相同,为 void (*foo)(char **args, intp *dimensions, intp *steps, void *func)
。调用时,args
是一个长度为 nargs
的列表,包含所有输入/输出参数的数据。对于标量基本函数,steps
的长度也为 nargs
,表示参数使用的步长。 dimensions
是指向单个整数的指针,定义要循环的轴的大小。
对于非平凡签名,dimensions
也会包含核心维度的大小,从第二个条目开始。每个唯一的维度名称只提供一个大小,并且大小根据维度名称在签名中首次出现的顺序给出。
steps
的前 nargs
个元素与标量 ufunc 相同。后续元素按顺序包含所有参数所有核心维度的步长。
例如,考虑一个签名是 (i,j),(i)->()
的 ufunc。在这种情况下,args
将包含三个指向输入/输出数组 a
、b
、c
数据的指针。此外,dimensions
将是 [N, I, J]
,以定义循环的大小 N
以及核心维度 i
和 j
的大小 I
和 J
。最后,steps
将是 [a_N, b_N, c_N, a_i, a_j, b_i]
,包含所有必要的步长。