#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
概要:
    水素様原子に対する両方向Numerov法による動径Schrodinger方程式の教材スクリプトです。

準備:
    python -m pip install numpy scipy matplotlib

実行例:
    python hydrogen_numerov.py
    python hydrogen_numerov.py --Z 1 --n 2 --l 0 --check
    python hydrogen_numerov.py --Z 1 --n 3 --l 2 --check --no-show

物理と単位:
    P(r) = r R(r), integral P(r)^2 dr = 1, r は Bohr半径 a0 単位です。
    P'' = [l(l+1)/r^2 - 2Z/r - E_Ry] P となります。
    E_Ry = 2 E_Hartree です。元のPerlコードもこのRy表記を採用しています。
    無限質量の核、非相対論、一電子Coulomb問題として扱います。
    解析解は E_Ry = -Z^2/n^2 で、節の数は n-l-1 です。

アルゴリズム:
    内部座標 rho = Z*r, e = E_Ry/Z^2 を使用し、Zによる格子精度の差を避けます。
    Numerov更新式を使用して両側から接続点まで積分し、離散WronskianのゼロをBrent法で探索します。
    原点側は rho のべき級数、遠方側は漸近級数で初期化します。
    エネルギーと波動関数はNumerov積分から計算し、解析解と比較します。

出力:
    指定された接頭辞をもとにCSVとPNGファイルを出力します。

参考:
    https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.brentq.html
    https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.eval_genlaguerre.html
    原コード HS-DoubleSide-Noumerov.pl
"""
from __future__ import annotations
import argparse
from dataclasses import dataclass
from pathlib import Path
import sys
import numpy as np
from scipy.integrate import simpson
from scipy.optimize import brentq
from scipy.special import eval_genlaguerre, gammaln


@dataclass
class Grid:
    """
    概要:
        計算用のグリッド情報を保持するデータクラスです。
    詳細説明:
        内部座標や刻み幅、接続点、方位量子数などのパラメータを管理します。
    引数:
        :param rho: 内部座標の配列
        :type rho: numpy.ndarray
        :param h: 座標の刻み幅
        :type h: float
        :param match: 接続点のインデックス
        :type match: int
        :param l: 方位量子数
        :type l: int
    """
    rho: np.ndarray
    h: float
    match: int
    l: int


def make_grid(n, l, step, maximum, match=None):
    """
    概要:
        計算用のグリッドを生成します。
    詳細説明:
        指定されたパラメータに基づいて、内部座標配列や接続点を計算しGridオブジェクトを返します。
    引数:
        :param n: 主量子数
        :type n: int
        :param l: 方位量子数
        :type l: int
        :param step: 内部座標の刻み幅
        :type step: float
        :param maximum: 内部座標の上限
        :type maximum: float
        :param match: 接続点となる内部座標の値、またはNone
        :type match: float or None
    戻り値:
        :returns: 生成されたグリッド情報
        :rtype: Grid
    例外:
        :raises ValueError: グリッドの区間数が不正な場合、または接続点が適切でない場合
    """
    count = int(np.ceil(maximum/step))
    if count < 100 or count > 500000:
        raise ValueError('Grid requires 100..500000 intervals; change --step/--rhomax.')
    h = maximum/count
    rho = h*np.arange(1, count+1)  # rho=0ではODEを評価しない
    # 対象準位の外側古典転回点。通常、節を避けて接続できる。
    target = n*n+np.sqrt(n**4-l*(l+1)*n*n) if match is None else match
    m = int(round(target/h))-1
    if not 4 <= m <= count-5:
        raise ValueError('Matching point must lie well inside the grid.')
    if rho[0]*(l+1) > 0.1:
        raise ValueError('Origin grid too coarse; reduce --step.')
    return Grid(rho, h, m, l)


def origin(rho, e, l):
    """
    概要:
        原点側の境界条件に基づく波動関数の初期値を計算します。
    詳細説明:
        常微分方程式から係数を逐次決定し、rhoのべき級数として計算します。
    引数:
        :param rho: 内部座標の配列
        :type rho: numpy.ndarray
        :param e: スケールされたエネルギー
        :type e: float
        :param l: 方位量子数
        :type l: int
    戻り値:
        :returns: 原点付近の波動関数の配列
        :rtype: numpy.ndarray
    """
    coef = [1.]
    for j in range(1, 13):
        prev2 = coef[j-2] if j >= 2 else 0.
        coef.append((-2*coef[j-1]-e*prev2)/(j*(2*l+j+1)))
    return rho**(l+1)*np.polynomial.polynomial.polyval(rho, coef)


def tail(rho, e, l):
    """
    概要:
        遠方側の境界条件に基づく波動関数の初期値を計算します。
    詳細説明:
        漸近級数を使用して初期値を計算し、共通指数を除いてアンダーフローを回避します。
    引数:
        :param rho: 内部座標の配列
        :type rho: numpy.ndarray
        :param e: スケールされたエネルギー
        :type e: float
        :param l: 方位量子数
        :type l: int
    戻り値:
        :returns: 遠方付近の波動関数の配列
        :rtype: numpy.ndarray
    """
    k = np.sqrt(-e)
    s = 1/k
    term = np.ones_like(rho)
    series = term.copy()
    for j in range(1, 9):
        term = term*(-((s-j+1)*(s-j)-l*(l+1))/(2*k*j))/rho
        series += term
    return np.exp(-k*(rho-rho[-1])+s*np.log(rho/rho[-1]))*series


def integrate_sides(e, grid):
    """
    概要:
        Numerov法を用いて両側から波動関数を積分します。
    詳細説明:
        接続点の周囲だけ重複させることで、不要な側への不安定な長距離積分を避けます。
    引数:
        :param e: スケールされたエネルギー
        :type e: float
        :param grid: グリッド情報
        :type grid: Grid
    戻り値:
        :returns: 前進積分の結果と後退積分の結果のタプル
        :rtype: tuple
    例外:
        :raises ValueError: Numerov法の分母がゼロに近すぎる場合
        :raises RuntimeError: 積分の過程でオーバーフローが発生した場合
    """
    x, h, m, l = grid.rho, grid.h, grid.match, grid.l
    g = l*(l+1)/x**2-2/x-e
    a = 1-h*h*g/12
    b = 2*(1+5*h*h*g/12)
    if np.min(np.abs(a)) < 1e-8:
        raise ValueError('Numerov denominator near zero; reduce --step.')
    f, q = np.full(len(x), np.nan), np.full(len(x), np.nan)
    f[:2] = origin(x[:2], e, l)
    q[-2:] = tail(x[-2:], e, l)
    for i in range(1, m+2):
        f[i+1] = (b[i]*f[i]-a[i-1]*f[i-1])/a[i+1]
    for i in range(len(x)-2, m-2, -1):
        q[i-1] = (b[i]*q[i]-a[i+1]*q[i+1])/a[i-1]
    if not np.all(np.isfinite(f[:m+3])) or not np.all(np.isfinite(q[m-2:])):
        raise RuntimeError('Numerov overflow; use a smaller domain/state.')
    # 正の係数での再スケール。Wronskianの符号を保存する。
    f /= np.max(np.abs(f[:m+3]))
    q /= np.max(np.abs(q[m-2:]))
    return f, q


def mismatch(e, grid):
    """
    概要:
        接続点における前進解と後退解の不一致度を計算します。
    詳細説明:
        離散Wronskianを評価して、両側からの解が滑らかに接続するかを判定する値を返します。
    引数:
        :param e: スケールされたエネルギー
        :type e: float
        :param grid: グリッド情報
        :type grid: Grid
    戻り値:
        :returns: 正規化された離散Wronskianの値
        :rtype: float
    """
    f, q = integrate_sides(e, grid)
    m = grid.match
    fv, qv = f[m:m+2], q[m:m+2]
    return (fv[0]*qv[1]-fv[1]*qv[0])/(np.linalg.norm(fv)*np.linalg.norm(qv))


def energy_bracket(n, l):
    """
    概要:
        対象となる準位のエネルギー探索区間を計算します。
    詳細説明:
        同じ方位量子数に対する隣接準位との中点を用いて、エネルギー探索の上限と下限を定めます。
    引数:
        :param n: 主量子数
        :type n: int
        :param l: 方位量子数
        :type l: int
    戻り値:
        :returns: 探索区間の下限と上限のタプル
        :rtype: tuple
    """
    # 同じlに対する隣接準位との中点で、1つの対象状態を囲む。
    lower = -2/n**2 if n == l+1 else (-1/(n-1)**2-1/n**2)/2
    upper = (-1/n**2-1/(n+1)**2)/2
    return lower, upper


def solve_state(n, l, step, maximum, match=None, bracket=None):
    """
    概要:
        指定された量子状態に対するエネルギー固有値と波動関数を計算します。
    詳細説明:
        Brent法を用いてエネルギーを探索し、求まった固有値で波動関数を計算して規格化します。
    引数:
        :param n: 主量子数
        :type n: int
        :param l: 方位量子数
        :type l: int
        :param step: 内部座標の刻み幅
        :type step: float
        :param maximum: 内部座標の上限
        :type maximum: float
        :param match: 接続点となる内部座標の値、またはNone
        :type match: float or None
        :param bracket: エネルギー探索区間のタプル、またはNone
        :type bracket: tuple or None
    戻り値:
        :returns: グリッド、エネルギー、座標、波動関数などの情報を含む辞書
        :rtype: dict
    例外:
        :raises RuntimeError: 波束の節の数が期待値と異なる場合
    """
    grid = make_grid(n, l, step, maximum, match)
    bounds = energy_bracket(n, l) if bracket is None else bracket
    e, result = brentq(mismatch, *bounds, args=(grid,), xtol=2e-13,
                       rtol=2e-13, maxiter=100, full_output=True)
    f, q = integrate_sides(e, grid)
    m = grid.match
    overlap = slice(m-2, m+3)
    # 1点で割らず重複領域の最小二乗で振幅を合わせる（節の近くでも安定）。
    q *= np.dot(f[overlap], q[overlap])/np.dot(q[overlap], q[overlap])
    x = np.r_[0., grid.rho]
    u = np.r_[0., f[:m+1], q[m+1:]]
    norm = np.sqrt(simpson(u*u, x=x))
    u, f, q = u/norm, f/norm, q/norm
    # 厳密ゼロの格子点を除いて符号変化を数える。
    nonzero = u[1:][u[1:] != 0]
    nodes = int(np.count_nonzero(nonzero[1:]*nonzero[:-1] < 0))
    if nodes != n-l-1:
        raise RuntimeError(f'Wrong state: nodes={nodes}, expected={n-l-1}. Check bracket/grid.')
    return dict(grid=grid, e=e, x=x, u=u, f=np.r_[0., f], q=np.r_[np.nan, q],
                nodes=nodes, iterations=result.iterations, bounds=bounds,
                mismatch=mismatch(e, grid))


def exact_u(x, n, l):
    """
    概要:
        解析的な動径波動関数を計算します。
    詳細説明:
        核電荷Zが1のとき規格化された動径関数 u = xR をLaguerre多項式を用いて計算します。
    引数:
        :param x: 座標の配列
        :type x: numpy.ndarray
        :param n: 主量子数
        :type n: int
        :param l: 方位量子数
        :type l: int
    戻り値:
        :returns: 解析的な波動関数の値の配列
        :rtype: numpy.ndarray
    """
    pref = np.exp(0.5*(3*np.log(2/n)+gammaln(n-l)-np.log(2*n)-gammaln(n+l+1)))
    t = 2*x/n
    return pref*x*np.exp(-x/n)*t**l*eval_genlaguerre(n-l-1, 2*l+1, t)


def main(argv=None):
    """
    概要:
        コマンドライン引数を解析し、計算の実行と結果の出力を行います。
    詳細説明:
        水素様原子の動径方程式を解き、解析解との比較結果を標準出力に表示し、CSVおよびPNGファイルとして保存します。
    引数:
        :param argv: コマンドライン引数のリスト、またはNone
        :type argv: list or None
    戻り値:
        :returns: なし
        :rtype: None
    """
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument('--Z', type=float, default=5., help='核電荷 (default: 5)')
    ap.add_argument('--n', type=int, default=1, help='主量子数 (1..8)')
    ap.add_argument('--l', type=int, default=0, help='方位量子数 (0..n-1)')
    ap.add_argument('--step', type=float, default=0.005, help='内部座標rho=Zrの刻み')
    ap.add_argument('--rhomax', type=float, help='内部座標の上限。既定max(40,12n^2)')
    ap.add_argument('--match', type=float, help='内部座標での接続点（既定:外側転回点）')
    ap.add_argument('--bracket', nargs=2, type=float, metavar=('LOW', 'HIGH'), help='e=E_Ry/Z^2 の探索区間')
    ap.add_argument('--check', action='store_true', help='刻み半減・範囲1.5倍の確認')
    ap.add_argument('--prefix', default='hydrogen_numerov', help='CSV/PNG名の接頭辞')
    ap.add_argument('--no-show', action='store_true', help='図を表示せず保存のみ')
    args = ap.parse_args(argv)
    maximum = args.rhomax if args.rhomax is not None else max(40., 12.*args.n**2)
    if not (1 <= args.n <= 8 and 0 <= args.l < args.n):
        ap.error('1 <= n <= 8, 0 <= l < n が必要です。')
    if not all(np.isfinite(v) and v > 0 for v in (args.Z, args.step, maximum)):
        ap.error('Z, step, rhomax は正の有限値にしてください。')
    if args.match is not None and not np.isfinite(args.match):
        ap.error('match は有限値にしてください。')
    if args.bracket and not (np.all(np.isfinite(args.bracket)) and args.bracket[0] < args.bracket[1] < 0):
        ap.error('bracket は LOW < HIGH < 0 にしてください。')
    s = solve_state(args.n, args.l, args.step, maximum, args.match, args.bracket)
    e, z = s['e'], args.Z
    r = s['x']/z
    p = np.sqrt(z)*s['u']
    analytic = np.sqrt(z)*exact_u(s['x'], args.n, args.l)
    error = np.sqrt(simpson((p-analytic)**2, x=r))
    radial = np.full_like(r, np.nan)
    radial[1:] = p[1:]/r[1:]
    print(f'Hydrogen-like ion: Z={z:g}, n={args.n}, l={args.l}')
    print(f'Energy [Ry]     : {e*z*z:.12f}  (exact {-z*z/args.n**2:.12f})')
    print(f'Energy [Hartree]: {e*z*z/2:.12f}')
    print(f'Relative E error: {abs(e+1/args.n**2)*args.n**2:.3e}')
    print(f'Norm integral   : {simpson(p*p, x=r):.12f}')
    print(f'Radial nodes    : {s["nodes"]} (expected {args.n-args.l-1})')
    print(f'Wavefunction L2 error: {error:.3e}')
    print(f'Matching residual   : {s["mismatch"]:.3e}; Brent iterations: {s["iterations"]}')
    print(f'rmax={r[-1]:g} a0; dr={s["grid"].h/z:g} a0; match={s["grid"].rho[s["grid"].match]/z:g} a0')
    print('Finite grid/domain and asymptotic boundary errors are separate from root tolerance.')
    if args.check:
        for label, step, extent in [('Half step', args.step/2, maximum), ('Larger domain', args.step, maximum*1.5)]:
            other = solve_state(args.n, args.l, step, extent, args.match, args.bracket)
            print(f'{label:15s}: E_Ry={other["e"]*z*z:.12f}; delta E_Ry={(other["e"]-e)*z*z:+.3e}')
    prefix = Path(args.prefix)
    prefix.parent.mkdir(parents=True, exist_ok=True)
    np.savetxt(str(prefix)+'.csv', np.column_stack((r, p, radial, p*p, analytic, p-analytic,
                np.sqrt(z)*s['f'], np.sqrt(z)*s['q'])), delimiter=',', comments='',
                header='r_a0,P,R,radial_probability,P_exact,P_error,P_outward,P_inward', fmt='%.12e')
    import matplotlib
    if args.no_show:
        matplotlib.use('Agg')
    import matplotlib.pyplot as plt
    fig, axes = plt.subplots(2, 2, figsize=(12, 8), constrained_layout=True)
    match_r = s['grid'].rho[s['grid'].match]/z
    ax = axes[0, 0]
    ax.plot(r, p, label='Numerov', lw=2)
    ax.plot(r, analytic, '--', label='Analytical', lw=1.5)
    ax.axvline(match_r, color='gray', ls=':', label='Matching point')
    ax.set(ylabel='P(r) = r R(r)', title='Normalized radial wavefunction')
    ax.legend()
    ax = axes[0, 1]
    ax.plot(r, p*p)
    ax.set(ylabel='P(r)^2', title='Radial probability density (integral = 1)')
    ax = axes[1, 0]
    ax.plot(r, p-analytic)
    ax.set(ylabel='P - P exact', title=f'Wavefunction error; L2 = {error:.2e}')
    for ax in axes.flat[:3]:
        ax.set(xlim=(0, min(r[-1], 8*args.n**2/z)), xlabel='r / a0')
    # 接続条件のエネルギー依存性を描く。計算解の探索とは独立の描画用走査。
    es = np.linspace(*s['bounds'], 51)
    ws = np.array([mismatch(value, s['grid']) for value in es])
    ax = axes[1, 1]
    ax.plot(es*z*z, ws)
    ax.axhline(0, color='gray', lw=0.8)
    ax.axvline(e*z*z, color='tab:red', ls='--', label='Numerical eigenvalue')
    ax.set(xlabel='Energy / Ry', ylabel='Normalized discrete Wronskian', title='Matching condition: W(E) = 0')
    ax.legend()
    for ax in axes.flat:
        ax.grid(alpha=0.25)
    fig.suptitle(f'Two-sided Numerov: Z={z:g}, n={args.n}, l={args.l}, E={e*z*z:.8f} Ry')
    fig.savefig(str(prefix)+'.png', dpi=150)
    print(f'Saved: {prefix}.csv\nSaved: {prefix}.png')
    if not args.no_show:
        plt.show()
    plt.close(fig)


if __name__ == '__main__':
    try:
        main()
    except (RuntimeError, ValueError, OSError) as exc:
        print(f'Error: {exc}', file=sys.stderr)
        sys.exit(1)