r14521128 GemPy 3.x 隱式地質建模工作規範
本 skill 做兩件事：
- 正確使用 GemPy 3.x API —— 所有寫進 references/gempy3-api.md 的用法都來自實際跑通的 notebook，不是從記憶或網路教學抄來的。
- 提供一套可複製的建模／不確定性分析流程紀律 —— Step 0～10 的 notebook 模板、 唯讀輸入正本、路徑集中管理、realization 命名與可重現性要求。
核心原則
- 禁止臆造 API。GemPy 從 v2 到 v3 改版幅度極大，網路上大量教學仍是
v1/v2 語法（
gp.create_data、gp.set_interpolator、Theano/Aesara 相關）， 直接照抄一定壞。寫任何 GemPy 程式碼前，先確認該用法出現在 references/gempy3-api.md 或官方文件 docs.gempy.org。 不確定就明講不確定，並提供查證方式。 - 外科手術式修改。只動使用者要求的部分；notebook 的其他 cell 與既有變數命名 保持原樣。地質建模 notebook 的 cell 之間有大量隱性依賴（globals 旗標、helper 函式），順手「整理」極容易弄壞下游。
- 每一步都要有可驗證輸出。每個 Step 結束時印出摘要、畫圖或存檔—— 地質模型的錯誤常常是「安靜地算出錯的東西」，沒有中間檢查就抓不到。
- 模型參數或地質假設有疑義時先問。擾動哪個參數、用什麼機率分布、 內插解析度、接觸關係（ERODE/ONLAP）——這些是地質判斷，不要替使用者默默決定。
- 輸入資料視為唯讀正本。擾動或修改一律另存新檔／新資料夾，不覆蓋原始 CSV。 詳見 references/project-conventions-template.md。
建模流程模板（Step 0～10）
建議所有建模 notebook 共用同一套流程，換模型時只改輸入路徑與輸出代號：
| Step | 內容 | 關鍵輸出 |
|---|---|---|
| 0 | 匯入套件（gempy、gempy_viewer、pyvista、rasterio） | GemPy 版本號 |
| 1 | 路徑設定 _INPUT/_OUTPUT + 檔案存在檢查 |
✅/⚠️ 檔案清單 |
| 2 | 讀 CSV + 欄位驗證 + 地層名稱交叉比對 | 筆數、地層種類 |
| 3 | 座標平移（大座標→局部座標）+ DEM 仿射平移 + 模型範圍 | 平移後 DEM |
| 4 | gp.create_geomodel(...) 初始化 |
解析度、網格尺寸 |
| 5 | 地層堆疊 map_stack_to_surfaces + ERODE/ONLAP + 顏色 |
structural_frame 表 |
| 6 | gp.set_topography_from_file(...) 套地形 |
DEM 驗證訊息 |
| 7 | 自訂剖面 set_section_grid + gp.compute_model |
計算成功旗標 |
| 7.5 | lith_block 匯出（npy + csv + ID 對照表） | lith_block_3d.npy |
| 8A/8B | 2D 剖面視覺化（俯視圖、X/Y 剖面、自訂剖面） | PNG 圖組 |
| 9 | 網格匯出：STL（原始）+ PLY（地表裁切+精簡）+ CSV | *.stl / *.ply |
| 10 | 互動式 3D（gpv.plot_3d，批次執行時保持註解） |
— |
每個 Step 的細節、常見錯誤與陷阱（lith_block 的 C/F order 轉換、地形裁切、 檔名非法字元⋯⋯）見 references/workflow.md。
常見任務入口
- 寫或改 GemPy 程式碼 → 先讀 references/gempy3-api.md 確認 API 簽名與已驗證用法。
- 建立新專案 / 訂定專案慣例 → 用 references/project-conventions-template.md 填出該專案的凍結參數、資料夾規範與地層清單，放進專案根目錄，之後一律以它為準。
- 不確定性分析、多組 realizations、蒙地卡羅 → 讀 references/uncertainty-analysis.md 的命名規範、擾動設計與可重現性 checklist。
- 從地表露頭計算地層位態（orientations）、V 字法則、三點法 → 讀 references/orientation-vnotch.md。 重點：不要拿整組露頭點做全域 PCA，那樣算出來的位態會被地形帶偏。
- 除錯 notebook → 讀 references/workflow.md 對應 Step 的常見錯誤段落，以及 gempy3-api.md 末尾的疑難排解表。
- 論文寫作引用 / 理論問題 → 讀 references/theory-references.md（方法論引用鏈）。
執行與驗證習慣
- 跑 notebook 用
jupyter nbconvert --to notebook --execute、papermill， 或請使用者在 VS Code / JupyterLab 執行。 - 改完 cell 後至少驗證：JSON 結構有效、路徑存在、無殘留舊路徑。
- 重大修改後要能重新 compute 出結果才算完成（Step 7 成功 + Step 8 有圖）， 不要只改完程式碼就宣告完工。
- 產出檔案後回報實際路徑與筆數／尺寸，讓使用者能快速抽查。
適用版本
- 附帶範例（
examples/）實測通過於 GemPy 2025.2.0。 - API 清單來自 2025.2.0 與 2026.0.3 兩代的實作經驗；2026.0.3 為撰稿時的最新穩定版， 但未逐項在該版重測。
- 支援 Python 3.10–3.12。
動手前先執行 python -c "import gempy; print(gempy.__version__)" 確認使用者的版本，
遇到簽名不符以官方文件 https://docs.gempy.org 為準，並告知使用者這是版本差異。