如何通过 cython 将 numpy 数组列表传递给 c++

Posted 2023-02-23

【中文标题】如何通过 cython 将 numpy 数组列表传递给 c++

【英文标题】：how to pass list of numpy arrays to c++ via cython

【发布时间】：2018-09-12 06:44:46

【问题描述】：

我想将 2d numpy 数组列表传递给 c++ 函数。我的第一个想法是使用std::vector<float *> 接收数组列表，但我找不到传递列表的方法。

c++ 函数如下所示：

double cpp_func(const std::vector<const float*>& vec) 
    return 0.0;

Cython 函数是这样的：

cpdef py_func(list list_of_array):
    cdef vector[float*] vec
    cdef size_t i
    cdef size_t n = len(list_of_array)
    for i in range(n):
        vec.push_back(&list_of_array[i][0][0])  # error: Cannot take address of Python object
    return cpp_func(vec)

我尝试过使用list[float[:,:]] 声明list_of_array，但也不起作用。

【问题讨论】：

您的cpp_func 的接口缺少有关传递的numpy 数组长度的信息。一旦您尝试使用信息（而不是简单地返回 0.0）就会出现问题。

【参考方案1】：

我会稍微改变你的函数的签名：

对于每个 numpy 数组，函数还需要知道该数组中元素的数量 数据是double * 而不是float *，因为这对应于默认的np.float-type。但这可以根据您的需要进行调整。

这导致以下 c++ 接口/代码（为方便起见，我为 Cython 使用 C-verbatim-code 功能>=0.28）：

%%cython --cplus -c=-std=c++11
from libcpp.vector cimport vector
cdef extern from *:
    """
    struct Numpy1DArray
        double *ptr;
        int   size;
    ;

    static double cpp_func(const std::vector<Numpy1DArray> &vec)
          // Fill with life to see, that it really works:
          double res = 0.0;
          for(const auto &a : vec)
              if(a.size>0)
                res+=a.ptr[0];
          
          return res;
       
    """
    cdef struct Numpy1DArray:
        double *ptr
        int size          
    double cpp_func(const vector[Numpy1DArray] &vec)
    ...

struct Numpy1DArray 只是捆绑了 np 数组所需的信息，因为这不仅仅是指向连续数据的指针。

---

朴素版

现在，编写包装函数非常简单：

%%cython --cplus -c=-std=c++11
....
def call_cpp_func(list_of_arrays):
  cdef Numpy1DArray ar_descr
  cdef vector[Numpy1DArray] vec
  cdef double[::1] ar
  for ar in list_of_arrays:  # coerse elements to double[::1]
        ar_descr.size = ar.size
        if ar.size > 0:
            ar_descr.ptr = &ar[0]
        else:
            ar_descr.ptr = NULL  # set to nullptr
        vec.push_back(ar_descr)

  return cpp_func(vec)

有几点值得注意：

您需要将列表的元素强制转换为实现缓冲区协议的东西，否则&ar[0] 显然不起作用，因为 Cython 会期望 ar[0] 成为 Python 对象。顺便说一句，这就是你错过的。 我选择了 Cython 的内存视图（即double[::1]）作为强制目标。与np.ndarray 相比的优势在于它也可以与array.array 一起使用，并且还会自动检查数据是否连续（这就是::1 的含义）。 一个常见的陷阱是访问ar[0] 以获得一个空的ndarray - 此访问必须受到保护。 此代码不是线程安全的。另一个线程可以使指针无效，例如通过就地调整 numpy-arrays 的大小或完全删除 numpy-arrays。 IIRC，对于 Python 2，您必须 cimport array 才能使代码与 array.array 一起使用。

最后，这是一个测试，代码是否有效（列表中还有一个array.array 来说明这一点）：

import array
import numpy as np
lst = (np.full(3, 1.0), np.full(0, 2.0), array.array('d', [2.0]))
call_cpp_func(lst)  # 3.0 as expected!

---

线程安全版本

上面的代码也可以用线程安全的方式编写。可能的问题是：

另一个线程可以通过调用 list_of_arrays.clear() 来触发删除 numpy-arrays - 之后可能没有更多的数组引用，它们将被删除。这意味着只要我们使用指针，我们就需要保留对每个输入数组的引用。 另一个线程可以调整数组的大小，从而使指针无效。这意味着我们必须使用缓冲区协议 - 它的__getbuffer__ 锁定缓冲区，因此一旦我们完成计算，它就不能失效并通过__releasebuffer__ 释放缓冲区。

Cython 的内存视图可用于锁定缓冲区并保持对输入数组的引用：

%%cython --cplus -c=-std=c++11
....
def call_cpp_func_safe(list_of_arrays):
     cdef Numpy1DArray ar_descr
     cdef vector[Numpy1DArray] vec
     cdef double[::1] ar
     cdef list stay_alive = []
     for ar in list_of_arrays:  # coerse elements to double[::1]
            stay_alive.append(ar)    # keep arrays alive and locked
            ar_descr.size = ar.size
            if ar.size > 0:
                ar_descr.ptr = &ar[0]
            else:
                ar_descr.ptr = NULL  # set to nullptr
            vec.push_back(ar_descr)
     return cpp_func(vec)

开销很小：将内存视图添加到列表中 - 安全的代价。

---

释放吉尔

最后一个改进：计算cpp_fun时可以释放gil，这意味着我们必须将cpp_func作为nogil导入并释放它为什么调用函数：

%%cython --cplus -c=-std=c++11
from libcpp.vector cimport vector
cdef extern from *:
    ....          
    double cpp_func(const vector[Numpy1DArray] &vec) nogil
...

def call_cpp_func(list_of_arrays):
...
    with nogil:
        result = cpp_func(vec)       
    return result

Cython 会发现 result 是 double 类型，因此可以在调用 cpp_func 时释放 gil。

【讨论】：

谢谢，它成功了。我认为cdef double[::1] ar是让python知道列表中元素类型的关键。