# fs_packet.py — Femtosecond Wave Packet Visualizer

Ti:Sapphire（中心 ~800 nm）を想定した **10 fs 級の超短パルス**を、
「**離散周波数成分の和**で構成」して可視化する教育用スクリプトです。
**ガウシアン包絡**をもつスペクトル（強度 FWHM は TBP≈0.44 で決定）から、
- フーリエ限界（位相が平坦）での短パルス
- **GDD（φ₂）** を与えた **チャープ**での**パルス伸長**
- **群速度の周波数依存** `v(ν)=v0/(1+η(ν−ν0))` による **波束崩壊のアニメーション**（τ = z / v）

を直感的に観察できます。Matplotlib だけで動作し、光学講義・デモに最適です。

---

## 1. 何ができるか（機能）

- **離散スペクトルの可視化**
  - f-offset–**Intensity**（A²）
  - f-offset–**Amplitude**（A）
- **時間領域の波形分解**
  - 各 **component**（単色波）と **合成波（sum）**、**|E|²** を同図に表示
- **GDD（φ₂）掃引**（`--chirp`、単位 fs²）
  - φ₂ を変えたときの **パルス幅の伸び・波形変形**を重ね描画
- **アニメーション（τ=z/v モデル）**
  - 媒質中の分散（周波数で群速度が変わる）により **波束が崩れる様子**を連続表示
  - **中心追従（auto-center）**、**軸レンジ固定/自動**、**描画速度（sleep）** を調整可能

---

## 2. 物理モデルの概要

- **スペクトル包絡**：ガウシアン（強度の FWHM は TBP=0.44 から決定）  
  目標パルス幅（例：10 fs）→ 必要帯域 **Δν_FWHM ≈ 0.44 / τ_FWHM**  
- **時間領域の合成**：
  \n\\(E(t)=\sum_k A_k \cos\!\big(2\pi\nu_k t + \phi_k\big)\\)\n
- **位相（基底）**：`--phase-mode` で `flat` / `linear` / `quad`（φ₂=GDD）/ `random`  
- **GDD 掃引**：`--chirp` で φ₂ を fs² 単位で一括指定し、静的に比較
- **アニメ（分散）**：群速度 `v(ν)=v0/(1+η(ν−ν0))`  
  伝搬距離 z での遅延 \\(\tau_k(z)=z/v(\nu_k)\\) を各成分に付与して再合成

> 注：本スクリプトは **概念・可視化重視**の最小モデルです。非線形効果や高次分散、利得・損失、実機のキャリブレーションなどは扱っていません。

---

## 3. 必要なライブラリ（非標準）とインストール

- Python 3.9+（推奨）
- **Matplotlib**（描画）  
- **NumPy**（数値計算）

```bash
pip install numpy matplotlib
```

> Anaconda 環境でも動作します。`stem` は使わず “stem風” 描画なので Matplotlib のバージョン差で崩れにくい構成です。

---

## 4. 使い方（Usage）

```bash
python fs_packet.py [OPTIONS]
```

主なオプション：

- スペクトルと時間波形
  - `--nwave INT` : 重ね合わせる単色波の本数（既定 101）
  - `--tauf FLOAT` : フーリエ限界の目標パルス幅（fs, 既定 10）
  - `--twin FLOAT` : 時間表示窓の全幅（fs, 既定 200）
  - `--nsamp INT` : 時間サンプル数（既定 4000）
- 基底位相（静的）
  - `--phase-mode {flat,linear,quad,random}`（既定 flat）
  - `--phi1 FLOAT` : 群遅延係数 φ₁ [s]
  - `--phi2 FLOAT` : GDD φ₂ [s²]
  - `--phi2-fs2 FLOAT` : GDD φ₂ を fs² 単位で指定（例：10 → 10 fs²）
  - `--seed INT` : `random` 指定時の乱数シード
- **GDD 掃引（静的）**
  - `--chirp "a,b,c"` または `--chirp "start:end:steps"`（**fs²** 指定）
- **アニメ（τ=z/v）**
  - `--anim` : アニメを有効化
  - `--eta FLOAT` : 分散強度 [1/Hz]（既定 2e-15）
  - `--zmax FLOAT` : 伝搬距離の最大値 [m]（既定 0.01）
  - `--nframes INT` : フレーム数（既定 80）
  - `--interval INT` : フレーム間隔 [ms]（既定 80）
  - `--sleep FLOAT` : 各フレーム後に `time.sleep(s)` を入れて体感速度調整（既定 0）
  - 追従・軸レンジ
    - `--auto-center / --no-auto-center`（既定 ON）
    - `--xlim tmin tmax`（fs）
    - `--auto-ylim / --no-auto-ylim`（既定 自動）
    - `--ylim ymin ymax`
  - デバッグ
    - `--show-debug` : フレーム毎の遅延統計を表示

---

## 5. 実行例

### 5.1 基本（静的表示）
フーリエ限界 10 fs，相当帯域の離散スペクトルと時間波形を表示：
```bash
python fs_packet.py --nwave 101 --tauf 10 --phase-mode flat
```

### 5.2 GDD（φ₂）掃引でパルス伸長を比較（fs² 指定）
```bash
python fs_packet.py --chirp 0,10,30,60
# 範囲指定（0→50 fs² を 6 分割）
python fs_packet.py --chirp 0:50:6
```

### 5.3 アニメーション（分散での波束崩壊）
- ほどよい速度で見やすく：
```bash
python fs_packet.py --anim --eta 2e-15 --zmax 0.02 --nframes 100 --interval 60 --sleep 0.03
```
- 伝搬距離を長くして大きな崩壊を観察：
```bash
python fs_packet.py --anim --eta 2e-15 --zmax 1.0 --nframes 120 --interval 80 --sleep 0.02
```
- 時間窓を広げて波束の動きを追いやすく：
```bash
python fs_packet.py --anim --eta 2e-15 --zmax 0.5 --twin 2000 --nframes 120 --interval 60
```
- 画面レンジを固定：
```bash
python fs_packet.py --anim --eta 2e-15 --zmax 0.5 --xlim -500 500 --no-auto-ylim --ylim -1.2 1.2
```

> **Tips**：アニメが見えない場合は、`--twin`（時間窓）を広げるか、`--auto-center` を ON（既定）に。`--sleep` を増やすとゆっくり表示できます。

---

## 6. よくある質問（FAQ）

**Q1. 位相図が全部 0 に見える**  
A. `--phase-mode flat` かつ `t_ref=0` 相当で観察していると **平坦位相**なので 0 になります。  
`--phase-mode quad --phi2-fs2 10` などで位相曲率（GDD）を入れると、時間波形が伸びます。

**Q2. アニメが表示されない/速すぎる**  
A. `--auto-center`（既定 ON）で中心追従を有効化し、`--twin` を広げる、`--sleep` を入れる、
`--xlim`/`--ylim` を手で指定してみてください。`--show-debug` で遅延スケールを確認すると調整しやすいです。

**Q3. 実機のデータやスペクトルで見たい**  
A. 本スクリプトは離散線の合成ですが、CSV 等から実測スペクトルを読み込ませる拡張も容易です。ご希望があればテンプレートをお渡しします。

---

## 7. 免責
教育・デモ用途のための簡略モデルです。研究・設計用途での厳密評価には、
実機パラメータ、分散の高次項、非線形効果（SPM, XPM など）、利得/損失などを含むモデルをご使用ください。

---

**Author**: ChatGPT（GPT-5 Thinking）  
**Last updated**: 2025-08-13 (JST)