编写自己的 ufunc#
创建新的通用函数#
在阅读本节之前,建议您先熟悉 Python C 扩展的基础知识,方法是阅读/浏览 扩展和嵌入 Python 解释器 第 1 部分以及 如何扩展 NumPy 中的教程。
umath 模块是一个计算机生成的 C 模块,它创建了许多 ufunc。它提供了许多关于如何创建通用函数的示例。创建您自己的 ufunc 来利用 ufunc 机制也并不困难。假设您有一个函数,您希望对其输入逐元素进行操作。通过创建一个新的 ufunc,您将获得一个处理以下功能的函数:
广播
N 维循环
自动类型转换,并最大限度地减少内存使用
可选输出数组
创建自己的 ufunc 并不难。所需做的只是为每个您想要支持的数据类型创建一个 1 维循环。每个 1 维循环必须具有特定的签名,并且只能使用固定大小数据类型的 ufunc。用于创建新的 ufunc 以处理内置数据类型的函数调用如下所示。用于注册用户定义数据类型的 ufunc 的机制有所不同。
在接下来的几个部分中,我们将提供一些示例代码,这些代码可以轻松修改以创建您自己的 ufunc。这些示例是 logit 函数(统计建模中常见的函数)的逐步完善或复杂的版本。logit 也很有趣,因为由于 IEEE 标准(特别是 IEEE 754)的魔力,下面创建的所有 logit 函数都自动具有以下行为。
>>> logit(0)
-inf
>>> logit(1)
inf
>>> logit(2)
nan
>>> logit(-2)
nan
这很棒,因为函数编写者无需手动传播 inf 或 nan。
非 ufunc 扩展示例#
为了进行比较并让读者全面了解,我们提供了一个简单的 logit
C 扩展实现,该实现不使用 numpy。
为此,我们需要两个文件。第一个是包含实际代码的 C 文件,第二个是用于创建模块的 setup.py
文件。
#define PY_SSIZE_T_CLEAN #include <Python.h> #include <math.h> /* * spammodule.c * This is the C code for a non-numpy Python extension to * define the logit function, where logit(p) = log(p/(1-p)). * This function will not work on numpy arrays automatically. * numpy.vectorize must be called in python to generate * a numpy-friendly function. * * Details explaining the Python-C API can be found under * 'Extending and Embedding' and 'Python/C API' at * docs.python.org . */ /* This declares the logit function */ static PyObject *spam_logit(PyObject *self, PyObject *args); /* * This tells Python what methods this module has. * See the Python-C API for more information. */ static PyMethodDef SpamMethods[] = { {"logit", spam_logit, METH_VARARGS, "compute logit"}, {NULL, NULL, 0, NULL} }; /* * This actually defines the logit function for * input args from Python. */ static PyObject *spam_logit(PyObject *self, PyObject *args) { double p; /* This parses the Python argument into a double */ if(!PyArg_ParseTuple(args, "d", &p)) { return NULL; } /* THE ACTUAL LOGIT FUNCTION */ p = p/(1-p); p = log(p); /*This builds the answer back into a python object */ return Py_BuildValue("d", p); } /* This initiates the module using the above definitions. */ static struct PyModuleDef moduledef = { PyModuleDef_HEAD_INIT, "spam", NULL, -1, SpamMethods, NULL, NULL, NULL, NULL }; PyMODINIT_FUNC PyInit_spam(void) { PyObject *m; m = PyModule_Create(&moduledef); if (!m) { return NULL; } return m; }
要使用 setup.py file
,请将 setup.py
和 spammodule.c
放置在同一个文件夹中。然后 python setup.py build
将构建要导入的模块,或者 python setup.py install
将模块安装到您的 site-packages 目录中。
''' setup.py file for spammodule.c Calling $python setup.py build_ext --inplace will build the extension library in the current file. Calling $python setup.py build will build a file that looks like ./build/lib*, where lib* is a file that begins with lib. The library will be in this file and end with a C library extension, such as .so Calling $python setup.py install will install the module in your site-packages file. See the setuptools section 'Building Extension Modules' at setuptools.pypa.io for more information. ''' from setuptools import setup, Extension import numpy as np module1 = Extension('spam', sources=['spammodule.c']) setup(name='spam', version='1.0', ext_modules=[module1])
将 spam 模块导入到 python 后,您可以通过 spam.logit
调用 logit。请注意,上面使用的函数不能原样应用于 numpy 数组。为此,我们必须对其调用 numpy.vectorize
。例如,如果在包含 spam 库的文件中打开了一个 python 解释器,或者 spam 已被安装,则可以执行以下命令:
>>> import numpy as np
>>> import spam
>>> spam.logit(0)
-inf
>>> spam.logit(1)
inf
>>> spam.logit(0.5)
0.0
>>> x = np.linspace(0,1,10)
>>> spam.logit(x)
TypeError: only length-1 arrays can be converted to Python scalars
>>> f = np.vectorize(spam.logit)
>>> f(x)
array([ -inf, -2.07944154, -1.25276297, -0.69314718, -0.22314355,
0.22314355, 0.69314718, 1.25276297, 2.07944154, inf])
生成的 LOGIT 函数速度不快!numpy.vectorize
只是循环遍历 spam.logit
。循环在 C 级别完成,但 numpy 数组不断被解析和重建。这是很昂贵的。当作者将 numpy.vectorize(spam.logit)
与下面构建的 logit ufunc 进行比较时,logit ufunc 的速度几乎快了 4 倍。当然,具体的速度提升可能更大或更小,具体取决于函数的性质。
一个 dtype 的 NumPy ufunc 示例#
为简单起见,我们提供了一个单个 dtype 的 ufunc,即 'f8'
double
。与上一节一样,我们首先给出 .c
文件,然后给出用于创建包含 ufunc 的模块的 setup.py
文件。
对应于 ufunc 的实际计算的代码部分用 /\* BEGIN main ufunc computation \*/
和 /\* END main ufunc computation \*/
标记。这两行之间的代码是创建您自己的 ufunc 时需要主要更改的部分。
#define PY_SSIZE_T_CLEAN #include <Python.h> #include "numpy/ndarraytypes.h" #include "numpy/ufuncobject.h" #include "numpy/npy_3kcompat.h" #include <math.h> /* * single_type_logit.c * This is the C code for creating your own * NumPy ufunc for a logit function. * * In this code we only define the ufunc for * a single dtype. The computations that must * be replaced to create a ufunc for * a different function are marked with BEGIN * and END. * * Details explaining the Python-C API can be found under * 'Extending and Embedding' and 'Python/C API' at * docs.python.org . */ static PyMethodDef LogitMethods[] = { {NULL, NULL, 0, NULL} }; /* The loop definition must precede the PyMODINIT_FUNC. */ static void double_logit(char **args, const npy_intp *dimensions, const npy_intp *steps, void *data) { npy_intp i; npy_intp n = dimensions[0]; char *in = args[0], *out = args[1]; npy_intp in_step = steps[0], out_step = steps[1]; double tmp; for (i = 0; i < n; i++) { /* BEGIN main ufunc computation */ tmp = *(double *)in; tmp /= 1 - tmp; *((double *)out) = log(tmp); /* END main ufunc computation */ in += in_step; out += out_step; } } /* This a pointer to the above function */ PyUFuncGenericFunction funcs[1] = {&double_logit}; /* These are the input and return dtypes of logit.*/ static const char types[2] = {NPY_DOUBLE, NPY_DOUBLE}; static struct PyModuleDef moduledef = { PyModuleDef_HEAD_INIT, "npufunc", NULL, -1, LogitMethods, NULL, NULL, NULL, NULL }; PyMODINIT_FUNC PyInit_npufunc(void) { PyObject *m, *logit, *d; import_array(); import_umath(); m = PyModule_Create(&moduledef); if (!m) { return NULL; } logit = PyUFunc_FromFuncAndData(funcs, NULL, types, 1, 1, 1, PyUFunc_None, "logit", "logit_docstring", 0); d = PyModule_GetDict(m); PyDict_SetItemString(d, "logit", logit); Py_DECREF(logit); return m; }
这是一个用于上述代码的 setup.py file
。与之前一样,可以通过在命令提示符下调用 python setup.py build
来构建模块,或者通过 python setup.py install
安装到 site-packages。模块也可以使用 python setup.py build_ext --inplace
放入本地文件夹(例如下面的 npufunc_directory
)中。
''' setup.py file for single_type_logit.c Note that since this is a numpy extension we add an include_dirs=[get_include()] so that the extension is built with numpy's C/C++ header files. Calling $python setup.py build_ext --inplace will build the extension library in the npufunc_directory. Calling $python setup.py build will build a file that looks like ./build/lib*, where lib* is a file that begins with lib. The library will be in this file and end with a C library extension, such as .so Calling $python setup.py install will install the module in your site-packages file. See the setuptools section 'Building Extension Modules' at setuptools.pypa.io for more information. ''' from setuptools import setup, Extension from numpy import get_include npufunc = Extension('npufunc', sources=['single_type_logit.c'], include_dirs=[get_include()]) setup(name='npufunc', version='1.0', ext_modules=[npufunc])
安装上述内容后,可以按如下方式导入和使用它。
>>> import numpy as np
>>> import npufunc
>>> npufunc.logit(0.5)
np.float64(0.0)
>>> a = np.linspace(0,1,5)
>>> npufunc.logit(a)
array([ -inf, -1.09861229, 0. , 1.09861229, inf])
多个 dtype 的 NumPy ufunc 示例#
最后,我们提供了一个完整 ufunc 的示例,其中包含半浮点数、浮点数、双精度数和长双精度数的内部循环。与前面的部分一样,我们首先给出 .c
文件,然后给出相应的 setup.py
文件。
对应于 ufunc 的实际计算的代码部分用 /\* BEGIN main ufunc computation \*/
和 /\* END main ufunc computation \*/
标记。这两行之间的代码是创建您自己的 ufunc 时需要主要更改的部分。
#define PY_SSIZE_T_CLEAN #include <Python.h> #include "numpy/ndarraytypes.h" #include "numpy/ufuncobject.h" #include "numpy/halffloat.h" #include <math.h> /* * multi_type_logit.c * This is the C code for creating your own * NumPy ufunc for a logit function. * * Each function of the form type_logit defines the * logit function for a different numpy dtype. Each * of these functions must be modified when you * create your own ufunc. The computations that must * be replaced to create a ufunc for * a different function are marked with BEGIN * and END. * * Details explaining the Python-C API can be found under * 'Extending and Embedding' and 'Python/C API' at * docs.python.org . * */ static PyMethodDef LogitMethods[] = { {NULL, NULL, 0, NULL} }; /* The loop definitions must precede the PyMODINIT_FUNC. */ static void long_double_logit(char **args, const npy_intp *dimensions, const npy_intp *steps, void *data) { npy_intp i; npy_intp n = dimensions[0]; char *in = args[0], *out = args[1]; npy_intp in_step = steps[0], out_step = steps[1]; long double tmp; for (i = 0; i < n; i++) { /* BEGIN main ufunc computation */ tmp = *(long double *)in; tmp /= 1 - tmp; *((long double *)out) = logl(tmp); /* END main ufunc computation */ in += in_step; out += out_step; } } static void double_logit(char **args, const npy_intp *dimensions, const npy_intp *steps, void *data) { npy_intp i; npy_intp n = dimensions[0]; char *in = args[0], *out = args[1]; npy_intp in_step = steps[0], out_step = steps[1]; double tmp; for (i = 0; i < n; i++) { /* BEGIN main ufunc computation */ tmp = *(double *)in; tmp /= 1 - tmp; *((double *)out) = log(tmp); /* END main ufunc computation */ in += in_step; out += out_step; } } static void float_logit(char **args, const npy_intp *dimensions, const npy_intp *steps, void *data) { npy_intp i; npy_intp n = dimensions[0]; char *in = args[0], *out = args[1]; npy_intp in_step = steps[0], out_step = steps[1]; float tmp; for (i = 0; i < n; i++) { /* BEGIN main ufunc computation */ tmp = *(float *)in; tmp /= 1 - tmp; *((float *)out) = logf(tmp); /* END main ufunc computation */ in += in_step; out += out_step; } } static void half_float_logit(char **args, const npy_intp *dimensions, const npy_intp *steps, void *data) { npy_intp i; npy_intp n = dimensions[0]; char *in = args[0], *out = args[1]; npy_intp in_step = steps[0], out_step = steps[1]; float tmp; for (i = 0; i < n; i++) { /* BEGIN main ufunc computation */ tmp = npy_half_to_float(*(npy_half *)in); tmp /= 1 - tmp; tmp = logf(tmp); *((npy_half *)out) = npy_float_to_half(tmp); /* END main ufunc computation */ in += in_step; out += out_step; } } /*This gives pointers to the above functions*/ PyUFuncGenericFunction funcs[4] = {&half_float_logit, &float_logit, &double_logit, &long_double_logit}; static const char types[8] = {NPY_HALF, NPY_HALF, NPY_FLOAT, NPY_FLOAT, NPY_DOUBLE, NPY_DOUBLE, NPY_LONGDOUBLE, NPY_LONGDOUBLE}; static struct PyModuleDef moduledef = { PyModuleDef_HEAD_INIT, "npufunc", NULL, -1, LogitMethods, NULL, NULL, NULL, NULL }; PyMODINIT_FUNC PyInit_npufunc(void) { PyObject *m, *logit, *d; import_array(); import_umath(); m = PyModule_Create(&moduledef); if (!m) { return NULL; } logit = PyUFunc_FromFuncAndData(funcs, NULL, types, 4, 1, 1, PyUFunc_None, "logit", "logit_docstring", 0); d = PyModule_GetDict(m); PyDict_SetItemString(d, "logit", logit); Py_DECREF(logit); return m; }
这是一个用于上述代码的 setup.py file
。与之前一样,可以通过在命令提示符下调用 python setup.py build
来构建模块,或者通过 python setup.py install
安装到 site-packages。
''' setup.py file for multi_type_logit.c Note that since this is a numpy extension we add an include_dirs=[get_include()] so that the extension is built with numpy's C/C++ header files. Furthermore, we also have to include the npymath lib for half-float d-type. Calling $python setup.py build_ext --inplace will build the extension library in the current file. Calling $python setup.py build will build a file that looks like ./build/lib*, where lib* is a file that begins with lib. The library will be in this file and end with a C library extension, such as .so Calling $python setup.py install will install the module in your site-packages file. See the setuptools section 'Building Extension Modules' at setuptools.pypa.io for more information. ''' from setuptools import setup, Extension from numpy import get_include from os import path path_to_npymath = path.join(get_include(), '..', 'lib') npufunc = Extension('npufunc', sources=['multi_type_logit.c'], include_dirs=[get_include()], # Necessary for the half-float d-type. library_dirs=[path_to_npymath], libraries=["npymath"]) setup(name='npufunc', version='1.0', ext_modules=[npufunc])
安装上述内容后,可以按如下方式导入和使用它。
>>> import numpy as np
>>> import npufunc
>>> npufunc.logit(0.5)
np.float64(0.0)
>>> a = np.linspace(0,1,5)
>>> npufunc.logit(a)
array([ -inf, -1.09861229, 0. , 1.09861229, inf])
具有多个参数/返回值的 NumPy ufunc 示例#
我们的最后一个示例是一个具有多个参数的 ufunc。它是针对单个 dtype 数据的 logit ufunc 代码的修改版本。我们计算 (A * B, logit(A * B))
。
我们只给出 C 代码,因为 setup.py
文件与 一个 dtype 的 NumPy ufunc 示例 中的 setup.py
文件完全相同,只是将以下行:
npufunc = Extension('npufunc', sources=['single_type_logit.c'], include_dirs=[get_include()])
替换为:
npufunc = Extension('npufunc', sources=['multi_arg_logit.c'], include_dirs=[get_include()])
C 文件如下所示。生成的 ufunc 接受两个参数 A
和 B
。它返回一个元组,其第一个元素是 A * B
,第二个元素是 logit(A * B)
。请注意,它自动支持广播,以及 ufunc 的所有其他属性。
#define PY_SSIZE_T_CLEAN #include <Python.h> #include "numpy/ndarraytypes.h" #include "numpy/ufuncobject.h" #include "numpy/halffloat.h" #include <math.h> /* * multi_arg_logit.c * This is the C code for creating your own * NumPy ufunc for a multiple argument, multiple * return value ufunc. The places where the * ufunc computation is carried out are marked * with comments. * * Details explaining the Python-C API can be found under * 'Extending and Embedding' and 'Python/C API' at * docs.python.org. */ static PyMethodDef LogitMethods[] = { {NULL, NULL, 0, NULL} }; /* The loop definition must precede the PyMODINIT_FUNC. */ static void double_logitprod(char **args, const npy_intp *dimensions, const npy_intp *steps, void *data) { npy_intp i; npy_intp n = dimensions[0]; char *in1 = args[0], *in2 = args[1]; char *out1 = args[2], *out2 = args[3]; npy_intp in1_step = steps[0], in2_step = steps[1]; npy_intp out1_step = steps[2], out2_step = steps[3]; double tmp; for (i = 0; i < n; i++) { /* BEGIN main ufunc computation */ tmp = *(double *)in1; tmp *= *(double *)in2; *((double *)out1) = tmp; *((double *)out2) = log(tmp / (1 - tmp)); /* END main ufunc computation */ in1 += in1_step; in2 += in2_step; out1 += out1_step; out2 += out2_step; } } /*This a pointer to the above function*/ PyUFuncGenericFunction funcs[1] = {&double_logitprod}; /* These are the input and return dtypes of logit.*/ static const char types[4] = {NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE}; static struct PyModuleDef moduledef = { PyModuleDef_HEAD_INIT, "npufunc", NULL, -1, LogitMethods, NULL, NULL, NULL, NULL }; PyMODINIT_FUNC PyInit_npufunc(void) { PyObject *m, *logit, *d; import_array(); import_umath(); m = PyModule_Create(&moduledef); if (!m) { return NULL; } logit = PyUFunc_FromFuncAndData(funcs, NULL, types, 1, 2, 2, PyUFunc_None, "logit", "logit_docstring", 0); d = PyModule_GetDict(m); PyDict_SetItemString(d, "logit", logit); Py_DECREF(logit); return m; }
具有结构化数组 dtype 参数的 NumPy ufunc 示例#
此示例演示了如何为结构化数组 dtype 创建 ufunc。对于示例,我们展示了一个用于添加两个 dtype 为 'u8,u8,u8'
的数组的简单 ufunc。该过程与其他示例略有不同,因为对 PyUFunc_FromFuncAndData
的调用不会完全注册自定义 dtype 和结构化数组 dtype 的 ufunc。我们需要再调用 PyUFunc_RegisterLoopForDescr
来完成 ufunc 的设置。
我们只给出 C 代码,因为 setup.py
文件与 一个 dtype 的 NumPy ufunc 示例 中的 setup.py
文件完全相同,只是将以下行:
npufunc = Extension('npufunc', sources=['single_type_logit.c'], include_dirs=[get_include()])
替换为:
npufunc = Extension('npufunc', sources=['add_triplet.c'], include_dirs=[get_include()])
C 文件如下所示。
#define PY_SSIZE_T_CLEAN #include <Python.h> #include "numpy/ndarraytypes.h" #include "numpy/ufuncobject.h" #include "numpy/npy_3kcompat.h" #include <math.h> /* * add_triplet.c * This is the C code for creating your own * NumPy ufunc for a structured array dtype. * * Details explaining the Python-C API can be found under * 'Extending and Embedding' and 'Python/C API' at * docs.python.org. */ static PyMethodDef StructUfuncTestMethods[] = { {NULL, NULL, 0, NULL} }; /* The loop definition must precede the PyMODINIT_FUNC. */ static void add_uint64_triplet(char **args, const npy_intp *dimensions, const npy_intp *steps, void *data) { npy_intp i; npy_intp is1 = steps[0]; npy_intp is2 = steps[1]; npy_intp os = steps[2]; npy_intp n = dimensions[0]; uint64_t *x, *y, *z; char *i1 = args[0]; char *i2 = args[1]; char *op = args[2]; for (i = 0; i < n; i++) { x = (uint64_t *)i1; y = (uint64_t *)i2; z = (uint64_t *)op; z[0] = x[0] + y[0]; z[1] = x[1] + y[1]; z[2] = x[2] + y[2]; i1 += is1; i2 += is2; op += os; } } /* This a pointer to the above function */ PyUFuncGenericFunction funcs[1] = {&add_uint64_triplet}; /* These are the input and return dtypes of add_uint64_triplet. */ static const char types[3] = {NPY_UINT64, NPY_UINT64, NPY_UINT64}; static struct PyModuleDef moduledef = { PyModuleDef_HEAD_INIT, "struct_ufunc_test", NULL, -1, StructUfuncTestMethods, NULL, NULL, NULL, NULL }; PyMODINIT_FUNC PyInit_npufunc(void) { PyObject *m, *add_triplet, *d; PyObject *dtype_dict; PyArray_Descr *dtype; PyArray_Descr *dtypes[3]; import_array(); import_umath(); m = PyModule_Create(&moduledef); if (m == NULL) { return NULL; } /* Create a new ufunc object */ add_triplet = PyUFunc_FromFuncAndData(NULL, NULL, NULL, 0, 2, 1, PyUFunc_None, "add_triplet", "add_triplet_docstring", 0); dtype_dict = Py_BuildValue("[(s, s), (s, s), (s, s)]", "f0", "u8", "f1", "u8", "f2", "u8"); PyArray_DescrConverter(dtype_dict, &dtype); Py_DECREF(dtype_dict); dtypes[0] = dtype; dtypes[1] = dtype; dtypes[2] = dtype; /* Register ufunc for structured dtype */ PyUFunc_RegisterLoopForDescr(add_triplet, dtype, &add_uint64_triplet, dtypes, NULL); d = PyModule_GetDict(m); PyDict_SetItemString(d, "add_triplet", add_triplet); Py_DECREF(add_triplet); return m; }
返回的 ufunc 对象是一个可调用的 Python 对象。它应该放在(模块)字典中,名称与 ufunc 创建例程中 name 参数使用的名称相同。以下示例改编自 umath 模块
static PyUFuncGenericFunction atan2_functions[] = { PyUFunc_ff_f, PyUFunc_dd_d, PyUFunc_gg_g, PyUFunc_OO_O_method}; static void *atan2_data[] = { (void *)atan2f, (void *)atan2, (void *)atan2l, (void *)"arctan2"}; static const char atan2_signatures[] = { NPY_FLOAT, NPY_FLOAT, NPY_FLOAT, NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE, NPY_LONGDOUBLE, NPY_LONGDOUBLE, NPY_LONGDOUBLE NPY_OBJECT, NPY_OBJECT, NPY_OBJECT}; ... /* in the module initialization code */ PyObject *f, *dict, *module; ... dict = PyModule_GetDict(module); ... f = PyUFunc_FromFuncAndData(atan2_functions, atan2_data, atan2_signatures, 4, 2, 1, PyUFunc_None, "arctan2", "a safe and correct arctan(x1/x2)", 0); PyDict_SetItemString(dict, "arctan2", f); Py_DECREF(f); ...