python - 如何通过 cython 将 numpy 数组列表传递给 C++

Question

我想将二维 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_of_array使用 list[float[:,:]] , 但也不起作用。

Answer 1

我将稍微更改您的函数的签名:

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

这导致以下 c++ 接口(interface)/代码(为方便起见，我使用 C-verbatim-code Cython 的功能>=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)

有几点值得注意:

• 您需要将列表的元素强制转换为实现缓冲区协议(protocol)的内容，否则 &ar[0] 显然无法工作，因为 Cython 会期望 ar[0]成为一个 Python 对象。顺便说一句，这就是您错过的。
• 我选择了 Cython 的内存 View (即 double[::1])作为强制转换的目标。 np.ndarray 的优点是它也可以与 array.array 一起使用，并且还会自动检查数据是否连续(这就是 的含义)::1).
• 一个常见的陷阱是为一个空的 ndarray 访问 ar[0] - 这种访问必须受到保护。
• 这段代码不是线程安全的。另一个线程可能会使指针无效，例如通过就地调整 numpy 数组的大小或完全删除 numpy 数组。
• 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!

---

线程安全版本

上面的代码也可以写成线程安全的方式。可能出现的问题是:

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

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

%%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)

开销很小:将内存 View 添加到列表 - 安全的代价。

---

释放吉尔

最后一个改进:gil可以在计算cpp_fun时释放，这意味着我们必须将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。