"""
概要:
    1D分子のHuckelモデルを計算し、分子軌道エネルギーと係数を求めるスクリプトです。

詳細説明:
    サイトエネルギーと移動積分からHamiltonianを作成し、固有値問題を解いて
    各分子軌道のエネルギーと係数を算出します。計算結果はCSVとして保存され、
    グラフとして可視化されます。

関連リンク:
    huckel1d_usage
"""
import numpy as np
import matplotlib.pyplot as plt
import pandas as pd

# ============================
# パラメータ設定
# ============================

def initialize():
    """
    概要:
        1D分子のHuckelモデルのパラメータを初期化します。

    詳細説明:
        オンサイトエネルギーのリスト onsite と、最隣接サイト間の移動積分のリスト hopping を設定します。
        s軌道同士の場合、移動積分は負になることに注意してください。

    戻り値:
        :returns: onsiteとhoppingを含むパラメータ辞書
        :rtype: dict
    """
    params = {}

    # 例：4 原子直鎖分子。s軌道同士の場合、移送積分は負であることに注意
    params["onsite"]  = [ 0.0,  0.1,  0.2, 0.1]
    params["hopping"] = [-1.0, -1.1, -0.9]  # 原子 i–(i+1)

    return params


# ============================
# Hamiltonian（有限鎖）
# ============================

def hamiltonian_molecule(onsite, hopping):
    """
    概要:
        1D分子のHuckel Hamiltonianを作成します。

    詳細説明:
        周期境界条件なしの有限鎖モデルとして、オンサイトエネルギーと
        最隣接サイト間の移動積分を用いて行列を構築します。

    引数:
        :param onsite: オンサイトエネルギーのリスト
        :type onsite: list
        :param hopping: 最隣接サイト間の移動積分のリスト
        :type hopping: list

    戻り値:
        :returns: Huckel Hamiltonian行列
        :rtype: numpy.ndarray
    """
    norb = len(onsite)
    H = np.zeros((norb, norb))

    # onsite
    for i in range(norb):
        H[i, i] = onsite[i]

    # nearest-neighbor hopping
    for i in range(norb - 1):
        H[i, i + 1] = hopping[i]
        H[i + 1, i] = hopping[i]

    return H


# ============================
# 計算
# ============================

def solve_molecule(onsite, hopping):
    """
    概要:
        Hamiltonianの固有値と固有ベクトルを計算します。

    引数:
        :param onsite: オンサイトエネルギーのリスト
        :type onsite: list
        :param hopping: 最隣接サイト間の移動積分のリスト
        :type hopping: list

    戻り値:
        :returns: 固有値の配列と固有ベクトルの配列のタプル
        :rtype: tuple
    """
    H = hamiltonian_molecule(onsite, hopping)
    eigvals, eigvecs = np.linalg.eigh(H)
    return eigvals, eigvecs


# ============================
# 出力
# ============================

def save_results(filename, eigvals, eigvecs):
    """
    概要:
        固有値と固有ベクトルの計算結果をCSVファイルに出力します。

    引数:
        :param filename: 出力するCSVファイル名
        :type filename: str
        :param eigvals: 固有値の配列
        :type eigvals: numpy.ndarray
        :param eigvecs: 固有ベクトルの配列
        :type eigvecs: numpy.ndarray
    """
    df = pd.DataFrame(eigvecs, columns=[f"MO_{i}" for i in range(len(eigvals))])
    df.insert(0, "Energy", eigvals)
    df.to_csv(filename, index=False)

def plot_molecular_orbitals_vstack(eigvecs, eigvals=None):
    """
    概要:
        計算された分子軌道を縦に積んでグラフとして表示します。

    詳細説明:
        x軸を共有し、枠を密着させた状態で各分子軌道の係数をプロットします。

    引数:
        :param eigvecs: 固有ベクトルの配列
        :type eigvecs: numpy.ndarray
        :param eigvals: 固有値の配列、またはNone
        :type eigvals: numpy.ndarray, optional
    """
    norb = eigvecs.shape[0]
    x = np.arange(norb)

    n_mo = eigvecs.shape[1]

    fig, axes = plt.subplots(
        n_mo, 1,
        figsize=(6, 1.2 * n_mo),
        sharex=True,
        gridspec_kw={"hspace": 0}
    )

    # MO が 1 本のときの保険
    if n_mo == 1:
        axes = [axes]

    # グラフの表示スケールを合わせるため、係数の最大値を取得
    ymax = np.max(np.abs(eigvecs))

    for i, ax in enumerate(axes):
        i_mo = n_mo - 1 - i

        if eigvals is not None:
            label = f"MO #{i_mo} E={eigvals[i_mo]:.2f}"
        else:
            label = f"MO #{i_mo}"
        ax.plot(x, eigvecs[:, i_mo], marker="o", label = label)
        ax.axhline(0, color="gray", lw=0.5)

        # y ラベル（エネルギーがあれば併記）
        ax.set_ylabel(f"$c_i$")

        # 下以外は x 軸ラベル・目盛り文字を消す
        if i != n_mo - 1:
            ax.tick_params(labelbottom=False)

        ax.set_ylim(-ymax, ymax)        
        ax.legend()

    axes[-1].set_xlabel("Atom index")

    plt.tight_layout()
    plt.show()

# ============================
# main
# ============================

def main():
    """
    概要:
        1D分子のHuckelモデル計算を実行するメイン関数です。

    詳細説明:
        パラメータの初期化、固有値計算、結果のコンソール出力、CSV保存、グラフ描画を順に行います。
    """
    params = initialize()
    onsite = params["onsite"]
    hopping = params["hopping"]

    eigvals, eigvecs = solve_molecule(onsite, hopping)

    print("固有値（分子軌道エネルギー）:")
    for i, e in enumerate(eigvals):
        print(f"MO {i}: {e:.4f}")

    save_results("huckel_1d_molecule.csv", eigvals, eigvecs)
    print("huckel_1d_molecule.csv を出力しました")

    plot_molecular_orbitals_vstack(eigvecs, eigvals)


# ============================
# entry point
# ============================

if __name__ == "__main__":
    main()