numpy-best-practices

NumPy のベストプラクティス

配列プログラミング、数値計算、パフォーマンス最適化に重点を置いた、NumPy 開発のための専門的なガイドラインです。

コードのスタイルと構成

• 正確な NumPy の例を用いて、簡潔で技術的な Python コードを書きます
• パフォーマンス向上のため、明示的なループよりベクトル化演算を優先します
• データの内容を表す説明的な変数名を使います（例：weights、gradients、input_array）
• Python コードには PEP 8 のスタイルガイドラインに従います
• 適切な場合は関数型プログラミングのパターンを使います

配列の作成と操作

• 適切な配列作成関数を使います：np.array()、np.zeros()、np.ones()、np.empty()、np.arange()、np.linspace()
• 配列のサイズがわかっている場合は、事前割り当てに np.zeros() または np.empty() を優先して使います
• 配列の結合には np.concatenate()、np.vstack()、np.hstack() を使います
• ブロードキャストを活用して、形状の異なる配列に対する演算を行います

インデックス指定とスライス

• 条件に応じた選択には、ブール配列を使った高度なインデックス指定を使います
• メモリを節約するため、可能な場合はコピーよりビューを優先します
• 条件に応じた要素の選択には np.where() を使います
• ファンシーインデックス指定（コピーを作成）と基本スライス（ビューを作成）の違いを理解します

データ型

• dtype パラメーターを使って、適切なデータ型を明示的に指定します
• 完全な精度が不要な場合は、メモリ効率のよい計算に np.float32 を使います
• 固定サイズの整数型で発生する整数オーバーフローに注意します
• 不要なコピーを避けて型変換するには np.asarray() を使います

パフォーマンスの最適化

ベクトル化

• Python のループより、常にベクトル化演算を優先します
• 要素単位の演算には NumPy のユニバーサル関数（ufunc）を使います
• 複雑なテンソル演算には np.einsum() を活用します
• 行列の乗算には np.dot() または @ 演算子を使います

メモリ管理

• メモリ配置（C 連続か Fortran 連続か）を確認するには np.ndarray.flags を使います
• 可能な場合は out パラメーターを使ったインプレース演算を優先します
• 大規模なデータセットにはメモリマップ配列（np.memmap）を使います
• 配列のコピーとビューの違いに注意します

計算効率

• 集約処理には axis パラメーターを指定して np.sum()、np.mean()、np.std() を使います
• 累積演算には np.cumsum()、np.cumprod() を活用します
• ソート済み配列の効率的な操作には np.searchsorted() を使います

エラー処理と検証

• 計算の前に入力の形状とデータ型を検証します
• 次元の確認には、わかりやすいメッセージを含むアサーションを使います
• np.isnan()、np.isinf() を使って NaN 値と Inf 値を適切に処理します
• 浮動小数点エラーの処理を制御するには np.errstate() コンテキストマネージャーを使います

乱数生成

• 最新の乱数生成には np.random.default_rng() を使います
• 再現性を確保するため、シードを設定します：rng = np.random.default_rng(seed=42)
• 古い np.random 関数より、新しい Generator API を優先します
• 適切な分布を使います：rng.normal()、rng.uniform()、rng.choice()

線形代数

• 線形代数演算には np.linalg を使います
• 線形方程式系では、逆行列の計算より np.linalg.solve() を活用します
• 分解には np.linalg.eig()、np.linalg.svd() を使います
• 逆行列を計算する前に np.linalg.cond() で行列の条件数を確認します

テストとドキュメント

• pytest と np.testing のアサーションを使って単体テストを書きます
• 厳密な比較には np.testing.assert_array_equal() を使います
• 浮動小数点数の比較には np.testing.assert_array_almost_equal() を使います
• NumPy の docstring 形式に従った包括的な docstring を記述します

主な規約

• import numpy as np としてインポートします
• 変数名と関数名には snake_case を使います
• docstring に配列の形状を記載します
• %timeit でコードのプロファイリングを行い、ボトルネックを特定します