#!/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: 伝導帯下端からのドナー束縛エネルギー(eV)
        :type Ed: float
        :param Ea: 価電子帯上端からのアクセプタ束縛エネルギー(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):
    """
    概要:
        伝導帯の有効状態密度を計算します。
    詳細説明:
        単位は cm^-3 です。スピン縮退度2を考慮しています。
    引数:
        :param m: 有効質量
        :type m: float
        :param T: 絶対温度(K)
        :type T: float
    戻り値:
        :returns: 有効状態密度
        :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: 有効状態密度
        :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):
    """
    概要:
        フェルミ・ディラック積分を計算します。
    詳細説明:
        Fj(eta) = integral_0^inf x^j expit(eta-x) dx / Gamma(j+1) 
        x=t^2 の変数変換により、j=1/2 における平方根の端点を取り除きます。
        積分区間を占有領域と熱的な裾野に分割することで、適応求積法が非常に大きな eta でもフェルミ端を精度良く計算できるようにします。
        etaが負の場合は指数部分をくくり出し、完全なロジスティック恒等式を用いてボルツマン近似なしに相対精度を維持します。
        省略される x > max(eta,0)+80 の裾野は指数関数的に小さな値となります。
    引数:
        :param eta: 規格化されたフェルミエネルギー
        :type eta: float
        :param j: 積分の次数
        :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
    """
    """ND+ = ND/[1+gD exp((Ef-ED)/kT)]."""
    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
    """
    """NA- = NA/[1+gA exp((EA-Ef)/kT)]."""
    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):
    """
    概要:
        電荷中性条件を満たすフェルミエネルギーを求めます。
    詳細説明:
        探索範囲を広げながら解を囲い込み、brentqを用いて方程式の解を計算します。
    引数:
        :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: コマンドライン引数のリスト
        :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: コマンドライン引数のリスト
        :type argv: list or None
    戻り値:
        :returns: なし
        :rtype: 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()