NumPy C-API: `PyArray_ContiguousFromAny()` 関数の詳細解説とサンプルコード

PyArray_ContiguousFromAny() は、NumPy C-API における重要な関数の一つであり、任意のネストされたシーケンスや配列インターフェースを持つオブジェクトから、連続的で適切な動作をする NumPy 配列を生成します。

この関数は、主に以下の用途で使用されます。

• 配列を連続メモリに配置する
• 配列の要素型を別の型に変換する
• Python オブジェクトを NumPy 配列に変換する

関数シグネチャ

PyObject *PyArray_ContiguousFromAny(
    PyObject *op,       /* 入力オブジェクト */
    int typenum,        /* 生成する配列のデータ型 */
    int min_depth,       /* 最小深さ */
    int max_depth       /* 最大深さ */
);

引数

• max_depth: 生成する NumPy 配列の最大深さ。これは、配列の最大次元数を表します。
• min_depth: 生成する NumPy 配列の最小深さ。これは、配列の次元数を表します。
• typenum: 生成する NumPy 配列のデータ型。これは、NPY_FLOAT64、NPY_INT32 などの数値型定数、または PyArray_Descr 構造体のポインタであることができます。
• op: 変換対象の Python オブジェクト。これは、リスト、タプル、NumPy 配列など、任意のネストされたシーケンスまたは配列インターフェースを持つオブジェクトであることができます。

戻り値

成功した場合、PyArray_ContiguousFromAny() は、生成された NumPy 配列へのポインタを返します。失敗した場合、NULL を返します。

エラー処理

PyArray_ContiguousFromAny() が失敗した場合、適切なエラーメッセージを設定する必要があります。これを行うには、PyErr_SetString() 関数を使用します。

例

以下の例では、リスト [1, 2, 3] を NPY_FLOAT64 型の連続 NumPy 配列に変換します。

#include <numpy/ndarray.h>

int main() {
  PyObject *list = PyList_New(3);
  PyList_SetItem(list, 0, PyInt_FromLong(1));
  PyList_SetItem(list, 1, PyInt_FromLong(2));
  PyList_SetItem(list, 2, PyInt_FromLong(3));

  PyObject *array = PyArray_ContiguousFromAny(list, NPY_FLOAT64, 0, 0);
  if (array == NULL) {
    PyErr_Print();
    return 1;
  }

  // NumPy 配列 `array` を処理する

  Py_DECREF(array);
  Py_DECREF(list);

  return 0;
}

• PyArray_ContiguousFromAny() は、NumPy C-API の一部であるため、NumPy が初期化されていることを確認する必要があります。これは、PyArray_ImportNumPyAPI() 関数を使用して行います。
• 生成された NumPy 配列は、関数から返された後、適切に解放する必要があります。これは、Py_DECREF() 関数を使用して行います。
• PyArray_ContiguousFromAny() は、入力オブジェクトのコピーを作成します。元のオブジェクトは変更されません。

---

リストを NPY_FLOAT64 型の連続 NumPy 配列に変換する

import numpy as np

def list_to_ndarray(input_list, dtype=np.float64):
  """リストを指定されたデータ型の連続 NumPy 配列に変換する

  Args:
    input_list: 変換対象のリスト
    dtype: 生成する NumPy 配列のデータ型 (デフォルト: `NPY_FLOAT64`)

  Returns:
    生成された NumPy 配列
  """

  ndarray = np.array(input_list, dtype=dtype)
  return ndarray.copy(order='C')

# 例
input_list = [1, 2, 3]
ndarray = list_to_ndarray(input_list)

print(ndarray)  # 出力: [1. 2. 3.]

タプルを NPY_INT32 型の連続 NumPy 配列に変換する

import numpy as np

def tuple_to_ndarray(input_tuple, dtype=np.int32):
  """タプルを指定されたデータ型の連続 NumPy 配列に変換する

  Args:
    input_tuple: 変換対象のタプル
    dtype: 生成する NumPy 配列のデータ型 (デフォルト: `NPY_INT32`)

  Returns:
    生成された NumPy 配列
  """

  ndarray = np.array(input_tuple, dtype=dtype)
  return ndarray.copy(order='C')

# 例
input_tuple = (4, 5, 6)
ndarray = tuple_to_ndarray(input_tuple)

print(ndarray)  # 出力: [4 5 6]

ネストされたリストを NPY_BOOL 型の連続 NumPy 配列に変換する

import numpy as np

def nested_list_to_ndarray(input_list, dtype=np.bool_):
  """ネストされたリストを指定されたデータ型の連続 NumPy 配列に変換する

  Args:
    input_list: 変換対象のネストされたリスト
    dtype: 生成する NumPy 配列のデータ型 (デフォルト: `NPY_BOOL`)

  Returns:
    生成された NumPy 配列
  """

  ndarray = np.array(input_list, dtype=dtype)
  return ndarray.copy(order='C')

# 例
input_list = [[True, False], [False, True]]
ndarray = nested_list_to_ndarray(input_list)

print(ndarray)  # 出力: [[ True  False]
                   [ False  True]]

NumPy 配列を別のデータ型に変換する

import numpy as np

def change_dtype(input_array, new_dtype):
  """NumPy 配列を別のデータ型に変換する

  Args:
    input_array: 変換対象の NumPy 配列
    new_dtype: 変換後のデータ型

  Returns:
    変換後の NumPy 配列
  """

  return np.array(input_array, dtype=new_dtype, copy=True, order='C')

# 例
input_array = np.array([1, 2, 3], dtype=np.int32)
ndarray = change_dtype(input_array, np.float64)

print(ndarray)  # 出力: [1. 2. 3.]

import numpy as np

def ensure_contiguous(input_array):
  """NumPy 配列を連続メモリに配置する

  Args:
    input_array: 変換対象の NumPy 配列

  Returns:
    連続メモリに配置された NumPy 配列
  """

  if not input_array.flags['C_CONTIGUOUS']:
    return input_array.copy(order='C')
  else:
    return input_array

# 例
input_array = np.array([[1, 2], [3, 4]], order='F')
ndarray = ensure_contiguous(input_array)

print(ndarray.flags['C_CONTIGUOUS'])  # 出力: True

---

np.array() 関数

np.array() 関数は、Python オブジェクトを NumPy 配列に変換する最も一般的な方法です。PyArray_ContiguousFromAny() 関数と比較して、以下の利点があります。

• 多くの場合、PyArray_ContiguousFromAny() 関数よりも高速
• コードが簡潔で読みやすい

ただし、np.array() 関数は必ずしも連続メモリに配置された NumPy 配列を生成しないという欠点があります。これは、パフォーマンスに悪影響を与える可能性があります。

import numpy as np

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

print(ndarray.flags['C_CONTIGUOUS'])  # 出力: True (常に連続メモリに配置されるとは限らない)

np.reshape() 関数

np.reshape() 関数は、既存の NumPy 配列の形状を変更するために使用できます。この関数は、PyArray_ContiguousFromAny() 関数と比較して、以下の利点があります。

• メモリコピーを回避できる
• 配列の形状を変更できる

ただし、np.reshape() 関数は必ずしも連続メモリに配置された NumPy 配列を生成しないという欠点があります。

import numpy as np

input_array = np.array([[1, 2], [3, 4]], order='F')
ndarray = np.reshape(input_array, (4,))

print(ndarray.flags['C_CONTIGUOUS'])  # 出力: True (形状を変更しても必ずしも連続メモリに配置されるとは限らない)

np.ascontiguousarray() 関数

np.ascontiguousarray() 関数は、既存の NumPy 配列を連続メモリに配置するために使用できます。この関数は、PyArray_ContiguousFromAny() 関数と比較して、以下の利点があります。

• メモリコピーを回避できる

ただし、np.ascontiguousarray() 関数は必ずしも新しい NumPy 配列を生成しないという欠点があります。元の配列が変更される可能性があります。

import numpy as np

input_array = np.array([[1, 2], [3, 4]], order='F')
ndarray = np.ascontiguousarray(input_array)

print(ndarray.flags['C_CONTIGUOUS'])  # 出力: True
print(ndarray is input_array)  # 出力: False (元の配列が変更される)

np.copyto() 関数

np.copyto() 関数は、既存の NumPy 配列を別の NumPy 配列にコピーするために使用できます。この関数は、PyArray_ContiguousFromAny() 関数と比較して、以下の利点があります。

• メモリコピーを制御できる
• 新しい NumPy 配列を常に生成する

ただし、np.copyto() 関数は必ずしも連続メモリに配置された NumPy 配列を生成しないという欠点があります。

import numpy as np

input_array = np.array([[1, 2], [3, 4]], order='F')
output_array = np.empty_like(input_array, order='C')
np.copyto(output_array, input_array)

print(output_array.flags['C_CONTIGUOUS'])  # 出力: True
print(output_array is input_array)  # 出力: False (新しい NumPy 配列が生成される)

PyArray_ContiguousFromAny() 関数は、NumPy C-API における便利な関数ですが、状況によっては代替方法の方が適切な場合があります。上記で紹介した代替方法はそれぞれ異なる利点と欠点を持っているので、要件に合わせて最適な方法を選択することが重要です。

• 新しい NumPy 配列を常に生成する必要がある場合は、np.copyto() 関数を使用
• メモリ使用量を削減したい場合は、np.reshape() 関数を使用することをお勧めします。
• 性能が重要な場合は、PyArray_ContiguousFromAny() 関数よりも np.ascontiguousarray() 関数を使用することをお勧めします。