Fj_test_extreme.py ダウンロード/コピー
Fj_test_extreme.py
Fj_test_extreme.py
1#!/usr/bin/env python3
2# -*- coding: utf-8 -*-
3"""
4概要:
5 エッジケースや極端な条件を含むフェルミ・ディラック積分(非正規化)のテストとベンチマークを行います。
6詳細説明:
7 Fj(j, eta) = 積分(0から無限大) x^j * f(eta - x) dx をテストします。
8 ここで f(z) = 1/(1+exp(-z)) = expit(z) です。
9 j = -1 の場合、積分形式は x が 0 に近づくにつれ発散するため、解析的な同一性を利用します。
10 F0(eta) = 積分(0から無限大) f(eta-x) dx = log(1+exp(eta)) となり、
11 これを eta で微分すると expit(eta) になります。
12 そのため、再帰関係の dFj/deta = Fj-1 との整合性から Fj(-1, eta) は expit(eta) と定義します。
13 他の j > -1 については、保守的な有限の上限を用いた数値積分 quad を使用します。
14 また、eta が非常に小さい非縮退の極限、T=0K のステップ極限、eta が非常に大きい縮退の極限である
15 ゾンマーフェルト展開などとの比較も実装しています。
16"""
17
18import time
19import math
20import numpy as np
21from scipy.special import expit, log1p, gamma
22from scipy.integrate import quad
23
24from tkfermi_integral import FermiIntegral_fast
25
26
27# ============================================================
28# Core implementations
29# ============================================================
30def _upper_bound(eta: float) -> float:
31 """
32 概要:
33 数値積分 quad のためのヒューリスティックな有限の上限値を計算します。
34 詳細説明:
35 大きな正の eta に対して被積分関数は x が eta より小さいときに x^j に比例するため、
36 上限値は eta を超える必要があります。また、大きな x に対しては占有確率が exp(eta-x)
37 のように減衰するため、倍精度計算では余裕を持たせた値を上限として使用します。
38 引数:
39 :param eta: フェルミ準位に関連する無次元パラメータ
40 :type eta: float
41 戻り値:
42 :returns: 積分計算のための上限値
43 :rtype: float
44 """
45 return float(max(eta + 60.0, 120.0))
46
47
48def Fj_expit(j: float, eta: float) -> float:
49 """
50 概要:
51 被積分関数に expit を用いて quad による数値積分を行います。
52 詳細説明:
53 j が -1 の場合は例外的に解析値 expit(eta) を返します。
54 j が -1 未満の場合はサポート外として例外を発生させます。
55 引数:
56 :param j: 積分の次数
57 :type j: float
58 :param eta: フェルミ準位に関連する無次元パラメータ
59 :type eta: float
60 戻り値:
61 :returns: 積分の計算結果
62 :rtype: float
63 例外:
64 :raises ValueError: j が -1 未満の場合
65 """
66 if j == -1:
67 return float(expit(eta))
68 if j <= -1:
69 raise ValueError("This implementation supports j > -1, except j=-1 (handled analytically).")
70
71 upper = _upper_bound(eta)
72 integrand = lambda x: (x ** j) * expit(eta - x)
73 res, _ = quad(integrand, 0.0, upper, epsabs=1e-12, epsrel=1e-12, limit=200)
74 return float(res)
75
76
77def Fj_raw(j: float, eta: float) -> float:
78 """
79 概要:
80 被積分関数に生の exp を用いて quad による数値積分を行います。
81 詳細説明:
82 j が -1 の場合は例外的に解析値 expit(eta) を返します。
83 j が -1 未満の場合はサポート外として例外を発生させます。
84 引数:
85 :param j: 積分の次数
86 :type j: float
87 :param eta: フェルミ準位に関連する無次元パラメータ
88 :type eta: float
89 戻り値:
90 :returns: 積分の計算結果
91 :rtype: float
92 例外:
93 :raises ValueError: j が -1 未満の場合
94 """
95 if j == -1:
96 # d/deta log(1+exp(eta)) = expit(eta)
97 return float(expit(eta))
98 if j <= -1:
99 raise ValueError("This implementation supports j > -1, except j=-1 (handled analytically).")
100
101 upper = _upper_bound(eta)
102 integrand = lambda x: (x ** j) / (1.0 + np.exp(x - eta))
103 res, _ = quad(integrand, 0.0, upper, epsabs=1e-12, epsrel=1e-12, limit=200)
104 return float(res)
105
106
107def Fj_fast(j: float, eta: float):
108 """
109 概要:
110 高速実装版のフェルミ・ディラック積分を呼び出すラッパー関数です。
111 詳細説明:
112 内部で FermiIntegral_fast を呼び出します。未対応の場合やエラーが発生した場合は None を返します。
113 引数:
114 :param j: 積分の次数
115 :type j: float
116 :param eta: フェルミ準位に関連する無次元パラメータ
117 :type eta: float
118 戻り値:
119 :returns: 積分の計算結果、または計算できない場合は None
120 :rtype: float または None
121 """
122 try:
123 return float(FermiIntegral_fast(eta, j))
124 except Exception:
125 return None
126
127
128# ============================================================
129# Asymptotic / limit reference checks
130# ============================================================
131def Fj_nondegenerate_approx(j: float, eta: float) -> float:
132 """
133 概要:
134 eta が非常に小さい負の値をとる場合の非縮退近似値を計算します。
135 詳細説明:
136 eta が十分小さいとき、Fj は exp(eta) と ガンマ関数(j+1) の積で近似できます。
137 j が -1 の場合は exp(eta) を返します。
138 引数:
139 :param j: 積分の次数
140 :type j: float
141 :param eta: フェルミ準位に関連する無次元パラメータ
142 :type eta: float
143 戻り値:
144 :returns: 非縮退近似による計算結果
145 :rtype: float
146 """
147 if j == -1:
148 # expit(eta) ~ exp(eta) for eta<<0
149 return float(np.exp(eta))
150 return float(np.exp(eta) * gamma(j + 1.0))
151
152
153def Fj_0K_step(j: float, eta: float) -> float:
154 """
155 概要:
156 絶対零度への極限におけるステップ関数の積分結果を計算します。
157 詳細説明:
158 eta が正の場合は eta の j+1 乗を j+1 で割った値を返します。
159 j が -1 の場合はステップ関数の極限として eta が 0 より大きいときに 1.0 を返します。
160 引数:
161 :param j: 積分の次数
162 :type j: float
163 :param eta: フェルミ準位に関連する無次元パラメータ
164 :type eta: float
165 戻り値:
166 :returns: 0K極限における計算結果
167 :rtype: float
168 """
169 if j == -1:
170 return float(1.0 if eta > 0 else 0.0)
171 if eta <= 0:
172 return 0.0
173 return float((eta ** (j + 1.0)) / (j + 1.0))
174
175
176def Fj_sommerfeld(j: float, eta: float) -> float:
177 """
178 概要:
179 eta が十分大きい正の値をとる場合のゾンマーフェルト展開による近似値を計算します。
180 詳細説明:
181 j が -1 の場合は 1.0 を返します。eta が 0 以下の場合は 0K極限の結果をそのまま返します。
182 それ以外の場合は、円周率の2乗や4乗の項を含む展開式を用いて高精度の近似値を計算します。
183 引数:
184 :param j: 積分の次数
185 :type j: float
186 :param eta: フェルミ準位に関連する無次元パラメータ
187 :type eta: float
188 戻り値:
189 :returns: ゾンマーフェルト展開による近似結果
190 :rtype: float
191 """
192 if j == -1:
193 # expit(eta) -> 1 for eta>>1
194 return 1.0
195 if eta <= 0:
196 # not a good regime; still return 0K limit
197 return Fj_0K_step(j, eta)
198
199 term0 = (eta ** (j + 1.0)) / (j + 1.0)
200 term2 = (math.pi**2 / 6.0) * j * (eta ** (j - 1.0)) if j > 0 else 0.0
201
202 # π^4 term requires j-3 power; for small j this diverges / is meaningless.
203 if j > 2.0:
204 term4 = (7.0 * math.pi**4 / 360.0) * j * (j - 1.0) * (j - 2.0) * (eta ** (j - 3.0))
205 else:
206 term4 = 0.0
207
208 return float(term0 + term2 + term4)
209
210
211# ============================================================
212# Test helpers
213# ============================================================
214def rel_err(a: float, b: float, tiny: float = 1e-300) -> float:
215 """
216 概要:
217 2つの値の間の相対誤差を計算します。
218 詳細説明:
219 ゼロ除算を防ぐために tiny の値を使用して分母の最小値を制限し、安全に誤差を評価します。
220 引数:
221 :param a: 比較する最初の値
222 :type a: float
223 :param b: 比較する基準となる値
224 :type b: float
225 :param tiny: 分母の下限となる微小値
226 :type tiny: float
227 戻り値:
228 :returns: 計算された相対誤差
229 :rtype: float
230 """
231 return abs(a - b) / max(abs(b), tiny)
232
233
234def print_header(title: str):
235 """
236 概要:
237 指定されたタイトルをコンソールに整形して出力します。
238 詳細説明:
239 前後に区切り線を入れて見やすく表示するための補助関数です。
240 引数:
241 :param title: 出力するタイトル文字列
242 :type title: str
243 戻り値:
244 :returns: なし
245 :rtype: None
246 """
247 print("\n" + "=" * 78)
248 print(title)
249 print("=" * 78)
250
251
252# ============================================================
253# Main tests
254# ============================================================
255def main():
256 """
257 概要:
258 フェルミ・ディラック積分の各種テストとベンチマークを実行するメイン関数です。
259 詳細説明:
260 数値積分、高速実装、非縮退近似、0K極限、ゾンマーフェルト展開の各結果を比較検証し、
261 さらに計算時間のベンチマークと極端な eta での健全性チェックを行います。
262 引数:
263 なし
264 戻り値:
265 :returns: なし
266 :rtype: None
267 """
268 # Requested j list including -1
269 j_values = [-1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0]
270
271 # Baseline sweep
272 eta_values = np.array([-20, -10, -5, -2, -1, -0.1, 0.0, 0.1, 1, 2, 5, 10, 20], dtype=float)
273
274 # Extreme / edge cases
275 eta_extreme = np.array([-100, -50, -40, 40, 50, 100], dtype=float)
276
277 # Tolerance for cross-implementation numeric agreement (quad expit vs quad raw)
278 tol_abs = 1e-10
279
280 print_header("A) Consistency check: quad(expit) vs quad(raw) vs fast (if available)")
281 print(f"abs diff tolerance (quad vs quad): {tol_abs:g}")
282 print("-" * 78)
283 print(" j eta quad_expit quad_raw |diff| fast status")
284 print("-" * 78)
285
286 for j in j_values:
287 for eta in eta_values:
288 v1 = Fj_expit(j, float(eta))
289 v2 = Fj_raw(j, float(eta))
290 d12 = abs(v1 - v2)
291
292 v3 = Fj_fast(j, float(eta))
293 if v3 is None:
294 status = "PASS" if d12 < tol_abs else "FAIL"
295 v3s = " (n/a)"
296 else:
297 d13 = abs(v1 - v3)
298 status = "PASS" if (d12 < tol_abs and d13 < tol_abs) else "FAIL"
299 v3s = f"{v3: .6e}"
300
301 print(f"{j:6.1f} {eta:8.2f} {v1: .6e} {v2: .6e} {d12: .2e} {v3s:>12} {status}")
302 print("-" * 78)
303
304 # ------------------------------------------------------------
305 # Edge / limit checks
306 # ------------------------------------------------------------
307 print_header("B) Edge/limit checks: nondegenerate (eta<<0), 0K-step, Sommerfeld (eta>>0)")
308 print("We compare quad(expit) against asymptotic/limit formulae.\n"
309 "For very negative eta: Fj ≈ exp(eta)*Gamma(j+1)\n"
310 "For large positive eta: use 0K step and Sommerfeld expansion as references.\n")
311 print("-" * 78)
312 print(" j eta quad_expit approx_type approx_value rel.err")
313 print("-" * 78)
314
315 # 1) nondegenerate checks
316 for j in j_values:
317 for eta in [-40.0, -50.0]:
318 v = Fj_expit(j, eta)
319 a = Fj_nondegenerate_approx(j, eta)
320 print(f"{j:5.1f} {eta:7.1f} {v: .6e} nondegenerate {a: .6e} {rel_err(v,a):.2e}")
321
322 print("-" * 78)
323
324 # 2) 0K-step check (finite eta, compare to step integral)
325 for j in [x for x in j_values if x != -1.0]:
326 for eta in [-5.0, -1.0, 0.0, 1.0, 5.0, 10.0]:
327 v = Fj_expit(j, eta)
328 a = Fj_0K_step(j, eta)
329 print(f"{j:5.1f} {eta:7.1f} {v: .6e} 0K step {a: .6e} {rel_err(v,a):.2e}")
330
331 print("-" * 78)
332
333 # 3) Sommerfeld check (eta large)
334 for j in [x for x in j_values if x not in (-1.0, 0.0)]: # j=0 has special exact form; skip
335 for eta in [20.0, 40.0]:
336 v = Fj_expit(j, eta)
337 a = Fj_sommerfeld(j, eta)
338 print(f"{j:5.1f} {eta:7.1f} {v: .6e} Sommerfeld {a: .6e} {rel_err(v,a):.2e}")
339
340 # Special exact identity for j=0
341 print("-" * 78)
342 for eta in [-40.0, -10.0, 0.0, 10.0, 40.0]:
343 v = Fj_expit(0.0, eta)
344 a = float(np.log1p(np.exp(eta))) # exact: ∫ f(eta-x) dx = log(1+exp(eta))
345 print(f"{0.0:5.1f} {eta:7.1f} {v: .6e} exact log1p {a: .6e} {rel_err(v,a):.2e}")
346
347 # ------------------------------------------------------------
348 # Benchmark
349 # ------------------------------------------------------------
350 print_header("C) Benchmark (per-call time)")
351 N = 30 # repeat count
352
353 j_bench = [0.5, 1.5]
354 eta_bench = [-10.0, -1.0, 0.0, 1.0, 10.0, 50.0]
355
356 for j in j_bench:
357 print(f"\n[j={j}]")
358 print("-" * 78)
359 for eta in eta_bench:
360 # expit quad
361 t0 = time.perf_counter()
362 for _ in range(N):
363 Fj_expit(j, eta)
364 t1 = time.perf_counter()
365 time_expit = (t1 - t0) / N
366
367 # raw quad
368 t0 = time.perf_counter()
369 for _ in range(N):
370 Fj_raw(j, eta)
371 t1 = time.perf_counter()
372 time_raw = (t1 - t0) / N
373
374 # fast (if any)
375 t_fast = None
376 ok_fast = True
377 try:
378 t0 = time.perf_counter()
379 for _ in range(N * 20):
380 FermiIntegral_fast(eta, j)
381 t1 = time.perf_counter()
382 t_fast = (t1 - t0) / (N * 20)
383 except Exception:
384 ok_fast = False
385
386 print(f"eta={eta:6.1f} | quad(expit)={time_expit*1e3:8.3f} ms quad(raw)={time_raw*1e3:8.3f} ms"
387 + (f" fast={t_fast*1e6:8.3f} µs" if ok_fast else " fast=(n/a)"))
388 print("-" * 78)
389
390 # ------------------------------------------------------------
391 # Extreme eta quick sanity (avoid too much time)
392 # ------------------------------------------------------------
393 print_header("D) Extreme eta sanity (quick)")
394 print("We only run quad(expit) once per point for extreme eta to avoid long runtimes.")
395 print("-" * 78)
396 print(" j eta Fj_expit")
397 print("-" * 78)
398 for j in j_values:
399 for eta in eta_extreme:
400 v = Fj_expit(j, float(eta))
401 print(f"{j:6.1f} {eta:8.1f} {v: .6e}")
402 print("-" * 78)
403
404
405if __name__ == "__main__":
406 main()