#!/usr/bin/env python3
"""
概要:
    放物線バンド半導体のキャリア統計を計算します。
詳細説明:
    エネルギーの単位はeV、密度の単位はcm^-3です。
    動作にはnumpy、scipy、matplotlibが必要です。
    価電子帯の上端Evを0、伝導帯の下端EcをEgとします。
    ドナー準位EDはEc-Ed、アクセプタ準位EAはEv+Eaとして扱います。
    有効質量は静止電子質量m0を単位とします。
    Fjは規格化された完全フェルミ・ディラック積分であり、ボルツマン近似は使用しません。
    バンドギャップEgおよび有効質量は固定、不純物は独立、3次元放物線バンドを仮定しています。
"""
import argparse
from dataclasses import dataclass
from math import exp, gamma, log, pi, sqrt
from pathlib import Path

import numpy as np
from scipy.constants import Boltzmann, electron_mass, elementary_charge, h
from scipy.integrate import quad
from scipy.optimize import brentq
from scipy.special import expit

KB = Boltzmann / elementary_charge  # eV/K


@dataclass(frozen=True)
class Model:
    """
    概要:
        半導体の物理モデルパラメータを保持するデータクラスです。
    詳細説明:
        バンドギャップ、有効質量、不純物密度、結合エネルギーなどのパラメータを格納します。
    引数:
        :param Eg: バンドギャップエネルギー (eV)。
        :type Eg: float
        :param me: 伝導帯の状態密度有効質量。バレー縮退度を含みます。
        :type me: float
        :param mh: 価電子帯の状態密度有効質量。
        :type mh: float
        :param ND: ドナー濃度 (cm^-3)。
        :type ND: float
        :param NA: アクセプタ濃度 (cm^-3)。
        :type NA: float
        :param Ed: 伝導帯の下端Ecから測ったドナーの結合エネルギー (eV)。
        :type Ed: float
        :param Ea: 価電子帯の上端Evから測ったアクセプタの結合エネルギー (eV)。
        :type Ea: float
        :param gD: ドナーの縮退度。
        :type gD: float
        :param gA: アクセプタの縮退度。
        :type gA: float
    """
    Eg: float = 1.12
    me: float = 1.08  # density-of-states effective mass (includes valley degeneracy)
    mh: float = 0.56
    ND: float = 1e16
    NA: float = 0.0
    Ed: float = 0.045  # donor binding energy below Ec
    Ea: float = 0.045  # acceptor binding energy above Ev
    gD: float = 2.0
    gA: float = 4.0


def m2Nc(m, T):
    """
    概要:
        伝導帯の有効状態密度を計算します。
    詳細説明:
        スピン縮退度2を考慮した伝導帯の状態密度をcm^-3単位で返します。
    引数:
        :param m: 有効質量。
        :type m: float
        :param T: 温度 (K)。
        :type T: float
    戻り値:
        :returns: 有効状態密度 (cm^-3)。
        :rtype: float
    """
    return 2 * (2 * pi * m * electron_mass * Boltzmann * T / h**2)**1.5 / 1e6


def m2Nv(m, T):
    """
    概要:
        価電子帯の有効状態密度を計算します。
    詳細説明:
        価電子帯の状態密度をcm^-3単位で返します。
    引数:
        :param m: 有効質量。
        :type m: float
        :param T: 温度 (K)。
        :type T: float
    戻り値:
        :returns: 有効状態密度 (cm^-3)。
        :rtype: float
    """
    return m2Nc(m, T)


def fe(E, Ef, T):
    """
    概要:
        電子のフェルミ・ディラック分布関数を計算します。
    引数:
        :param E: エネルギー準位 (eV)。
        :type E: float or numpy.ndarray
        :param Ef: フェルミ準位 (eV)。
        :type Ef: float
        :param T: 温度 (K)。
        :type T: float
    戻り値:
        :returns: 電子の占有確率。
        :rtype: float or numpy.ndarray
    """
    return expit((Ef - np.asarray(E)) / (KB * T))


def fh(E, Ef, T):
    """
    概要:
        正孔のフェルミ・ディラック分布関数を計算します。
    詳細説明:
        価電子帯がほぼ満たされている場合の桁落ちを防ぐため、1からfeを引くのではなく直接計算します。
    引数:
        :param E: エネルギー準位 (eV)。
        :type E: float or numpy.ndarray
        :param Ef: フェルミ準位 (eV)。
        :type Ef: float
        :param T: 温度 (K)。
        :type T: float
    戻り値:
        :returns: 正孔の占有確率。
        :rtype: float or numpy.ndarray
    """
    # Avoid cancellation in 1-fe for a nearly full valence band.
    return expit((np.asarray(E) - Ef) / (KB * T))


def Fj(eta, j=0.5):
    """
    概要:
        規格化された完全フェルミ・ディラック積分を計算します。
    詳細説明:
        積分区間を占有領域と熱的な裾の部分に分割し、適応型数値積分を適用することで
        フェルミ端を高い精度で解決します。etaが0未満の場合は厳密なロジスティック恒等式を用いて
        指数関数をくくり出し、ボルツマン近似を使わずに相対精度を維持します。
    引数:
        :param eta: フェルミ準位とエネルギーバンド端の差をkTで割った無次元量。
        :type eta: float
        :param j: 積分の次数。デフォルトは0.5です。
        :type j: float
    戻り値:
        :returns: フェルミ・ディラック積分の値。
        :rtype: float
    例外:
        :raises ValueError: etaが非有限、またはjが-0.5以下の場合に発生します。
    """
    if not np.isfinite(eta) or j <= -0.5:
        raise ValueError('Fj requires finite eta and j > -0.5')
    scale = exp(eta) if eta < 0 else 1.0
    if scale == 0:
        return 0.0  # below floating-point representability
    def integrand(t):
        x = t*t
        f = exp(-x) * expit(x - eta) if eta < 0 else expit(eta - x)
        return 2 * t**(2*j + 1) * f
    cuts = [0.0]
    if eta > 0:
        cuts += [sqrt(max(eta - 40, 0)), sqrt(eta)]
    cuts += [sqrt(max(eta, 0) + 80)]
    cuts = sorted(set(cuts))
    value = sum(quad(integrand, a, b, epsabs=1e-11, epsrel=2e-9,
                     limit=200)[0] for a, b in zip(cuts[:-1], cuts[1:]))
    return scale * value / gamma(j + 1)


def Ne(Ef, T, s):
    """
    概要:
        伝導帯の電子密度を計算します。
    引数:
        :param Ef: フェルミ準位 (eV)。
        :type Ef: float
        :param T: 温度 (K)。
        :type T: float
        :param s: 半導体モデルパラメータ。
        :type s: Model
    戻り値:
        :returns: 電子密度 (cm^-3)。
        :rtype: float
    """
    return m2Nc(s.me, T) * Fj((Ef - s.Eg) / (KB*T))


def Nh(Ef, T, s):
    """
    概要:
        価電子帯の正孔密度を計算します。
    引数:
        :param Ef: フェルミ準位 (eV)。
        :type Ef: float
        :param T: 温度 (K)。
        :type T: float
        :param s: 半導体モデルパラメータ。
        :type s: Model
    戻り値:
        :returns: 正孔密度 (cm^-3)。
        :rtype: float
    """
    return m2Nv(s.mh, T) * Fj(-Ef / (KB*T))


def NDp(Ef, T, s):
    """
    概要:
        イオン化したドナーの密度を計算します。
    詳細説明:
        ND+ = ND / (1 + gD exp((Ef-ED)/kT)) を計算します。
    引数:
        :param Ef: フェルミ準位 (eV)。
        :type Ef: float
        :param T: 温度 (K)。
        :type T: float
        :param s: 半導体モデルパラメータ。
        :type s: Model
    戻り値:
        :returns: イオン化ドナー密度 (cm^-3)。
        :rtype: float
    """
    return s.ND * expit((s.Eg - s.Ed - Ef)/(KB*T) - log(s.gD))


def NAm(Ef, T, s):
    """
    概要:
        イオン化したアクセプタの密度を計算します。
    詳細説明:
        NA- = NA / (1 + gA exp((EA-Ef)/kT)) を計算します。
    引数:
        :param Ef: フェルミ準位 (eV)。
        :type Ef: float
        :param T: 温度 (K)。
        :type T: float
        :param s: 半導体モデルパラメータ。
        :type s: Model
    戻り値:
        :returns: イオン化アクセプタ密度 (cm^-3)。
        :rtype: float
    """
    return s.NA * expit((Ef - s.Ea)/(KB*T) - log(s.gA))


def deltaQ(Ef, T, s):
    """
    概要:
        電荷の中性条件からのズレを計算します。
    詳細説明:
        正孔密度、イオン化ドナー密度の和から、電子密度、イオン化アクセプタ密度の和を引いた値を返します。
    引数:
        :param Ef: フェルミ準位 (eV)。
        :type Ef: float
        :param T: 温度 (K)。
        :type T: float
        :param s: 半導体モデルパラメータ。
        :type s: Model
    戻り値:
        :returns: 正電荷と負電荷の差。
        :rtype: float
    """
    return Nh(Ef, T, s) - Ne(Ef, T, s) + NDp(Ef, T, s) - NAm(Ef, T, s)


def solve(T, s):
    """
    概要:
        指定された温度でのフェルミ準位を求めます。
    詳細説明:
        電荷の中性条件を満たすフェルミ準位を、ブレント法を用いて反復的に探索します。
        探索区間は必要に応じて拡大されます。
    引数:
        :param T: 温度 (K)。
        :type T: float
        :param s: 半導体モデルパラメータ。
        :type s: Model
    戻り値:
        :returns: フェルミ準位 (eV)。
        :rtype: float
    例外:
        :raises RuntimeError: 探索範囲内で電荷が非有限になった場合、または解を囲い込めなかった場合に発生します。
    """
    center = s.Eg / 2
    width = max(s.Eg/2, 10*KB*T, 0.1)
    scale = max(s.ND, s.NA, m2Nc(s.me, T), m2Nv(s.mh, T), 1.0)
    def q(E):
        return deltaQ(E, T, s) / scale
    for _ in range(80):
        lo, hi = center-width, center+width
        qlo, qhi = q(lo), q(hi)
        if not np.isfinite([qlo, qhi]).all():
            raise RuntimeError(f'Nonfinite charge at T={T:g} K')
        if qlo >= 0 and qhi <= 0:
            return brentq(q, lo, hi, xtol=1e-13, rtol=1e-14)
        width *= 2
    raise RuntimeError(f'Cannot bracket Ef at T={T:g} K')


def initialize(argv=None):
    """
    概要:
        コマンドライン引数を解析し、モデルと設定を初期化します。
    詳細説明:
        各種物理パラメータや温度範囲、出力ファイル名などの引数を受け取り、
        エラーチェックを行ったうえで返します。
    引数:
        :param argv: コマンドライン引数のリスト。デフォルトはNoneです。
        :type argv: list or None
    戻り値:
        :returns: 解析された引数とモデルパラメータのタプル。
        :rtype: tuple
    """
    parser = argparse.ArgumentParser(description=__doc__,
                                    formatter_class=argparse.RawDescriptionHelpFormatter)
    defaults = Model()
    for name in ('Eg', 'me', 'mh', 'ND', 'NA', 'Ed', 'Ea', 'gD', 'gA'):
        parser.add_argument('--'+name, type=float, default=getattr(defaults, name))
    parser.add_argument('--Tmin', type=float, default=50)
    parser.add_argument('--Tmax', type=float, default=600)
    parser.add_argument('--nT', type=int, default=112)
    parser.add_argument('--Nmin', type=float, default=1e10)
    parser.add_argument('--Nmax', type=float, default=1e22)
    parser.add_argument('--csv', default='carrier_statistics.csv')
    parser.add_argument('--save', help='Plot filename, e.g. carriers.png')
    parser.add_argument('--no-show', action='store_true')
    a = parser.parse_args(argv)
    for name in ('Eg', 'me', 'mh', 'gD', 'gA', 'Tmin', 'Tmax', 'Nmin', 'Nmax'):
        if not np.isfinite(getattr(a, name)) or getattr(a, name) <= 0:
            parser.error(name+' must be finite and positive')
    for name in ('ND', 'NA', 'Ed', 'Ea'):
        if not np.isfinite(getattr(a, name)) or getattr(a, name) < 0:
            parser.error(name+' must be finite and nonnegative')
    if a.Ed > a.Eg or a.Ea > a.Eg:
        parser.error('Impurity binding energies must lie within the gap')
    if a.Tmax < a.Tmin or a.nT < 1 or a.Nmax <= a.Nmin:
        parser.error('Require Tmax >= Tmin, nT >= 1, Nmax > Nmin')
    return a, Model(**{k: getattr(a, k) for k in Model.__dataclass_fields__})


def main(argv=None):
    """
    概要:
        スクリプトのメイン処理を実行します。
    詳細説明:
        指定された温度範囲についてフェルミ準位と各キャリア密度を計算し、
        標準出力およびCSVファイルへ出力します。オプションでグラフを描画して
        保存または表示します。
    引数:
        :param argv: コマンドライン引数のリスト。デフォルトはNoneです。
        :type argv: list or None
    """
    a, s = initialize(argv)
    print('# Ev=0 eV, Ec=Eg; energy=eV, density=cm^-3; masses=m0')
    print('# Model:', s)
    print('# T[K] Ef[eV] n p ND+ NA- relative_charge_residual')
    rows = []
    for T in np.linspace(a.Tmin, a.Tmax, a.nT):
        Ef = solve(T, s)
        n, p, dp, am = Ne(Ef, T, s), Nh(Ef, T, s), NDp(Ef, T, s), NAm(Ef, T, s)
        residual = (p-n+dp-am)/max(n+p+dp+am, np.finfo(float).tiny)
        rows.append((T, Ef, n, p, dp, am, residual))
        print(f'{T:9.3f} {Ef: .10f} {n:.6e} {p:.6e} {dp:.6e} {am:.6e} {residual: .3e}')
    data = np.array(rows)
    np.savetxt(a.csv, data, delimiter=',',
               header='T_K,Ef_eV,n_cm-3,p_cm-3,NDplus_cm-3,NAminus_cm-3,relative_charge_residual', comments='')
    import matplotlib.pyplot as plt
    fig, ax = plt.subplots(figsize=(9, 5.5), layout='constrained')
    for col, label, style in ((2, 'n', '-'), (3, 'p', '-'), (4, 'ND+', '--'), (5, 'NA-', '--')):
        y = np.where(data[:, col] > 0, data[:, col], np.nan)
        ax.plot(data[:, 0], y, style, label=label)
    ax.set(yscale='log', ylim=(a.Nmin, a.Nmax), xlabel='Temperature (K)',
           ylabel=r'Density (cm$^{-3}$)')
    ax.grid(True, which='both', alpha=0.25)
    right = ax.twinx()
    right.plot(data[:, 0], data[:, 1], 'k-', linewidth=2, label='Ef')
    right.axhline(0, color='gray', linestyle=':', label='Ev')
    right.axhline(s.Eg, color='gray', linestyle='-.', label='Ec')
    right.set_ylabel('Energy relative to Ev (eV)')
    lines, labels = ax.get_legend_handles_labels()
    l2, lab2 = right.get_legend_handles_labels()
    ax.legend(lines+l2, labels+lab2, loc='best', ncol=2)
    ax.set_title('Semiconductor carrier statistics (Fermi-Dirac)')
    if a.save:
        fig.savefig(a.save, dpi=180)
    print(f'# CSV: {Path(a.csv).resolve()}')
    if not a.no_show:
        plt.show()
    plt.close(fig)


if __name__ == '__main__':
    main()