# 学生ガイド

対象バージョン: **Cosmic Web Simulator 1.0.1**

## 1. このアプリで学ぶこと

Cosmic Web Simulatorは、天体や流体の動きを眺めるだけでなく、**数値モデルを設定し、結果を測り、計算の信頼性を確かめる**ための実験環境です。

主な学習目標:

- 初期条件、境界条件、終了条件を区別する
- 物理法則と数値計算法を区別する
- 粒子数、メッシュ数、時間刻みと計算負荷の関係を調べる
- 画像と診断量を対応させて結果を読む
- 保存量や解像度依存性から計算の信頼性を評価する
- 教育用モデルから分かることと分からないことを説明する

## 2. 推奨環境

最新版のChrome、Edge、Firefox、Safariを想定しています。計算はブラウザ内で行うため、速度と実行可能な規模は端末性能、ブラウザ、同時に開いているアプリやタブによって変わります。

開始前に、左側の**PC資源と実行予測**を確認してください。

## 3. 基本操作

### 1. 計算エンジンを選ぶ

- **重力多体系計算:** 重力で相互作用するN-body粒子
- **SPH:** 流体を表す粒子状の質量要素
- **Moving mesh:** 幅を持つ1次元有限体積cell

三つのエンジンは、画面に似た点や領域が見えても、表している数値要素と更新方法が異なります。右側の**何を計算しているか**を確認してください。

### 2. シナリオを選ぶ

**物理・数値設定**の先頭でシナリオを選びます。初めて使うときはAdvancedをOFFにし、既定値から始めてください。

### 3. 計算資源を確認する

リスク表示の意味:

- **LOW:** 比較的軽いと予測
- **MODERATE:** 端末によって待ち時間が生じる
- **HIGH:** 大きな負荷または長い実行時間を予測
- **BLOCKED:** 安全に初期化できない条件

Memory、CPU、Runtimeは別々に評価されます。LOWでも、終了まで長時間かかる場合があります。

### 4. 初期条件を生成する

**資源確認して初期条件を生成**を押し、開始前確認画面で次を確認します。

- 粒子数またはcell数
- PM mesh
- 推定ピークメモリ
- 計算Worker数
- 推定step数と総実行時間
- 終了条件

### 5. 表示を選ぶ

- **VIEW:** 3D表示またはXY／XZ／YZ射影
- **DISPLAY:** 粒子、投影密度、粒子＋密度、cell
- **COLOR:** 色で示す物理量
- **velocity vectors:** 速度の向き
- **trail:** 粒子軌跡

### 6. 実行する

- **実行:** 連続して計算
- **1 batch:** 一定数のstepだけ進める
- **リセット:** 同じ設定の初期状態へ戻す

設定を変更した後は、初期条件を再生成してください。

## 4. シナリオ解説の読み方

シナリオを選ぶと、画面下部の**このシミュレーションの基礎**が切り替わります。

1. **概要:** 何をモデル化しているか
2. **基礎知識:** 現象を理解するための概念
3. **数値計算:** 使用する離散化、ソルバー、境界条件
4. **何を見るか:** 表示すべき色、ベクトル、診断量
5. **結果の読み方:** 見た目と数値をどう結び付けるか
6. **適用限界:** この計算だけでは結論できないこと

全シナリオの解説は [SCENARIO_GUIDE.md](SCENARIO_GUIDE.md) にも収録しています。

## 5. 色の読み方

### 速さ `|v|`

速度ベクトルの大きさです。方向は示しません。収縮か膨張かを調べるときは、半径方向速度または速度ベクトルを使います。

### 半径方向速度 `v_r`

中心から外向きを正、内向きを負として表示します。

- 負: 収縮・流入
- 正: 膨張・流出

### 質量

個々の粒子またはcellが持つ質量です。宇宙論モードは等質量粒子を用いるため、通常は同じ色になります。

### 密度

- **宇宙論:** PM meshで求めた配置空間密度 `ρ/ρ̄`
- **SPH:** smoothing kernelによる2次元面密度または3次元体積密度
- **Moving mesh:** cell mass / cell width

これは6次元のphase-space densityではありません。

### 圧力

SPH粒子または有限体積cellの圧力です。Direct法やBarnes–Hut法だけを使うN-body計算には圧力はありません。

### 温度指標

状態方程式から作る表示用の指標です。物理単位への校正をしていないシナリオではKelvinではありません。

### Mach数

局所的な速さを音速で割った値です。1を超えると局所音速より速い流れです。

### 速度発散 `∇·v`

- 負: 収束・圧縮
- 正: 発散・膨張

### 成分ラベル

初期領域や役割を追跡する離散分類です。化学種とは限りません。連続量のカラーバーではなく凡例で表示されます。

## 6. 診断量の読み方

### 相対エネルギー誤差 `ΔE/|E0|`

保存系で大きく変化する場合は、時間刻み、softening、ソルバー近似、境界条件を確認します。合体やcoolingを含むシナリオでは、全エネルギーが意図的に変化する場合があります。

### 相対質量誤差 `ΔM/|M0|`

周期境界や閉じた有限体積計算では小さい値が望まれます。open boundaryでは領域外への流出により質量が変わる場合があります。

### Virial ratio

重力系では主に `2K/|U|` を表示します。1付近はvirial平衡の目安ですが、非定常系や圧力を持つ系では他の診断量と併用してください。

### 最大密度

局所的な極値で、数値noiseにも敏感です。投影密度や半質量半径と合わせて読みます。

### 平均近傍数

SPHでsmoothing kernel内に入る平均粒子数です。少なすぎるとnoiseが増え、多すぎると構造を過度に平滑化します。

### Batch計算時間

一定数のstepに要した実測時間です。公平に比較するときは、同じ端末、ブラウザ、Worker数、描画条件を使ってください。

## 7. 終了条件

終了条件は右側の診断欄に表示されます。

- **宇宙論:** final redshiftまたは最大step数
- **銀河衝突:** `t_end`または最大step数。最初の近点では停止しない
- **微惑星リング:** 指定した基準軌道数または最大step数
- **ガス雲・ガス円盤:** `t_end`
- **超新星残骸:** `t_end`
- **ダム崩壊:** `t_end`
- **Moving mesh:** `t_end`または最大step数

計算が停止しても、物理現象が最終状態に達したとは限りません。

## 8. 公平な比較実験

比較では、調べたい変数以外を固定します。

### CDMとWDMの例

- 同じseed
- 同じbox size
- 同じ粒子数 `n³`
- 同じPM mesh
- 同じredshift範囲
- 初期powerの小スケール抑制だけを変更

### Direct法とBarnes–Hut法の例

- 同じ初期状態
- 同じ時間刻み
- 同じsoftening
- ソルバーとopening angleだけを変更

複数の条件を同時に変えると、結果差の原因を特定できません。

## 9. 解像度と収束

一つの計算結果だけで結論を出さないでください。可能な範囲で次を試します。

- 時間刻みを1/2にする
- 粒子数またはcell数を増やす
- PM meshを変える
- SPH smoothing lengthまたは目標近傍数を変える
- Barnes–Hut opening angleを小さくする

条件を細かくしたときに、主要な結果が一定の値や傾向へ近づくか確認します。

## 10. 保存と提出

### 設定JSON

初期条件、seed、数値手法、終了条件を保存します。

### 診断CSV

保存量、密度、構造指標、計算時間の時系列を表計算ソフトやColabで解析できます。

### PNG

表示中のcanvasを保存します。時刻、カラーバー、凡例が読める状態にしてください。

### 共有URL

現在の設定をURLへ埋め込みます。再現性確認や授業での条件配布に利用できます。

## 11. よくある誤解

### 「粒子数が多いほど必ず正確」

粒子数だけでなく、時間刻み、softening、mesh、近傍数、境界条件が結果を左右します。

### 「きれいな構造が見えたので正しい」

数値noiseや不安定な設定でも構造が生じます。保存量、解像度依存性、別手法との比較が必要です。

### 「宇宙論の1粒子が1銀河」

宇宙論粒子は暗黒物質分布を離散化するmacro-particleです。一粒子が銀河を表すわけではありません。

### 「超新星SPHが中性子星かブラックホールかを予測した」

中心天体の分類は教育用prescriptionで与えます。SPHが主に計算するのは爆発後の流体膨張です。

### 「Moving meshはAREPOと同じ」

本アプリのmoving meshは1次元HLLC-ALE教材です。2次元・3次元Voronoi meshの接続変更は扱いません。

## 12. トラブルシューティング

### 初期化できない

`BLOCKED`の場合は、粒子数、PM mesh、Worker数を下げます。宇宙論では `8 ≤ n ≤ 2048` を入力できますが、入力範囲は実行可能範囲を保証しません。

### 画面が固まる

別タブを閉じ、描画上限、density grid、steps per frameを下げます。

### SPH粒子が飛散する

- 時間刻みを小さくする
- 人工粘性を既定値へ戻す
- smoothing lengthと近傍数を確認する
- 強いshockが境界へ到達していないか確認する

### 動きや構造が見えない

- 色で示す物理量を変える
- 投影密度または粒子＋密度表示へ切り替える
- 速度ベクトルを表示する
- シナリオ固有の診断量を確認する
- 終了時刻が短すぎないか確認する

### ローカルで開けない

`file://`ではなくHTTP serverから開きます。

```bash
npm run dev
```

## 13. レポートに記録する項目

- アプリのversion
- シナリオ
- ソルバーと時間積分法
- 粒子数、cell数、PM mesh
- 時間刻み、softening、smoothing length
- 境界条件
- seed
- 終了条件
- 比較で変更した変数
- 保存量または誤差
- 結果の適用限界