NumPy ufunc ループを C 言語で定義する: int PyUFunc_RegisterLoopForType() 関数の詳細解説

NumPy C-API: int PyUFunc_RegisterLoopForType() 関数の詳細解説

int PyUFunc_RegisterLoopForType() は、NumPy C-API の重要な関数であり、特定の型に対して NumPy ufunc ループを登録するために使用されます。これは、NumPy 配列の要素間で実行される C 言語関数を登録するための強力なツールです。

関数宣言

int PyUFunc_RegisterLoopForType(PyUFuncObject *ufunc,
                                 PyTypeObject *type,
                                 PyUFuncLoopFunc *func,
                                 int flags)

引数

• ufunc: ループを登録する ufunc オブジェクト
• type: ループが適用される NumPy 型
• func: 実行される C 言語関数
• flags: オプションフラグ

C 言語関数

func は、以下の形式で記述する必要があります。

void func(char **args, npy_intp *dimensions, npy_intp *steps, void *data)

• args: 入力および出力配列へのポインタを含む配列
• dimensions: 各入力および出力配列の次元数
• steps: 各入力および出力配列における各次元の要素間の距離
• data: ユーザーデータ

詳細解説

PyUFunc_RegisterLoopForType() は、以下の処理を行います。

1. ufunc オブジェクトと型オブジェクトの検証
2. ループ関数の検証
3. ループ関数の登録

登録後の動作

ループ関数は、NumPy ufunc がその型に対して実行されるたびに呼び出されます。

例

以下の例は、PyUFunc_RegisterLoopForType() を使用して、2 つの NumPy 配列の要素を乗算するループ関数を登録する方法を示しています。

#include <numpy/ufunc_object.h>

static void multiply_loop(char **args, npy_intp *dimensions, npy_intp *steps, void *data) {
  npy_intp i;
  npy_float64 *x = (npy_float64 *)args[0];
  npy_float64 *y = (npy_float64 *)args[1];
  npy_float64 *out = (npy_float64 *)args[2];

  for (i = 0; i < dimensions[0]; i++) {
    out[i] = x[i] * y[i];
  }
}

static PyUFuncGenericFunction multiply_functions[] = {
  {&multiply_loop, NULL, NULL}
};

static PyUFuncObject multiply_ufunc = {
  .fn = multiply_functions,
  .types = {PyArray_FLOAT64, PyArray_FLOAT64, PyArray_FLOAT64},
  .ntypes = 3,
  .name = "multiply",
  .doc = "Multiply two NumPy arrays element-wise."
};

int main() {
  PyUFunc_RegisterLoopForType(&multiply_ufunc, &PyArray_FLOAT64);
  // ...
}

補足

• PyUFunc_RegisterLoopForType() は、高度な NumPy C-API 関数です。使用前に、NumPy C-API に関する十分な知識が必要です。
• より簡単な方法で NumPy ufunc を定義したい場合は、@vectorize デコレータを使用することを検討してください。

NumPy C-API: int PyUFunc_RegisterLoopForType() 関数のサンプルコード

#include <numpy/ufunc_object.h>

static void add_loop(char **args, npy_intp *dimensions, npy_intp *steps, void *data) {
  npy_intp i;
  npy_int32 *x = (npy_int32 *)args[0];
  npy_int32 *y = (npy_int32 *)args[1];
  npy_int32 *out = (npy_int32 *)args[2];

  for (i = 0; i < dimensions[0]; i++) {
    out[i] = x[i] + y[i];
  }
}

static PyUFuncGenericFunction add_functions[] = {
  {&add_loop, NULL, NULL}
};

static PyUFuncObject add_ufunc = {
  .fn = add_functions,
  .types = {PyArray_INT32, PyArray_INT32, PyArray_INT32},
  .ntypes = 3,
  .name = "add",
  .doc = "Add two NumPy arrays element-wise."
};

int main() {
  PyUFunc_RegisterLoopForType(&add_ufunc, &PyArray_INT32);
  // ...
}

乗算

#include <numpy/ufunc_object.h>

static void multiply_loop(char **args, npy_intp *dimensions, npy_intp *steps, void *data) {
  npy_intp i;
  npy_float64 *x = (npy_float64 *)args[0];
  npy_float64 *y = (npy_float64 *)args[1];
  npy_float64 *out = (npy_float64 *)args[2];

  for (i = 0; i < dimensions[0]; i++) {
    out[i] = x[i] * y[i];
  }
}

static PyUFuncGenericFunction multiply_functions[] = {
  {&multiply_loop, NULL, NULL}
};

static PyUFuncObject multiply_ufunc = {
  .fn = multiply_functions,
  .types = {PyArray_FLOAT64, PyArray_FLOAT64, PyArray_FLOAT64},
  .ntypes = 3,
  .name = "multiply",
  .doc = "Multiply two NumPy arrays element-wise."
};

int main() {
  PyUFunc_RegisterLoopForType(&multiply_ufunc, &PyArray_FLOAT64);
  // ...
}

論理否定

#include <numpy/ufunc_object.h>

static void logical_not_loop(char **args, npy_intp *dimensions, npy_intp *steps, void *data) {
  npy_intp i;
  npy_bool *x = (npy_bool *)args[0];
  npy_bool *out = (npy_bool *)args[1];

  for (i = 0; i < dimensions[0]; i++) {
    out[i] = !x[i];
  }
}

static PyUFuncGenericFunction logical_not_functions[] = {
  {&logical_not_loop, NULL, NULL}
};

static PyUFuncObject logical_not_ufunc = {
  .fn = logical_not_functions,
  .types = {PyArray_BOOL, PyArray_BOOL},
  .ntypes = 2,
  .name = "logical_not",
  .doc = "Logical NOT of a NumPy array element-wise."
};

int main() {
  PyUFunc_RegisterLoopForType(&logical_not_ufunc, &PyArray_BOOL);
  // ...
}

最大値

#include <numpy/ufunc_object.h>

static void maximum_loop(char **args, npy_intp *dimensions, npy_intp *steps, void *data) {
  npy_intp i;
  npy_int32 *x = (npy_int32 *)args[0];
  npy_int32 *y = (npy_int32 *)args

NumPy C-API: int PyUFunc_RegisterLoopForType() 以外の方法

@vectorize デコレータ

NumPy には、@vectorize デコレータと呼ばれる、C 言語関数を NumPy ufunc に変換する便利な機能があります。@vectorize は、PyUFunc_RegisterLoopForType() よりも簡単に NumPy ufunc を定義できます。

@vectorize
def add(x, y):
  return x + y

# 加算 ufunc を利用
x = np.array([1, 2, 3])
y = np.array([4, 5, 6])
z = add(x, y)

print(z)
# [5 7 9]

numpy.frompyfunc 関数は、C 言語関数を NumPy ufunc オブジェクトに変換する関数です。numpy.frompyfunc は、@vectorize よりも柔軟性がありますが、複雑で習得に時間がかかります。

def add_c(x, y):
  return x + y

add_ufunc = np.frompyfunc(add_c, 2, 1)

# 加算 ufunc を利用
x = np.array([1, 2, 3])
y = np.array([4, 5, 6])
z = add_ufunc(x, y)

print(z)
# [5 7 9]

NumPy ufunc の拡張

NumPy は、ufunc.add や ufunc.multiply などの事前定義された ufunc を多数提供しています。これらの ufunc を拡張して、独自のニーズに合わせてカスタマイズできます。

def my_add(x, y):
  return x + y + 1

# 加算 ufunc を拡張
np.add.at = my_add

# 拡張された加算 ufunc を利用
x = np.array([1, 2, 3])
y = np.array([4, 5, 6])
z = np.add(x, y)

print(z)
# [6 8 10]

その他のライブラリ

NumPy 以外にも、ufunc を定義するためのライブラリがいくつかあります。以下はその例です。

int PyUFunc_RegisterLoopForType() 関数は、NumPy ufunc ループを登録する強力な方法ですが、複雑で習得に時間がかかります。上記のような代替方法も検討することで、ニーズに合った方法を選択できます。