NumPy: 高度なufuncを自作してみたいあなたへ - `void PyUFunc_OO_O_method()` を使いこなすためのヒント

void PyUFunc_OO_O_method() は、NumPy C-API におけるユニバーサル関数（ufunc）のループ処理を定義するための関数です。この関数は、2つの入力配列と1つの出力配列を用いて、要素単位のループ処理を実行します。ループ処理は、入力オブジェクトの __call__ メソッドを使用して実行されます。

機能

ループ処理の最適化のためのオプション引数を受け取ることができます。
入力オブジェクトの __call__ メソッドを使用して要素単位のループ処理を実行します。
2つの入力配列と1つの出力配列を処理します。

引数

flags: フラグ
userdata: ユーザーデータ
loop: ループ処理関数へのポインタ
casting: キャスティングフラグ
dtypes: 入力配列と出力配列のデータ型
ntypes: 入力配列のデータ型の数

ループ処理関数

ループ処理関数は、以下の引数を受け取ります。

userdata: ユーザーデータ
loop_count: ループ処理の反復回数
out: 出力配列
nda2: 2番目の入力配列
nda1: 最初の入力配列

ループ処理関数内では、以下の操作を実行できます。

ユーザーデータを処理する
ループ処理の制御を行う
入力配列と出力配列の要素にアクセスして操作する

例

以下の例は、2つの整数を乗算して結果を出力するユニバーサル関数を定義します。

#include <numpy/ndarray.h>
#include <numpy/ufunc.h>

static PyObject *
multiply(PyObject *self, PyObject *args)
{
  PyArrayObject *op1, *op2, *out;

  if (!PyArg_ParseTuple(args, "OOO", &op1, &op2, &out)) {
    return NULL;
  }

  if (PyArray_NDIM(op1) != 1 || PyArray_NDIM(op2) != 1 ||
      PyArray_NDIM(out) != 1) {
    PyErr_SetString(PyExc_ValueError, "Input arrays must be 1-dimensional");
    return NULL;
  }

  if (PyArray_DTYPE(op1) != PyArray_DTYPE(op2) ||
      PyArray_DTYPE(op1) != PyArray_DTYPE(out)) {
    PyErr_SetString(PyExc_ValueError, "Input arrays must have the same data type");
    return NULL;
  }

  PyUFunc_OO_O_method(PyArray_Multiply, op1, op2, out, NULL, NULL, 0);

  Py_INCREF(out);
  return out;
}

static PyMethodDef multiply_methods[] = {
  {"multiply", multiply, METH_VARARGS, "Multiply two arrays element-wise."},
  {NULL, NULL, 0, NULL}
};

PyModuleDef *
initmultiply(void)
{
  PyObject *m;

  m = PyModule_Create(&multiply_module, "multiply");
  if (m == NULL) {
    return NULL;
  }

  if (PyModule_AddFunctions(m, multiply_methods, NULL) < 0) {
    Py_DECREF(m);
    return NULL;
  }

  return m;
}

PyMODINIT_FUNC(multiply, initmultiply)

この例では、multiply 関数は3つの引数を受け取ります。

out: 出力配列
op2: 2番目の入力配列
op1: 最初の入力配列

multiply 関数は、入力配列が1次元であることと、データ型が一致していることを確認します。その後、PyUFunc_OO_O_method 関数を使用して、要素単位のループ処理を実行します。

ループ処理関数は、効率的に実装する必要があります。非効率的なループ処理関数は、パフォーマンスの低下につながる可能性があります。
PyUFunc_OO_O_method 関数は、NumPy C-API の高度な機能です。使用する前に、NumPy C-API に関する十分な知識が必要です。

NumPy C-API:

#include <numpy/ndarray.h>
#include <numpy/ufunc.h>

static int
multiply_loop(PyArrayObject *nda1, PyArrayObject *nda2, PyArrayObject *out,
             npy_intp *dimensions, npy_intp *strides, void *userdata)
{
  npy_intp *ptr1, *ptr2, *ptrout;
  npy_intp i, n;

  n = dimensions[0];

  ptr1 = (npy_intp *)PyArray_MapPtr(nda1, NULL);
  ptr2 = (npy_intp *)PyArray_MapPtr(nda2, NULL);
  ptrout = (npy_intp *)PyArray_MapPtr(out, NULL);

  for (i = 0; i < n; ++i) {
    ptrout[i] = ptr1[i] * ptr2[i];
  }

  PyArray_UnmapPtr(nda1, ptr1);
  PyArray_UnmapPtr(nda2, ptr2);
  PyArray_UnmapPtr(out, ptrout);

  return 0;
}

static PyObject *
multiply(PyObject *self, PyObject *args)
{
  PyArrayObject *op1, *op2, *out;

  if (!PyArg_ParseTuple(args, "OOO", &op1, &op2, &out)) {
    return NULL;
  }

  if (PyArray_NDIM(op1) != 1 || PyArray_NDIM(op2) != 1 ||
      PyArray_NDIM(out) != 1) {
    PyErr_SetString(PyExc_ValueError, "Input arrays must be 1-dimensional");
    return NULL;
  }

  if (PyArray_DTYPE(op1) != PyArray_DTYPE(op2) ||
      PyArray_DTYPE(op1) != PyArray_DTYPE(out)) {
    PyErr_SetString(PyExc_ValueError, "Input arrays must have the same data type");
    return NULL;
  }

  PyUFunc_OO_O_method(PyArray_Multiply, op1, op2, out, multiply_loop,
                       NULL, 0);

  Py_INCREF(out);
  return out;
}

static PyMethodDef multiply_methods[] = {
  {"multiply", multiply, METH_VARARGS, "Multiply two arrays element-wise."},
  {NULL, NULL, 0, NULL}
};

PyModuleDef *
initmultiply(void)
{
  PyObject *m;

  m = PyModule_Create(&multiply_module, "multiply");
  if (m == NULL) {
    return NULL;
  }

  if (PyModule_AddFunctions(m, multiply_methods, NULL) < 0) {
    Py_DECREF(m);
    return NULL;
  }

  return m;
}

PyMODINIT_FUNC(multiply, initmultiply)

このコードは以下の通り動作します。

multiply_loop 関数は、入力配列と出力配列の要素をループ処理します。
ループ処理内で、入力配列の要素を乗算して出力配列の要素に格納します。
multiply 関数は、入力配列と出力配列の形状とデータ型が正しいことを確認します。
PyUFunc_OO_O_method 関数を使用して、multiply_loop 関数を介して要素単位のループ処理を実行します。
multiply 関数は、出力配列を返します。

void PyUFunc_OO_O_method() の代替方法として、以下の方法が考えられます。

NumPy ufunc ツールを使用する

NumPy には、ufunc を定義するためのより高レベルなツールが用意されています。これらのツールを使用すると、void PyUFunc_OO_O_method() を直接使用するよりも、コードをより簡潔に記述することができます。

ufunc.reduce 関数: この関数は、入力配列に対する集約操作を実行するための ufunc を定義するために使用できます。
@vectorize デコレータ: このデコレータを使用すると、Python 関数を ufunc に変換することができます。デコレータは、ループ処理の最適化など、多くのタスクを自動的に処理します。

Cython を使用する

Cython は、C と Python の両方の機能を組み合わせたプログラミング言語です。Cython を使用すると、NumPy C-API をより簡単に操作することができます。Cython で ufunc を定義するには、以下の手順が必要です。

Cython ファイルを作成し、NumPy C-API ヘッダーファイルをインポートします。
ufunc のループ処理関数を作成します。
@cython.binding_type デコレータを使用して、ループ処理関数を ufunc に変換します。

Numba を使用する

Numba は、Python コードを効率的な機械語コードにコンパイルするためのツールです。Numba を使用すると、ufunc のループ処理を高速化することができます。Numba で ufunc を定義するには、以下の手順が必要です。

Numba デコレータを使用して、Python 関数を Numba 関数に変換します。
Numba 関数内で、ufunc のループ処理を実行します。

例

以下の例は、@vectorize デコレータを使用して、2つの整数を乗算して結果を出力する ufunc を定義する方法を示します。

from numpy import vectorize

@vectorize
def multiply(x, y):
  return x * y

x = np.array([1, 2, 3])
y = np.array([4, 5, 6])

z = multiply(x, y)
print(z)  # 出力: [4 10 18]

この例では、@vectorize デコレータは multiply 関数を ufunc に変換し、ループ処理の最適化を自動的に処理します。

void PyUFunc_OO_O_method() は、ufunc を定義するための強力なツールですが、使用方法が複雑です。上記で紹介した代替方法は、より簡潔で効率的な方法で ufunc を定義することができます。