# 環境設定指南（setup）

> 原則（已與課程負責人確認）：**真跑一律以 Google Colab 為準；本機（尤其 Windows）一律走 mock fallback**。所有互動教材（interactive/）不需要任何安裝——雙擊 HTML 就能開。

## 三層參與方式

| 層級 | 你需要什麼 | 能做什麼 |
|---|---|---|
| A. 只看教材與互動 demo | 瀏覽器（手機也行） | 全部章節的概念學習、互動視覺化 |
| B. 跑 notebook（mock 模式） | 任何有 numpy + matplotlib 的 Python | 所有 notebook 的教學主線（不裝 MLIP 套件） |
| C. 真跑 MLIP / LDR | Google Colab（免費 T4 即可） | MACE/CHGNet/MatterSim 推論與小型微調 |

## Colab 注意事項（授課前務必實測）

- 每本 notebook 開頭有「環境偵測 cell」：套件不在就自動進 mock 模式，**不會報錯中斷**
- `mattersim` 需要 **Python ≥3.12**——若 Colab runtime 還是 3.11，pip 會退回裝舊版 1.1.x；課前先跑 `!python --version` 確認
- 安裝指令統一放在 notebook 內的註解 cell，不要求學生先讀文件

## 各套件速查（細節與來源見 docs/repo-analysis/）

| 套件 | 指令 | 課堂建議 | 主要坑 |
|---|---|---|---|
| CHGNet | `pip install chgnet` | 本機/Colab 皆可（門檻最低） | Python 3.13+ 需編譯器；微調能量用 energy/atom |
| MACE | `pip install mace-torch` | 推論 CPU 可、微調上 Colab | 別裝錯成 `MACE`；先裝對 torch（2.4.1 不支援）；舊文獻的 `--swa` 已改名 `--stage_two` |
| MatterSim | `pip install mattersim` | **只在 Colab/WSL2**（無 Windows wheel；Python ≥3.12） | 相依很重；checkpoint 首次使用會自動下載 |
| Local Deep Research | `pip install local-deep-research` | 教師演示為主（Python ≥3.12；需 LLM） | 課堂走雲端 API key + 免費搜尋引擎（arxiv/pubmed/wikipedia） |

## Windows 學生的路徑

1. 首選：Colab（零安裝）
2. 想本機玩：CHGNet 可直接 `pip install`（有官方 Windows wheel）
3. MACE/MatterSim/LDR 想本機跑：WSL2 + Ubuntu（本課程不教安裝 WSL2，附官方連結即可）

## 教師端配置（demo day）

- 一台能投影的機器 + 預先跑通的 Colab 分頁（每章一個）
- LDR 演示：課前啟動 `python -m local_deep_research.web.app`（教師機），備妥 API key 與 3–5 篇示範 PDF
- 備案：所有 demo 都有純 HTML / mock 版本，**斷網也能上課**

## 版本鎖定（教材撰寫當下，2026-06-11）

- local-deep-research v1.7.0 / mace-torch v0.3.16 / chgnet v0.4.2 / mattersim v1.2.5
- 教材中所有指令以這些版本為準；升版後若行為不同，以各 repo 官方 README 為準