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