NumPy C-API: PyArray_BroadcastToShape() 関数詳解

NumPy C-API: PyObject *PyArray_BroadcastToShape() 関数解説

関数概要

PyObject *PyArray_BroadcastToShape(PyArrayObject *array, npy_intp *newshape, int ndims);

• array: ブロードキャストされる配列
• newshape: ブロードキャスト後の形状を指定する配列
• ndims: newshape の要素数

動作

PyArray_BroadcastToShape() は、以下の手順で動作します。

1. array と newshape の形状が互換性があるかどうかをチェックします。
2. 互換性がない場合は、エラーが発生します。
3. 互換性がある場合は、新しい配列が作成されます。
4. 新しい配列は、array の要素を newshape に沿ってブロードキャストします。
5. 新しい配列へのポインタが返されます。

例

#include <numpy/arrayobject.h>

int main() {
  // 配列の作成
  PyArrayObject *array = PyArray_Zeros(2, PyArray_INT32);

  // ブロードキャスト後の形状
  npy_intp newshape[] = {3, 2};

  // ブロードキャスト
  PyArrayObject *broadcast_array = PyArray_BroadcastToShape(array, newshape, 2);

  // ブロードキャスト後の配列の内容
  for (int i = 0; i < 3; i++) {
    for (int j = 0; j < 2; j++) {
      printf("%d ", *(int *)PyArray_GETPTR2(broadcast_array, i, j));
    }
    printf("\n");
  }

  // メモリ解放
  Py_DECREF(array);
  Py_DECREF(broadcast_array);

  return 0;
}

この例では、array は形状 (2,) のゼロ配列です。newshape は形状 (3, 2) を指定します。PyArray_BroadcastToShape() は、array を (3, 2) にブロードキャストし、新しい配列 broadcast_array を返します。broadcast_array は以下の内容になります。

0 0
0 0
0 0

ブロードキャストルール

PyArray_BroadcastToShape() は、以下のブロードキャストルールに従います。

• 配列の各次元は、ブロードキャスト後の形状の対応する次元と同じか、1 でなければなりません。
• 1 の次元は、ブロードキャスト後の形状の対応する次元と同じ長さに拡張されます。

PyArray_BroadcastToShape() 関数に関する詳細は、NumPy の公式ドキュメントを参照してください。

補足

• PyArray_BroadcastToShape() は、NumPy の C-API の関数なので、Python コードから直接呼び出すことはできません。C 言語で記述されたコードから呼び出す必要があります。
• PyArray_BroadcastToShape() は、新しい配列を作成します。元の配列は変更されません。
• PyArray_BroadcastToShape() は、参照カウントを増加させます。使用後は Py_DECREF() で参照カウントを減らす必要があります。

関連関数

• PyArray_Newshape()：形状を変更せずに、新しい配列を作成します。

NumPy C-API は、NumPy の内部処理にアクセスするための低レベルなインターフェースです。C 言語に慣れていない場合は、NumPy の Python インターフェースを使用することをお勧めします。

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

単純なブロードキャスト

#include <numpy/arrayobject.h>

int main() {
  // 配列の作成
  PyArrayObject *array = PyArray_Zeros(2, PyArray_INT32);

  // ブロードキャスト後の形状
  npy_intp newshape[] = {3, 2};

  // ブロードキャスト
  PyArrayObject *broadcast_array = PyArray_BroadcastToShape(array, newshape, 2);

  // ブロードキャスト後の配列の内容
  for (int i = 0; i < 3; i++) {
    for (int j = 0; j < 2; j++) {
      printf("%d ", *(int *)PyArray_GETPTR2(broadcast_array, i, j));
    }
    printf("\n");
  }

  // メモリ解放
  Py_DECREF(array);
  Py_DECREF(broadcast_array);

  return 0;
}

スカラー値のブロードキャスト

#include <numpy/arrayobject.h>

int main() {
  // スカラー値
  int value = 5;

  // ブロードキャスト後の形状
  npy_intp newshape[] = {3, 2};

  // スカラー値を配列に変換
  PyArrayObject *scalar_array = PyArray_Scalar(value, PyArray_INT32);

  // ブロードキャスト
  PyArrayObject *broadcast_array = PyArray_BroadcastToShape(scalar_array, newshape, 2);

  // ブロードキャスト後の配列の内容
  for (int i = 0; i < 3; i++) {
    for (int j = 0; j < 2; j++) {
      printf("%d ", *(int *)PyArray_GETPTR2(broadcast_array, i, j));
    }
    printf("\n");
  }

  // メモリ解放
  Py_DECREF(scalar_array);
  Py_DECREF(broadcast_array);

  return 0;
}

このコードは、スカラー値 5 を (3, 2) にブロードキャストします。

高次元配列のブロードキャスト

#include <numpy/arrayobject.h>

int main() {
  // 配列の作成
  npy_intp dims[] = {2, 3, 4};
  PyArrayObject *array = PyArray_Zeros(3, PyArray_INT32, dims);

  // ブロードキャスト後の形状
  npy_intp newshape[] = {2, 3, 1, 4};

  // ブロードキャスト
  PyArrayObject *broadcast_array = PyArray_BroadcastToShape(array, newshape, 4);

  // ブロードキャスト後の配列の内容
  for (int i = 0; i < 2; i++) {
    for (int j = 0; j < 3; j++) {
      for (int k = 0; k < 1; k++) {
        for (int l = 0; l < 4; l++) {
          printf("%d ", *(int *)PyArray_GETPTR4(broadcast_array, i, j, k, l));
        }
        printf("\n");
      }
    }
  }

  // メモリ解放
  Py_DECREF(array);
  Py_DECREF(broadcast_array);

  return 0;
}

このコードは、(2, 3, 4) 形状のゼロ配列を (2, 3, 1, 4) にブロードキャストします。

ブロードキャストエラー

#include <numpy/arrayobject.h>

int main() {
  // 配列の作成
  PyArrayObject *array = PyArray_Zeros(2, PyArray_INT32);

  // ブロードキャスト後の形状
  npy_intp newshape[] = {3, 3};

  // ブロードキャスト (エラー発生)
  PyArrayObject *broadcast_array = PyArray_BroadcastToShape(array, newshape, 2);

  // エラー処理

NumPy 配列のブロードキャストを行う方法

PyArray_BroadcastToShape() 関数は、NumPy C-API の関数で、与えられた配列を指定された形状にブロードキャストします。

PyObject *PyArray_BroadcastToShape(PyArrayObject *array, npy_intp *newshape, int ndims);

詳細は、NumPy C-API: PyObject *PyArray_BroadcastToShape() 関数解説: #numPy-c-api-PyObject-PyArray_BroadcastToShape-関数解説 を参照してください。

np.broadcast() 関数は、NumPy の Python インターフェースの関数で、複数の配列をブロードキャストします。

np.broadcast(*arrays)

• arrays: ブロードキャストされる配列のリスト

詳細は、NumPy: np.broadcast() 関数: https://numpy.org/doc/stable/reference/generated/numpy.broadcast.html を参照してください。

np.newaxis を使って、配列の特定の次元を拡張できます。

array = np.array([1, 2, 3])

# (3,) -> (3, 1)
broadcast_array = array[:, np.newaxis]

# (3,) -> (1, 3)
broadcast_array = array[np.newaxis, :]

詳細は、NumPy: np.newaxis: [無効な URL を削除しました] を参照してください。

スカラー値は、ブロードキャストによって任意の形状の配列に変換できます。

# スカラー値
value = 5

# (3, 2)
broadcast_array = np.full((3, 2), value)

# (3, 2)
broadcast_array = np.ones((3, 2)) * value

その他

上記以外にも、NumPy 配列のブロードキャストを行う方法はいくつかあります。詳細は、NumPy の公式ドキュメントを参照してください。

• C 言語で NumPy を使用している場合は、PyArray_BroadcastToShape() 関数を使うのが最も効率的です。
• Python コードで NumPy を使用している場合は、np.broadcast() 関数を使うのが最も簡単です。
• 特定の次元のみをブロードキャストしたい場合は、np.newaxis を使うのが便利です。

NumPy 配列のブロードキャストは、さまざまな方法で行うことができます。状況に合わせて適切な方法を選択してください。