`plot_wf.py` は、水素原子の電子の波動関数を多様な方法で可視化するためのPythonプログラムです。3Dグラフィックス、アニメーション、モンテカルロサンプリングなどを用いて、波動関数の実部、虚部、絶対値、確率密度、位相などの特性を直感的に理解できるように設計されています。

---

### 1) プログラムの動作

`plot_wf.py` は、水素原子の波動関数を様々な形式で可視化するプログラムです。主な機能は以下の通りです。

1.  **水素原子波動関数の計算**: `tkWavefunction_H` モジュールを利用して、主量子数 $n$、方位量子数 $l$、磁気量子数 $m$ に基づく動径波動関数 ($R_{nl}$) および球面調和関数 ($Y_{lm}$) を含む波動関数 ($\psi_{nlm}$) を計算します。
2.  **多様なプロットモード**: コマンドライン引数 `mode` によって、以下のような様々な種類のプロットを生成します。
    *   **3D表面プロット (`rplot`, `ranim`, `rsurface`)**:
        *   `rplot`: 球面調和関数の絶対値、実部、虚部、または絶対値の2乗を3D表面としてプロットします。表面の色は値または位相でマッピングされます。
        *   `ranim`: `rplot` のアニメーション版で、波動関数の位相を時間的に変化させながら回転する様子をGIFで出力します。
        *   `rsurface`: 球面調和関数の絶対値を半径とし、その絶対値自体をz軸にプロットする3D表面図を生成します。
    *   **3Dドットプロット (`dot`, `dotc`, `dotanim`)**:
        *   モンテカルロ法によるリジェクションサンプリングを用いて、波動関数の確率密度分布を点の集合として3D空間に表示します。点の色は位相によって分けられます。
        *   `dotc`: ドットプロットに加えて、波動関数の等高線（平面スライス）も表示します。
        *   `dotanim`: ドットプロットのアニメーション版で、波動関数の位相を時間的に変化させながら点を更新します。
    *   **3D等値面プロット (`iso3d`, `iso3danim`)**:
        *   波動関数の特定の強度レベル（等値面）を3Dで可視化します。異なるレベルは異なる色で表示されます。
        *   `iso3danim`: 等値面プロットのアニメーション版で、波動関数の位相を時間的に変化させながら等値面を更新します。
    *   **2Dグラフ (`Rnl`, `Ylm`/`Theta`, `Phi`)**:
        *   `Rnl`: 動径波動関数 $R_{nl}(r)$ と動径確率密度分布 $P_{nl}(r) = r^2 |R_{nl}(r)|^2$ のグラフをそれぞれ描画します。
        *   `Ylm` (または `Theta`): 球面調和関数 $Y_{lm}(\theta)$ の$\theta$依存性を2Dグラフで表示します。
        *   `Phi`: 球面調和関数 $Y_{lm}(\phi)$ の$\phi$依存性を2Dグラフで表示します。
    *   **その他ユーティリティ (`normalize`, `torus`, `contour3d`, `3dMC_animation`)**:
        *   `normalize`: 波動関数の正規化を、数値積分 (`scipy.integrate.quad`) とモンテカルロ積分でチェックします。
        *   `torus`: 一般的なトーラスの3D表面をプロットします。
        *   `contour3d`: 汎用的な3D関数の2D等高線（スライス）を3D空間にプロットします。
        *   `3dMC_animation`: $e^{-r^2}$ のような汎用的な分布のモンテカルロサンプリングをアニメーションで表示します。
3.  **`functype` による軌道の指定**: `functype` 引数で、プロット対象の軌道と表示方法を指定します。
    *   `nlm` の形式（例: `1s0`）と、その後の1文字で表示タイプ（`r`=実部、`i`=虚部、`a`=絶対値、`a2`=絶対値の2乗）を指定します。
    *   例: `1s0a` (1s軌道の絶対値), `2pxr` (2px軌道の実部), `3d+2a2` (3d_{+2}軌道の絶対値の2乗)。
4.  **アニメーション出力**: `ranim`, `dotanim`, `iso3danim`, `3dMC_animation` モードでは、matplotlib の `FuncAnimation` を使用してGIFアニメーションファイルを生成します。アニメーションの保存には外部ツール `imagemagick` が必要です。
5.  **コマンドライン引数による制御**: プロットの表示 (`--fplot`) やファイルへの保存 (`--fsave`) をコマンドラインオプションで制御できます。

### 2) 必要な非標準ライブラリとインストール方法

このプログラムは以下の非標準ライブラリを使用しています。

*   **numpy**: 数値計算（配列操作、数学関数）に必要です。
*   **scipy**: 科学計算（積分、特殊関数、物理定数）に必要です。
*   **matplotlib**: グラフ描画全般、特に3Dプロットとアニメーション生成に必要です。

**インストール方法**:
これらのライブラリは、Pythonのパッケージマネージャー `pip` を使ってインストールできます。

```bash
pip install numpy scipy matplotlib
```

**アニメーション保存に必要な外部ツール**:
GIFアニメーションの保存 (`FuncAnimation.save(..., writer='imagemagick')`) には、システムに [ImageMagick](https://imagemagick.org/) がインストールされている必要があります。

*   **Windows**: ImageMagickの公式ウェブサイトからインストーラーをダウンロードしてインストールしてください。
*   **macOS**: Homebrew を使用してインストールできます: `brew install imagemagick`
*   **Linux**: 各ディストリビューションのパッケージマネージャーを使用してください (例: Debian/Ubuntuなら `sudo apt-get install imagemagick`)。

### 3) 必要な入力ファイル

`plot_wf.py` は、以下の2つのカスタムモジュールに依存しています。これらのファイルが `plot_wf.py` と同じディレクトリ、またはPythonのパスが通っている場所に存在する必要があります。

*   `tkWavefunction_H.py`: 水素原子の波動関数を計算するための関数（動径波動関数 $R_{nl}$、球面調和関数 $Y_{lm}$、デカルト座標での波動関数 $\psi_{nlm}$ など）が定義されています。
*   `tkPlot3d.py`: 3Dプロットのヘルパー関数（3D表面プロット、散布図、等高線、カラーバー表示、軸スケール設定など）が定義されています。

### 4) 実行後に生成される出力ファイル

プログラムが `fsave=1` (デフォルト) で実行された場合、以下のファイルがカレントディレクトリに生成されます。

*   **2Dグラフ**:
    *   `Rnl` モード:
        *   `plot_wf_Rnl.png`: 動径波動関数 $R_{nl}(r)$ のグラフ。
        *   `plot_wf_Pnl.png`: 動径確率密度分布 $P_{nl}(r)$ のグラフ。
    *   `Ylm` / `Theta` モード: `plot_wf_Ylm_{functype}.png` (例: `plot_wf_Ylm_1s0r.png`)
    *   `Phi` モード: `plot_wf_Phi_{functype}.png` (例: `plot_wf_Phi_1s0r.png`)
*   **3Dプロット (静止画)**:
    *   `rplot` モード: `plot_wf_rplot_{functype}.png` (例: `plot_wf_rplot_2pxa.png`)
    *   `dot` モード: `plot_wf_dot_{functype}.png` (例: `plot_wf_dot_3d+2a2.png`)
    *   `dotc` モード: `plot_wf_dotc_{functype}.png` (例: `plot_wf_dotc_3d+2a2.png`)
    *   `iso3d` モード: `plot_wf_iso3d_{functype}.png` (例: `plot_wf_iso3d_4f-3r.png`)
    *   `rsurface` モード: `plot_wf_rsurface_{functype}.png` (例: `plot_wf_rsurface_2pxa.png`)
    *   `torus` モード: `plot_wf_torus_2px.png` (functypeはデフォルト値が使われる)
    *   `isosurface3d` モード: `plot_wf_isosurface3d_2px.png` (functypeはデフォルト値が使われる)
    *   `contour3d` モード: `plot_wf_contour3d_2px.png` (functypeはデフォルト値が使われる)
*   **3Dプロット (GIFアニメーション)**:
    *   `ranim` モード: `plot_wf_ranim_{functype}.gif` (例: `plot_wf_ranim_2pya.gif`)
    *   `dotanim` モード: `plot_wf_dotanim_{functype}.gif` (例: `plot_wf_dotanim_3d+2a2.gif`)
    *   `iso3danim` モード: `plot_wf_iso3danim_{functype}.gif` (例: `plot_wf_iso3danim_4f-3r.gif`)
    *   `3dMC_animation` モード: `plot_wf_3dMC_animation_2px.gif` (functypeはデフォルト値が使われる)

### 5) コマンドラインでの使用例 (Usage)

以下は、`plot_wf.py` をコマンドラインから実行する際の一般的な使用例です。

```bash
# プログラムのヘルプメッセージを表示
python plot_wf.py -h

# デフォルト設定 (rplot 2pxa) で実行し、プロットを表示してPNGを保存
python plot_wf.py

# 1s軌道の絶対値を3D表面としてプロット (デフォルトのrplotモード)
python plot_wf.py rplot 1s0a

# 2py軌道の絶対値のアニメーション (GIF) を生成
python plot_wf.py ranim 2pya

# 3d+2軌道の絶対値の2乗をモンテカルロドットプロットで表示
python plot_wf.py dot 3d+2a2

# 3d-1軌道の実部をモンテカルロドットプロットと等高線で表示
python plot_wf.py dotc 3d-1r

# 4f-3軌道の実部を3D等値面としてプロット
python plot_wf.py iso3d 4f-3r

# 動径波動関数と動径確率密度分布の2Dグラフを表示 (PNGを保存)
python plot_wf.py Rnl

# 球面調和関数のシータ依存性 (Ylm) の2Dグラフを表示 (PNGを保存)
python plot_wf.py Ylm

# 波動関数の正規化をチェック
python plot_wf.py normalize

# 一般的なトーラスをプロット
python plot_wf.py torus

# 3Dモンテカルロサンプリングのアニメーション
python plot_wf.py 3dMC_animation

# プロットを表示せずにファイルのみ保存 (例: 3d+2軌道のドットアニメーション)
python plot_wf.py dotanim 3d+2a2 --fplot 0 --fsave 1

# プロットをファイルに保存せず、表示のみ行う (例: 1s軌道の絶対値)
python plot_wf.py rplot 1s0a --fplot 1 --fsave 0

# モンテカルロサンプリングの点数を変更する例
python plot_wf.py dot 2s0a 50000
```