benchmark_fd.py ドキュメント

概要

benchmark_fd.py は、複数のPython実装による半奇数次のフェルミ・ディラック積分(\(F_{1/2}(\eta)\))の計算精度と実行速度を比較・検証するためのベンチマークスクリプトです。指定されたディレクトリに含まれる複数の実装スクリプトを動的にインポートし、基準となる高精度な数値積分結果との相対誤差、および実行時間を計測します。

理論的背景とアルゴリズム

本プログラムが対象とするのは、規格化された次数 \(j = 1/2\) のフェルミ・ディラック積分 \(F_{1/2}(\eta)\) です。これは半導体物理学や薄膜トランジスタ(TFT)の特性解析などにおいて、キャリア濃度の計算に頻出する重要な関数です。

基本定義は以下の通りです。

\[F_{1/2}(\eta) = \frac{1}{\Gamma(3/2)} \int_{0}^{\infty} \frac{x^{1/2}}{\exp(x-\eta)+1} dx\]

コード内の reference 関数では、ベンチマークの基準値を得るために scipy.integrate.quad を用いて独立した数値積分を行っています。その際、数値積分の精度と安定性を確保するために以下のアルゴリズム的工夫が施されています。

  1. 変数変換 積分変数を \(t = \sqrt{x}\) と置換(\(x = t^2\)、\(dx = 2t dt\))することで、\(x=0\) 付近での微分不可能(特異性)を解消し、数値積分の収束性を高めています。

\[\int_{0}^{\infty} \frac{x^{1/2}}{\exp(x-\eta)+1} dx = 2 \int_{0}^{\infty} \frac{t^2}{\exp(t^2-\eta)+1} dt\]
  1. スケーリングとアンダーフロー対策 \(\eta < 0\) の領域において値が極端に小さくなる場合の相対精度を保つため、\(e^\eta\) をスケールファクターとして積分の外に括り出しています。また、オーバーフローを回避するためにロジスティックシグモイド関数 \(\text{expit}(z)\) を活用しています。

\(\eta < 0\) の場合、被積分関数の核となる部分は以下のように計算されます。

\[f(t) = \exp(-t^2) \cdot \text{expit}(t^2 - \eta)\]

\(\eta \ge 0\) の場合は以下のように計算されます。

\[f(t) = \text{expit}(\eta - t^2)\]

これらの工夫により、幅広い \(\eta\) の値に対して高精度な基準値を安定して算出し、各実装の参照値として利用しています。

依存ライブラリ

本プログラムは標準ライブラリ(argparse, csv, importlib.util, math, pathlib, statistics, sys, time)に加えて、以下の非標準ライブラリに依存しています。

  • numpy

  • scipy (scipy.integrate.quad および scipy.special.expit を使用)

入出力仕様

入力仕様

プログラムはコマンドライン引数(CLIオプション)を通じて入力を受け取ります。外部データファイルから直接読み込む機能は実装されていません。 また、SOURCES 定数として定義された6つのスクリプト(Ne-T_sonnet5.5.py, tkfermi_integral.py, Ne-T_copilot.py, Ne-T_Gemini3.8Flash.py, Ne-T_Gemini3Flash.py, Ne-T_sol.py)が、引数 --source-dir で指定されたディレクトリに存在することを前提としています。

利用可能なCLIオプションは以下の通りです。

  • -n, --count : 各実装・各試行での総計算回数(デフォルト: 1000)。1以上の整数を指定します。

  • --repeat : ベンチマークの試行回数(デフォルト: 3)。1以上の整数を指定します。代表値として中央値が採用されます。

  • --eta : 評価対象となる \(\eta\) の値をスペース区切りで指定するリスト(デフォルト: -10, -3, -1, -0.1, 0, 1, 5, 19.9, 20, 50, 100)。指定された値が循環して入力配列として使用されます。

  • --source-dir : 比較対象のPython実装スクリプトが存在するディレクトリパス(デフォルト: 実行スクリプトの親ディレクトリ)。

  • --output : 出力CSVファイルのベースパス(デフォルト: benchmark_fd)。

出力仕様

ベンチマークの実行結果は、標準出力(コンソール)と3つのCSVファイルに出力されます。

標準出力

  • ロードした各実装のキャッシュ無効化(cache_clear)の状況。

  • 各試行における実装ごとの実行時間。

  • すべての試行完了後、実行時間(中央値)が短い順にソートされた結果のサマリー表(実装名、中央値の時間、1回あたりのマイクロ秒、最大相対誤差)。

CSVファイル 引数 --output で指定したベース名(デフォルトは benchmark_fd)にサフィックスが付与された、以下の3つのファイルが生成されます(文字コードはBOM付きUTF-8 utf-8-sig)。

  • _timing.csv 各実装の全体的なベンチマーク結果を記録します。 カラム構成: implementation, count, repeat, median_seconds, min_seconds, us_per_call, max_relative_error

  • _values.csv 各 \(\eta\) に対する各実装の計算値と、基準値との誤差を記録します。 カラム構成: implementation, eta, value, reference, relative_error

  • _trials.csv 各試行(トライアル)ごとの個別の実行時間を記録します。 カラム構成: implementation, trial, seconds

実行例

benchmark_fd.py を実行し、計算回数や \(\eta\) の値をカスタム指定する例を以下に示します。

python benchmark_fd.py --count 5000 --repeat 5 --eta -5.0 0.0 5.0 10.0 --output results/my_benchmark

上記のコマンドを実行すると、以下が行われます。

  • 指定された4つの \(\eta\) の値が循環的に適用され、各実装につき合計5000回の関数呼び出しが行われます。

  • 計測を5回繰り返し、代表値が取得されます。

  • 結果はコンソールに表示されるとともに、results ディレクトリ内に my_benchmark_timing.csv, my_benchmark_values.csv, my_benchmark_trials.csv として保存されます。