广义通用函数 API#
通常不仅需要对标量执行函数循环,还需要对向量(或数组)执行函数循环.NumPy 通过推广通用函数(ufuncs)来实现这一概念.在常规 ufuncs 中,基本函数仅限于逐元素操作,而广义版本(gufuncs)支持"子数组"到"子数组"的操作.Perl 向量库 PDL 提供了类似的功能,并且其术语在以下内容中重复使用.
每个广义 ufunc 都具有与之关联的信息,该信息声明输入的"核心"维度是什么,以及输出的相应维度是什么(逐元素 ufuncs 具有零核心维度).所有参数的核心维度列表称为 ufunc 的"签名".例如,ufunc numpy.add 具有签名 (),()->() ,定义了两个标量输入和一个标量输出.
另一个例子是函数 inner1d(a, b) ,其签名为 (i),(i)->() .这沿每个输入的最后一个轴应用内积,但保持其余索引不变.例如,如果 a 的形状为 (3, 5, N) ,而 b 的形状为 (5, N) ,则这将返回形状为 (3,5) 的输出.底层基本函数被调用 3 * 5 次.在签名中,我们为每个输入指定一个核心维度 (i) ,为输出指定零个核心维度 () ,因为它接受两个一维数组并返回一个标量.通过使用相同的名称 i ,我们指定两个对应的维度应具有相同的大小.
超出核心维度的维度称为"循环"维度.在上面的例子中,这对应于 (3, 5) .
签名确定每个输入/输出数组的维度如何拆分为核心维度和循环维度:
签名中的每个维度都与相应传入数组的维度匹配,从形状元组的末尾开始.这些是核心维度,它们必须存在于数组中,否则将引发错误.
在签名中分配给相同标签的核心维度(例如,
inner1d的(i),(i)->()中的i)必须具有完全匹配的大小,不执行广播.从所有输入中删除核心维度,并将剩余的维度一起广播,从而定义循环维度.
每个输出的形状由循环维度加上输出的核心维度决定
通常,输出中所有核心维度的大小将由输入数组中具有相同标签的核心维度的大小决定.这不是必需的,并且可以定义一个标签首次出现在输出中的签名,尽管在调用此类函数时必须采取一些预防措施.一个例子是函数 euclidean_pdist(a) ,其签名为 (n,d)->(p) ,给定一个 n d 维向量数组,计算它们之间所有唯一的成对欧几里得距离.因此,输出维度 p 必须等于 n * (n - 1) / 2 ,但默认情况下,调用者有责任传入大小正确的输出数组.如果无法从传入的输入或输出数组确定输出的核心维度的大小,则会引发错误.可以通过定义一个 PyUFunc_ProcessCoreDimsFunc 函数并将其分配给 PyUFuncObject 结构的 proces_core_dims_func 字段来更改此设置.有关更多详细信息,请参见下文.
注意:在 NumPy 1.10.0 之前,检查不那么严格:通过根据需要将 1 添加到形状来创建缺少的核心维度,将具有相同标签的核心维度一起广播,并创建大小为 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 | <Core dimension> |
<Core dimension> "," <Core dimension list>
<Core dimension> ::= <Dimension name> <Dimension modifier>
<Dimension name> ::= valid Python variable name | valid integer
<Dimension modifier> ::= nil | "?"
注意:
所有引号仅为清晰起见.
共享相同名称的未修改核心维度必须具有相同的大小.每个维度名称通常对应于基本函数实现中的一个循环级别.
空格将被忽略.
作为维度名称的整数会将该维度冻结为该值.
如果名称带有"?"修饰符后缀,则该维度仅当它存在于共享它的所有输入和输出上时才是核心维度;否则它将被忽略(并替换为基本函数的大小为 1 的维度).
以下是一些签名示例:
名称 |
签名 |
常用用法 |
|---|---|---|
add |
|
二元 ufunc |
sum1d |
|
缩减 |
inner1d |
|
向量-向量乘法 |
matmat |
|
矩阵乘法 |
vecmat |
|
向量-矩阵乘法 |
matvec |
|
矩阵-向量乘法 |
matmul |
|
以上四种用法的组合 |
outer_inner |
|
内积在最后一个维度上,外积在倒数第二个维度上,并在其余维度上循环/广播. |
cross1d |
|
叉积,其中最后一个维度被冻结并且必须为 3 |
最后一个是冻结核心维度的实例,可用于提高 ufunc 性能
用于实现基本函数的 C-API#
当前接口保持不变,并且仍然可以使用 PyUFunc_FromFuncAndData 来实现(专门的)ufunc,该 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] ,包含所有必要的步幅.
自定义核心维度尺寸处理#
PyUFunc_ProcessCoreDimsFunc 类型的可选函数存储在 ufunc 的 process_core_dims_func 属性上,它为 ufunc 的作者提供了一个"钩子",可以进入传递给 ufunc 的数组的核心维度的处理过程.这个 "钩子" 的两个主要用途是:
检查ufunc所需的核心维度约束是否满足(如果未满足,则设置异常).
为任何未由输入数组确定的输出核心维度计算输出形状.
作为第一个用途的示例,考虑具有签名 (n)->(2) 的广义 ufunc minmax ,它同时计算序列的最小值和最大值.它应该要求 n > 0 ,因为长度为 0 的序列的最小值和最大值没有意义.在这种情况下,ufunc 作者可以像这样定义函数:
int minmax_process_core_dims(PyUFuncObject ufunc, npy_intp *core_dim_sizes) { npy_intp n = core_dim_sizes[0]; if (n == 0) { PyExc_SetString("minmax requires the core dimension " "to be at least 1."); return -1; } return 0; }
在这种情况下,数组 core_dim_sizes 的长度将为 2.数组中的第二个值将始终为 2,因此函数无需检查它.核心维度 n 存储在第一个元素中.如果函数发现 n 为 0,则会设置异常并返回 -1.
"钩子"的第二个用途是在调用者未提供输出数组且输出的一个或多个核心维度也不是输入核心维度时,计算输出数组的大小.如果 ufunc 没有在 process_core_dims_func 属性上定义函数,则未指定的输出核心维度大小将导致引发异常.通过 process_core_dims_func 提供的"钩子",ufunc的作者可以将输出大小设置为适合该ufunc的任何值.
在传递给"钩子"函数的数组中,未由输入确定的核心维度通过在 core_dim_sizes 数组中具有值 -1 来指示.该函数可以将 -1 替换为适合 ufunc 的任何值,基于输入数组中出现的核心维度.
警告
该函数绝不能更改输入中不是 -1 的 core_dim_sizes 中的值.更改不是 -1 的值通常会导致 ufunc 产生不正确的输出,并可能导致 Python 解释器崩溃.
例如,考虑广义 ufunc conv1d ,其基本函数计算两个长度分别为 m 和 n 的一维数组 x 和 y 的"完整"卷积.此卷积的输出长度为 m + n - 1 .要将其实现为广义 ufunc,签名设置为 (m),(n)->(p) ,并且在 "钩子" 函数中,如果发现核心维度 p 为 -1,则将其替换为 m + n - 1 .如果 p 不为 -1,则必须验证给定值是否等于 m + n - 1 .如果不是,则该函数必须设置异常并返回 -1.为了获得有意义的结果,该操作还要求 m + n 至少为 1,即两个输入都不能为长度 0.
这是在代码中的样子:
int conv1d_process_core_dims(PyUFuncObject *ufunc, npy_intp *core_dim_sizes) { // core_dim_sizes will hold the core dimensions [m, n, p]. // p will be -1 if the caller did not provide the out argument. npy_intp m = core_dim_sizes[0]; npy_intp n = core_dim_sizes[1]; npy_intp p = core_dim_sizes[2]; npy_intp required_p = m + n - 1; if (m == 0 && n == 0) { // Disallow both inputs having length 0. PyErr_SetString(PyExc_ValueError, "conv1d: both inputs have core dimension 0; the function " "requires that at least one input has size greater than 0."); return -1; } if (p == -1) { // Output array was not given in the call of the ufunc. // Set the correct output size here. core_dim_sizes[2] = required_p; return 0; } // An output array *was* given. Validate its core dimension. if (p != required_p) { PyErr_Format(PyExc_ValueError, "conv1d: the core dimension p of the out parameter " "does not equal m + n - 1, where m and n are the " "core dimensions of the inputs x and y; got m=%zd " "and n=%zd so p must be %zd, but got p=%zd.", m, n, required_p, p); return -1; } return 0; }