Fj_test_extreme.py ダウンロード/コピー

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()