benchmark.py ドキュメント

概要

benchmark.py は、フェルミ・ディラック積分の計算速度を、Pythonによる実装( tkfermi_python )とC言語による実装( tkfermi_c )とで比較検証するためのベンチマークプログラムです。 純粋な計算アルゴリズムの速度比較を行うため、Python版関数( _FermiIntegral_cached )のキャッシュ機能を無効化した上で実行時間を計測します。複数のパラメータに対する各実装の実行時間や、C言語化による高速化の倍率( speedup )、および両者の計算結果の相対誤差( relative_difference )を評価し、CSV形式で結果を出力します。

理論と計算アルゴリズム

本プログラムがベンチマーク対象としているフェルミ・ディラック積分 \(F_j(\eta)\) は、半導体物理学においてキャリア濃度の計算などで用いられる特殊関数であり、以下の式で定義されます。

\[F_j(\eta) = \frac{1}{\Gamma(j+1)} \int_{0}^{\infty} \frac{x^j}{\exp(x - \eta) + 1} dx\]

ここで、\(j\) は積分次数(プログラム内では order として扱われ、\(0.5\) または \(1.5\) を指定可能)、\(\eta\) は無次元化されたフェルミ準位(プログラム内では eta として指定)を表します。

解析的かつ効率的な計算を行うため、プログラムでは \(\eta\) の値(フェルミ準位のエネルギーレベル)に応じて、以下の3つの領域( region )に計算アルゴリズムを分岐させています。

  • 非縮退領域 ( \(\eta < -0.1\) ) series として判定されます。マクスウェル・ボルツマン近似を基礎とした級数展開により高速に計算されます。

  • 中間領域 ( \(-0.1 \le \eta < 20\) ) quad として判定されます。ガウス求積法などの数値積分アルゴリズム(数値求積)が適用されます。

  • 強縮退領域 ( \(\eta \ge 20\) ) asymptotic として判定されます。ゾンマーフェルト展開などに基づく漸近展開が適用されます。

依存関係

本プログラムは以下の標準ライブラリおよびサードパーティ製パッケージに依存しています。

  • 標準ライブラリ

    • argparse

    • csv

    • pathlib

    • platform

    • statistics

    • sys

    • time

  • サードパーティ製ライブラリ

    • numpy

    • scipy

    • tkfermi_python (Pythonによるオリジナル実装)

    • tkfermi_c (C言語による部分的な移植実装)

入出力仕様

入力(コマンドライン引数)

プログラムの実行条件は、以下のコマンドラインオプションで指定します。

  • -n, --count 1回の試行における、各関数・各 \(\eta\) ごとの呼び出し回数を指定します。デフォルトは \(1000\) です。

  • --repeat 計測の試行回数を指定します。デフォルトは \(3\) です。

  • --eta 計算対象となる \(\eta\) の値をスペース区切りで複数指定します。デフォルトでは \(-10\) から \(100\) までの複数の値が設定されています。

  • --order 積分次数 \(j\) を指定します。指定可能な値は \(0.5\) または \(1.5\) であり、デフォルトは \(0.5\) です。

  • --output 出力ファイルのベース名および出力先パスを指定します。デフォルトは tkfermi_comparison です。

出力

ベンチマークの実行中、標準出力に実行環境の情報や、各 \(\eta\) ごとの実行時間( \(\mu s\) 単位)、高速化倍率、相対誤差などの経過状況が表示されます。実行完了後、指定された output のパスに基づいて以下の2つのCSVファイルが出力されます。

  • サマリーファイル (例: tkfermi_comparison_summary.csv ) 各 \(\eta\) における中央値を用いたベンチマーク結果の集計が記録されます。 含まれる主な列: eta, order, region, python_us, c_us, speedup, relative_difference など。

  • トライアルファイル (例: tkfermi_comparison_trials.csv ) 各試行における個別の実行時間データ(秒単位)が記録されます。 含まれる主な列: eta, implementation, trial, seconds など。

実行例

ベンチマークを実行する際の基本的なコマンド例です。積分次数を \(0.5\) とし、各計測を \(1000\) 回の関数呼び出し、合計 \(3\) 回の試行で実行します。

python benchmark.py --order 0.5 --count 1000 --repeat 3

任意の \(\eta\) の値や出力先ファイル名を指定して実行する場合は、以下のようにオプションを組み合わせます。

python benchmark.py --eta -5.0 0.0 5.0 25.0 --output results/benchmark_out