コード品質と用途適性評価

このコードは誰向けか

  • 教育用サンプル

  • 研究室内の個人用解析コード向け

  • Python初級〜中級者向け

  • 試作コード

  • 公開ライブラリ利用者向けではない

コードの長所

  • 可読性とコメント: すべての関数にSphinx形式のdocstringが記述されており、引数・戻り値の型や計算の目的が明示されています。

  • ベクトル化への配慮: 内部の計算に math モジュールではなく、numpy の数学関数(exp, sqrt, cos, arccos, arctan2 など)を優先的にインポートして使用しており、引数に ndarray が渡されることを想定した設計になっています。

  • モジュール化: 動径波動関数(Rnl, Rnl_if)、球面調和関数(Ylm 等)、およびそれらを合成する波動関数(psi_r 等)が適切に関数として分離されており、数式の構造に合わせた構成になっています。

  • 解析解の提供: Rnl_if にて、低次の主量子数に対する解析的な数式が条件分岐によって実装されており、数値計算の負荷軽減や精度向上の意図が確認できます。

問題点と制限

  • 未定義変数の参照と引数の欠落: psi_xyz_real 関数内で、引数にない phase_m が参照されています。また、内部で psi_r を呼び出す際、本来必要な主量子数 n の引数が欠落しており(psi_r(r, theta, phi, l, m, phase_m) となっている)、実行時エラーが発生します。

  • 副作用(ログ出力)の残留: get_orb_name 関数の内部に print(n,l,m) が残っており、関数が呼び出されるたびに意図しない標準出力が発生します。

  • silent failureのリスク: Rnl_if 関数にて、サポートされていない n, l の組み合わせに対して None を返しています。戻り値が後続の数値演算に使われた場合、予期せぬ TypeError を引き起こす可能性があります。

  • 型依存の判定: get_orb_name や get_qnumbers の内部で type(l) is str または type(m) == str という完全一致による型判定が行われています。

  • グローバル変数の再定義: モジュールレベルで pi = np.pi として名前空間上の変数を上書き定義しています。

数値計算コードとしての評価

  • 極限条件と特異点: Ylm_xyz, Ylm_xyz_real, psi_xyz, psi_xyz_real において、r = sqrt(x**2 + y**2 + z**2) の計算直後に arccos(z / r) を実行しています。原点(x=0, y=0, z=0)が入力された場合、ゼロ除算による数値的な特異点処理(分岐や例外処理)が存在しないため、エラーや NaN が発生します。

  • オーバーフローの可能性: Rnl 関数内で factorial(n + l)**3 などの階乗や累乗計算が行われています。量子数 n や l に大きな値が与えられた場合、浮動小数点数の限界を超えてオーバーフローする可能性があります。

  • 単位系の管理: モジュール冒頭で a0(ボーア半径)をオングストローム単位(* 1e10)に変換している一方で、En 関数では h, m_e, e などのSI単位系をそのまま用いて計算した後に e で除算してeVに変換しています。複数の単位系が混在しており、呼び出し側が前提とする単位系との整合性については検証が必要です。

  • 条件分岐と配列計算の相性: psi_r_real や Ylm_phi_r などの内部に if m >= 0: といったスカラー値向けの条件分岐が存在します。docstringの通り m が int であれば問題ありませんが、もし m として ndarray が渡された場合はエラーとなります。

優先順位が高い改善点

  1. psi_xyz_real 内の未定義変数 phase_m を phase に修正し、psi_r の呼び出し引数に n を追加する(例えば、psi_r(r, theta, phi, n, l, m, phase) とする)。

  2. arccos(z / r) を実行する各関数において、原点(r == 0)の入力に対するゼロ除算を回避する条件分岐を追加する。

  3. get_orb_name 内にハードコードされているデバッグ用の print(n,l,m) を削除する。

  4. Rnl_if 関数のサポート外ルートで None を返す処理を、明示的な例外送出(例えば raise ValueError("Unsupported quantum numbers"))に変更する。

  5. type() を用いた厳密な型判定を、isinstance() を用いた判定に置き換える。

  6. Rnl 関数における大きな量子数でのオーバーフローを防ぐため、対数領域での階乗計算(例えば scipy.special.gammaln の利用)の導入を検討する。

用途に対する適性のまとめ

このコードは、docstringによる関数の目的や数式の意図が明確であり、「教育用サンプル」や「研究室内の個人用解析コード(試作コード)」として数式の実装過程を確認・共有する用途に適しています。

一方で、原点におけるゼロ除算への保護がなく、一部関数で未定義変数を参照していることから、そのままの状態で「公開ライブラリ」や「バッチ処理」「長期保守向け」として利用するには適していません。プロダクションコードや大規模な数値計算に組み込む場合は、特異点回避と例外処理の改修を最初に行う必要があります。