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

tkfermi_integral.py をダウンロード

tkfermi_integral.py
tkfermi_integral.py
  1"""
  2Fast and robust Fermi–Dirac integral library
  3"""
  4
  5from math import exp, gamma, isclose
  6from functools import lru_cache
  7import numpy as np
  8from scipy import integrate
  9from scipy.special import expit, log_expit
 10from scipy.special import zeta
 11from scipy.special import spence  # 追加:Li2(x)の計算に使用
 12
 13
 14xlim_exp = 40.0
 15#xlim_exp = 300.0
 16
 17kF12 = 2.0 / np.sqrt(np.pi)  # 2/sqrt(pi)
 18
 19
 20# ------------------------------------------------------------
 21# Sommerfeld expansion coefficients for degenerate limit
 22# z_k = (1 - 2^(-(2k+1))) * zeta(2k+2)
 23# where zeta(s, 1) = Riemann zeta(s)
 24# for validation: _deg_coeffs = (0.822467, 0.947033, 0.985551, 0.996233, 0.999040, 0.999758, 0.999939, 0.999985)
 25# ------------------------------------------------------------
 26n_deg_coeffs = 10
 27
 28"""
 29_deg_coeffs = [
 30    (1.0 - 2.0 ** (-(2 * k + 1))) * float(zeta(2 * k + 2, 1.0))
 31    for k in range(n_deg_coeffs)
 32]
 33"""
 34
 35def generate_sommerfeld_coeffs(n_terms):
 36    coeffs = []
 37    for k in range(1, n_terms + 1):
 38        # z_k = (1 - 2^(1-2k)) * zeta(2k)
 39        val = (1 - 2.0**(1 - 2*k)) * zeta(2*k, 1)
 40        coeffs.append(float(val))
 41    return tuple(coeffs)
 42
 43_deg_coeffs = generate_sommerfeld_coeffs(n_deg_coeffs)
 44
 45def _round_key(x, ndigit=10):
 46    return round(float(x), ndigit)
 47
 48
 49# ------------------------------------------------------------
 50# Fermi–Dirac occupations (x = E/kT, eta = Ef/kT)
 51# ------------------------------------------------------------
 52def fermi_dirac_e_npvector(x):
 53    x = np.clip(x, -xlim_exp, xlim_exp)
 54    pos = x > 0
 55    out = np.empty_like(x)
 56    exp_positive = np.exp(-x[pos])
 57    out[pos] = exp_positive / (1 + exp_positive)
 58    out[~pos] = 1 / (1 + np.exp(x[~pos]))
 59    return out
 60
 61def fermi_dirac_e_if(x, eta, g=1.0):
 62    """
 63    f = 1 / (1 + g * exp(x - eta))
 64    """
 65    xe = x - eta
 66    if xe < -xlim_exp: return 1.0
 67    if xe > xlim_exp: return 0.0
 68    return 1.0 / (1 + g * exp(xe))
 69
 70def fermi_dirac_e(x, eta, g=1.0):
 71    """
 72    f = 1 / (1 + g * exp(x - eta))
 73      = expit((eta - x) - ln(g))
 74    """
 75    return expit((eta - x) - np.log(g))
 76
 77def log_fermi_dirac_e(x, eta, g=1.0):
 78    """log(f) stable for the same definition."""
 79    return log_expit((eta - x) - np.log(g))
 80
 81def fermi_dirac_h(x, eta, g=1.0):
 82    """
 83    vacancy (hole) probability (defined with the same 'g as prefactor'):
 84        1 - f = 1 / (1 + g * exp(eta - x))
 85              = expit((x - eta) - ln(g))
 86    """
 87    return expit((x - eta) - np.log(g))
 88
 89def log_fermi_dirac_h(x, eta, g=1.0):
 90    """log(1-f) stable for the same definition."""
 91    return log_expit((x - eta) - np.log(g))
 92
 93def ionized_acceptor_frac(eta, xA, g=1.0):
 94    return fermi_dirac_e(xA, eta, g=g)
 95
 96def ionized_donor_frac(eta, xD, g=1.0):
 97    """ND+/ND = 1 / (1 + g * exp(eta - xD))"""
 98    return fermi_dirac_h(xD, eta, g=g)
 99
100# ============================================================
101# internal: degenerate limit (Sommerfeld-like)
102# ============================================================
103
104def _DegenerateFermiDirac(eta, r):
105    gi = eta ** (r + 1.0) / (r + 1.0)
106    t = r
107    gg = t / (eta * eta)
108    gs = gg * _deg_coeffs[0]
109    t -= 1.0
110
111    for k in range(1, n_deg_coeffs):
112        gg *= t * (t - 1.0) / (eta * eta)
113        gs += gg * _deg_coeffs[k]
114        t -= 2.0
115
116    return gi * (1.0 + 2.0 * (r + 1.0) * gs)
117
118
119# ============================================================
120# internal: non-degenerate limit (alternating series)
121# ============================================================
122
123def _NonDegenerateFermiDirac(eta, r, reltol=1e-10, max_terms=200000):
124    if eta < -20.0:
125        return gamma(r + 1.0) * exp(eta)
126
127    s = 1.0
128    total = 0.0
129    scale = 0.0
130
131    for _ in range(max_terms // 2):
132        t1 = exp(s * eta) / s**(r + 1.0)
133        s += 1.0
134        t2 = exp(s * eta) / s**(r + 1.0)
135        s += 1.0
136
137        subtotal = t1 - t2
138        total += subtotal
139
140        scale = max(scale, abs(t1), abs(t2))
141
142        if abs(subtotal) < reltol * max(abs(total), 1.0):
143            break
144
145    return total * gamma(r+1.0)
146
147
148# ============================================================
149# cache-safe wrapper
150# ============================================================
151
152def _func_Fr_x2(x, eta, r):
153    return 2.0 * x ** (2.0 * r + 1.0) * expit(eta - x*x)
154
155def _FermiIntegral_core(eta, r, epsabs, epsrel, limit):
156    # degenerate
157    if eta >= 25.0 + 2.0 * r:
158        return _DegenerateFermiDirac(eta, r)
159
160    # non-degenerate
161    if eta < -0.1:
162        return _NonDegenerateFermiDirac(eta, r)
163
164    # intermediate: z = x^2 + quad
165    lim = 17.0 + 4.5 * r + eta
166    lim = max(lim, 4.0)
167    f = lambda x: _func_Fr_x2(x, eta, r)
168
169    ret = 0.0
170    ret += integrate.quad(f, 0.0, 1.0, epsabs=epsabs, epsrel=epsrel, limit=limit)[0]
171    ret += integrate.quad(f, 1.0, 4.0, epsabs=epsabs, epsrel=epsrel, limit=limit)[0]
172    ret += integrate.quad(f, 4.0, lim, epsabs=epsabs, epsrel=epsrel, limit=limit)[0]
173
174    return ret
175
176@lru_cache(maxsize=1024)
177def _FermiIntegral_cached(eta, r, epsabs, epsrel, limit):
178    return _FermiIntegral_core(eta, r, epsabs, epsrel, limit)
179
180# ============================================================
181# public API
182# ============================================================
183
184def FermiIntegral_fast(
185    eta, r,
186    *,
187    epsabs=1.0e-10,
188    epsrel=1.0e-8,
189    limit=50,
190    use_cache = True
191):
192    """
193    General Fermi–Dirac integral F_r(eta)
194    整数次数 (r = -1, 0, 1) については解析解・特殊関数を用いて高速化
195    """
196    # --- 整数次数の解析解 / 特殊関数による高速化 ---
197    is_integer_r = isclose(r, round(r), abs_tol=1e-12)
198    ri = int(round(r)) if is_integer_r else None
199    
200    if is_integer_r:
201    # r = -1: F_{-1}(eta) = 1 / (1 + exp(-eta))
202        if ri == -1:
203            return expit(eta)
204
205    # r = 0: F_0(eta) = ln(1 + exp(eta))
206        if ri == 0:
207            if eta > 0:
208                return eta + np.log1p(np.exp(-eta))
209            else:
210                return np.log1p(np.exp(eta))
211
212    # r = 1: F_1(eta) = -Li2(-exp(eta))
213    # scipy.special.spence(z) は Li2(z) そのものではなく Li2(z)に関連した定義
214    # Li2(z) = spence(1-z) なので、F_1(eta) = -spence(1 + exp(eta))
215        if ri == 1:
216            if eta > 100:
217            # 漸近展開 (eta^2 / 2 + pi^2 / 6)
218                return 0.5 * eta**2 + np.pi**2 / 6.0
219            return -float(spence(1.0 + np.exp(eta)))
220
221    # キャッシュキーの作成と呼び出し
222    key = (
223        _round_key(eta),
224        _round_key(r),
225        epsabs,
226        epsrel,
227        limit,
228    )
229    if use_cache:
230        return _FermiIntegral_cached(*key)
231    else:
232        return _FermiIntegral_core(*key)
233
234def FermiIntegral_half(
235    eta,
236    *,
237    epsabs=1.0e-10,
238    epsrel=1.0e-8,
239    limit=50
240):
241    """F_{1/2}(eta)"""
242
243    return FermiIntegral_fast(
244        eta, 0.5,
245        epsabs=epsabs,
246        epsrel=epsrel,
247        limit=limit
248    )
249
250
251def FermiIntegral_3half(
252    eta,
253    *,
254    epsabs=1.0e-10,
255    epsrel=1.0e-8,
256    limit=50
257):
258    """F_{3/2}(eta)"""
259
260    return FermiIntegral_fast(
261        eta, 1.5,
262        epsabs=epsabs,
263        epsrel=epsrel,
264        limit=limit
265    )
266
267
268# ============================================================
269# carrier density helpers (Gamma-normalization NOT used)
270# ============================================================
271
272def electron_density(Nc, eta_c, *, epsabs=1.0e-10, epsrel=1.0e-8, limit=50):
273    """
274    Electron density (nonparabolicity ignored; standard parabolic band).
275
276    This library defines the (non-normalized) FD integral:
277        I_{1/2}(eta) = ∫_0^∞ ε^{1/2} / (1 + exp(ε - eta)) dε
278    (NO division by Gamma).
279
280    Therefore:
281        n = Nc * (2/sqrt(pi)) * I_{1/2}(eta_c)
282
283    Parameters
284    ----------
285    Nc : float
286        Effective density of states in conduction band [cm^-3] or [m^-3]
287        (unit is carried through).
288    eta_c : float or array-like
289        Dimensionless chemical potential for electrons:
290            eta_c = (Ef - Ec) / (kT) = β(Ef - Ec)
291
292    Returns
293    -------
294    n : float or ndarray
295        Electron density in the same unit as Nc.
296    """
297
298    eta_arr = np.asarray(eta_c)
299    if eta_arr.ndim == 0:
300        return Nc * kF12 * FermiIntegral_half(
301            float(eta_arr), epsabs=epsabs, epsrel=epsrel, limit=limit
302        )
303    out = np.empty_like(eta_arr, dtype=float)
304    it = np.nditer(eta_arr, flags=["multi_index"])
305    for v in it:
306        out[it.multi_index] = Nc * kF12 * FermiIntegral_half(
307            float(v), epsabs=epsabs, epsrel=epsrel, limit=limit
308        )
309    return out
310
311
312def hole_density(Nv, eta_v, *, epsabs=1.0e-10, epsrel=1.0e-8, limit=50):
313    """
314    Hole density (standard parabolic valence band).
315
316    Using the same non-normalized integral I_{1/2}:
317        p = Nv * (2/sqrt(pi)) * I_{1/2}( beta(Ev - Ef) )
318
319    If you pass:
320        eta_v = beta(Ef - Ev)
321    then beta(Ev - Ef) = -eta_v, so:
322        p = Nv * (2/sqrt(pi)) * I_{1/2}(-eta_v)
323
324    Parameters
325    ----------
326    Nv : float
327        Effective density of states in valence band [cm^-3] or [m^-3]
328        (unit is carried through).
329    eta_v : float or array-like
330        Dimensionless quantity defined as:
331            eta_v = (Ef - Ev) / (kT) = β(Ef - Ev)
332
333    Returns
334    -------
335    p : float or ndarray
336        Hole density in the same unit as Nv.
337    """
338
339    eta_arr = np.asarray(eta_v)
340    if eta_arr.ndim == 0:
341        return Nv * kF12 * FermiIntegral_half(
342            float(-eta_arr), epsabs=epsabs, epsrel=epsrel, limit=limit
343        )
344    out = np.empty_like(eta_arr, dtype=float)
345    it = np.nditer(eta_arr, flags=["multi_index"])
346    for v in it:
347        out[it.multi_index] = Nv * kF12 * FermiIntegral_half(
348            float(-v), epsabs=epsabs, epsrel=epsrel, limit=limit
349        )
350    return out
351
352
353# ============================================================
354# self-test
355# ============================================================
356
357if __name__ == "__main__":
358    Nc = 1.0e19
359    Nv = 1.0e19
360    eta_list = [-10.0, -3.0, -1.0, 0.0, 2.0, 5.0, 10.0]
361
362    print("Fermi–Dirac integral test")
363    print("")
364
365    print("r = 1/2")
366    for eta in eta_list:
367        print(f"  eta={eta:6.2f}  F1/2={FermiIntegral_half(eta):.8e}")
368
369    print("\nr = 3/2")
370    for eta in eta_list:
371        n = electron_density(Nc, eta)
372        p = hole_density(Nv, eta)
373        print(f"  eta={eta:6.2f}  F3/2={FermiIntegral_3half(eta):.8e}  n={n:.8e}  p={p:.8e}")
374
375    print("\ncache info:")
376    print(_FermiIntegral_cached.cache_info())
377