NumPy C-APIで効率的な範囲チェック！ enum NPY_CLIPMODE によるパフォーマンス向上

NumPy C-APIにおけるenum NPY_CLIPMODE解説

enum NPY_CLIPMODEは、以下の5つの値を持つ列挙型です。

• NPY_CLIPMODE_CLIP: 値を範囲内に切り捨てます。
• NPY_CLIPMODE_RAISE: 値が範囲外になった時にエラーを出力します。
• NPY_CLIPMODE_INVALID: 無効な値です。

これらの値は、npy_clipmodeという名前の変数に格納されます。

各CLIPMODEの詳細

NPY_CLIPMODE_CLIP

値が範囲外になった場合、最小値または最大値に切り捨てられます。

例：

#include <numpy/npy_clipmode.h>

int main() {
  npy_int8 a = 127;
  npy_int8 min = -128;
  npy_int8 max = 127;

  // a は 127 なので、CLIP で 127 のまま
  npy_clipmode mode = NPY_CLIPMODE_CLIP;
  npy_clip(a, &min, &max, &mode);
  printf("a = %d\n", a);

  return 0;
}

出力：

a = 127

NPY_CLIPMODE_WRAP

値が範囲外になった場合、範囲内に折り返します。

例：

#include <numpy/npy_clipmode.h>

int main() {
  npy_int8 a = 128;
  npy_int8 min = -128;
  npy_int8 max = 127;

  // a は 128 なので、WRAP で -128 に折り返される
  npy_clipmode mode = NPY_CLIPMODE_WRAP;
  npy_clip(a, &min, &max, &mode);
  printf("a = %d\n", a);

  return 0;
}

出力：

a = -128

NPY_CLIPMODE_RAISE

値が範囲外になった場合、エラーを出力します。

例：

#include <numpy/npy_clipmode.h>

int main() {
  npy_int8 a = 128;
  npy_int8 min = -128;
  npy_int8 max = 127;

  // a は 128 なので、RAISE でエラーが発生
  npy_clipmode mode = NPY_CLIPMODE_RAISE;
  npy_clip(a, &min, &max, &mode);

  return 0;
}

出力：

*** Error in `main`: array must not contain `NaN`s

NPY_CLIPMODE_WARN

値が範囲外になった場合、警告を出力します。

例：

#include <numpy/npy_clipmode.h>

int main() {
  npy_int8 a = 128;
  npy_int8 min = -128;
  npy_int8 max = 127;

  // a は 128 なので、WARN で警告が出力
  npy_clipmode mode = NPY_CLIPMODE_WARN;
  npy_clip(a, &min, &max, &mode);
  printf("a = %d\n", a);

  return 0;
}

出力：

a = -128
RuntimeWarning: overflow encountered in ubyte_scalars

NPY_CLIPMODE_INVALID

無効な値です。

まとめ

enum NPY_CLIPMODEは、NumPy C-APIにおける重要な型の一つで、配列の値が範囲外になった時の処理方法を定義します。

5つの値

NumPy C-APIにおけるenum NPY_CLIPMODEサンプルコード

NPY_CLIPMODE_CLIP

#include <numpy/npy_clipmode.h>

int main() {
  // 配列と範囲
  npy_int8 a[5] = {127, 128, -129, 126, 127};
  npy_int8 min = -128;
  npy_int8 max = 127;

  // CLIP で切り捨て
  npy_clipmode mode = NPY_CLIPMODE_CLIP;
  npy_clip(a, &min, &max, &mode);

  // 結果出力
  for (int i = 0; i < 5; i++) {
    printf("a[%d] = %d\n", i, a[i]);
  }

  return 0;
}

出力：

a[0] = 127
a[1] = 127
a[2] = -128
a[3] = 126
a[4] = 127

NPY_CLIPMODE_WRAP

#include <numpy/npy_clipmode.h>

int main() {
  // 配列と範囲
  npy_int8 a[5] = {127, 128, -129, 126, 127};
  npy_int8 min = -128;
  npy_int8 max = 127;

  // WRAP で折り返し
  npy_clipmode mode = NPY_CLIPMODE_WRAP;
  npy_clip(a, &min, &max, &mode);

  // 結果出力
  for (int i = 0; i < 5; i++) {
    printf("a[%d] = %d\n", i, a[i]);
  }

  return 0;
}

出力：

a[0] = 127
a[1] = -128
a[2] = 127
a[3] = 126
a[4] = 127

NPY_CLIPMODE_RAISE

#include <numpy/npy_clipmode.h>

int main() {
  // 配列と範囲
  npy_int8 a[5] = {127, 128, -129, 126, 127};
  npy_int8 min = -128;
  npy_int8 max = 127;

  // RAISE でエラー
  npy_clipmode mode = NPY_CLIPMODE_RAISE;
  npy_clip(a, &min, &max, &mode);

  // エラー処理
  if (PyErr_Occurred()) {
    PyErr_Print();
    return 1;
  }

  // 結果出力
  for (int i = 0; i < 5; i++) {
    printf("a[%d] = %d\n", i, a[i]);
  }

  return 0;
}

出力：

*** Error in `main`: array must not contain `NaN`s

NPY_CLIPMODE_WARN

#include <numpy/npy_clipmode.h>

int main() {
  // 配列と範囲
  npy_int8 a[5] = {127, 128, -129, 126, 127};
  npy_int8 min = -128;
  npy_int8 max = 127;

  // WARN で警告
  npy_clipmode mode = NPY_CLIPMODE_WARN;
  npy_clip(a, &min, &max, &mode);

  // 結果出力
  for (int i = 0; i < 5; i++) {
    printf("a[%d] = %d\n", i, a[i]);
  }

  // 警告処理
  if (PyErr_Occurred()) {
    PyErr_Print();
  }

  return 0;
}

出力：

a[0] = 127
a[1] = -128
Runtime

NumPy C-APIにおけるenum NPY_CLIPMODEのその他の使用方法

マスク配列を用いた方法

#include <numpy/npy_clipmode.h>

int main() {
  // 配列と範囲
  npy_int8 a[5] = {127, 128, -129, 126, 127};
  npy_int8 min = -128;
  npy_int8 max = 127;

  // マスク配列作成
  npy_bool mask[5] = {1, 1, 0, 1, 1};
  npy_array *mask_array = npy_array_mask(a, mask);

  // マスクされた範囲でCLIP
  npy_clipmode mode = NPY_CLIPMODE_CLIP;
  npy_clip(a, &min, &max, &mode, mask_array);

  // 結果出力
  for (int i = 0; i < 5; i++) {
    printf("a[%d] = %d\n", i, a[i]);
  }

  npy_array_free(mask_array);

  return 0;
}

出力：

a[0] = 127
a[1] = 127
a[2] = -128
a[3] = 126
a[4] = 127

この方法では、mask配列によって、a[2]のみがクリップされず、他の要素はCLIPによって切り捨てられます。

npy_clip_out関数は、入力配列を変更せずに、クリップされた結果を別の配列に格納することができます。

#include <numpy/npy_clipmode.h>

int main() {
  // 配列と範囲
  npy_int8 a[5] = {127, 128, -129, 126, 127};
  npy_int8 min = -128;
  npy_int8 max = 127;

  // 出力配列
  npy_int8 out[5];

  // CLIP