このコードは誰向けか

  • 数値解析・物性研究者向け(読む人・修正する人)

  • 研究室内の個人用解析コード向け(再利用する人)

  • 長期保守・再利用を考える開発者向け

  • 研究用解析コード

  • 高速数値計算

コードの長所

  • 数値安定性: キャリアの占有確率計算において scipy.special.expit, log_expit, spence などの特殊関数を利用しており、オーバーフローやアンダーフローを回避する工夫が確認できます。

  • 極限条件の考慮: _FermiIntegral_core 関数内で eta の値に応じ、縮退極限(_DegenerateFermiDirac)と非縮退極限(_NonDegenerateFermiDirac)への条件分岐が行われています。また、FermiIntegral_fast でも eta > 100 の場合の漸近展開が実装されています。

  • キャッシュ: functools.lru_cache を用いて積分結果を保存する際、_round_key による浮動小数点数の丸めを行うことで、微小な数値の揺らぎによるキャッシュミスを防ぐ設計となっています。

  • docstring: 各関数に対して Sphinx/reST 形式による引数の型や戻り値の説明が詳細に記載されており、AI生成との相性や可読性の面で優れています。

  • 関数分離: 内部演算用の関数(_ から始まる関数)と、ユーザーが呼び出す公開 API(FermiIntegral_fast など)の責務分離が行われています。

問題点と制限

  • silent failure の可能性: _FermiIntegral_core において scipy.integrate.quad を呼び出していますが、戻り値の1要素目 [0] のみを取得しています。積分計算の誤差情報や、収束しなかった場合の警告情報が破棄される構造になっています。

  • ベクトル化の制約: コアとなる積分関数はスカラ値を前提としています。electron_density などの関数では NumPy 配列の入力に対応するため np.nditer を用いていますが、内部で for ループを回して1要素ずつ計算しているため、巨大な配列を入力した場合は Python レイヤーでのループ処理によるオーバーヘッドが発生します。

  • global state: ゾンマーフェルト展開係数 _deg_coeffs がモジュール読み込み時に generate_sommerfeld_coeffs によって計算・保持されます。モジュールロード時の実行コストが発生します。

  • ハードコードされた数値: xlim_exp = 40.0 や _round_key の ndigit=10 など、精度や丸めに関するパラメータがグローバル変数やデフォルト引数として固定されています。

数値計算上の評価

  • 極限条件と asymptotic 処理: FermiIntegral_fast 内での r=1 における 0.5 * eta**2 + np.pi**2 / 6.0 や、非縮退時のガンマ関数を用いた近似(gamma(r + 1.0) * exp(eta))など、極限領域の解析式が明示的に組み込まれています。

  • overflow/underflow: fermi_dirac_e の expit((eta - x) - np.log(g)) への変形や、_NonDegenerateFermiDirac における eta < -20.0 での早期リターンにより、指数関数の発散を回避する処理が確認できます。

  • 収束性: _NonDegenerateFermiDirac のループ内で相対許容誤差 reltol による break 判定が行われていますが、最大項数 max_terms まで収束しなかった場合の例外処理が存在しません。指定された条件で常に収束するかどうかは検証が必要です。

  • 物理モデル依存性: electron_density および hole_density の docstring に記載されている通り、非放物線性を無視した標準的な放物線バンドの仮定に依存しています。

構造・アーキテクチャの評価

  • API設計: 特殊関数や漸近展開による高速化を担当する部分と、数値積分を担当するコア関数が分離されており、利用者は内部処理を意識せずに FermiIntegral_fast を呼び出せる構造になっています。

  • テスト容易性: __main__ ブロック内に動作確認用の print 出力を含む自己テストコードが含まれていますが、境界条件を検証するアサーションや独立したテストフレームワークによる記述はありません。

  • 将来的なライブラリ化: 詳細なドキュメントと関数分割がなされているため、プロジェクト内の別モジュールとしての再利用に適した構造を持っています。

優先順位が高い改善点

  1. scipy.integrate.quad の戻り値に含まれる誤差評価値を取得し、計算が収束しなかった場合や誤差が許容範囲を超えた場合に、警告を出力するか例外を送出する処理の追加。

  2. _NonDegenerateFermiDirac のループが max_terms に到達して終了した場合に、未収束の可能性があることを通知する仕組みの導入。

  3. electron_density や hole_density における np.nditer と for ループの処理を、NumPy 配列全体に対するベクトル化演算(例: numpy.vectorize の活用や、スカラ演算ロジックの見直し)に変更することによる処理速度の向上。

  4. _round_key で設定されている ndigit=10 の丸め処理が、要求される epsabs や epsrel に対して十分な分解能を維持できるか、また意図しないキャッシュキーの衝突を引き起こさないかの検証。

  5. 極限条件の分岐点(例: eta >= 25.0 + 2.0 * r や eta < -0.1)における関数値の連続性を担保するためのテストコード(例: pytest を用いた自動テスト)の作成。

用途に対する適性まとめ

本コードは、半導体物理や物性物理における研究用解析コード、または研究室内の個人用数値計算ツールとして適しています。極限条件における解析式への分岐や、特殊関数による数値安定性の確保といった数式処理の工夫が多数含まれており、教育用サンプルとしても有用な側面を持っています。一方で、配列処理におけるパフォーマンスやエラーハンドリングの面でいくつかの制限が存在するため、公開ライブラリや不特定多数のユーザーが利用するブラックボックスなモジュールとして長期保守を行う場合には、上述した例外処理やベクトル化の改善が必要です。