gempy-3x

# GemPy 3.x 隱式地質建模工作規範 本 skill 做兩件事： 1. **正確使用 GemPy 3.x API** —— 所有寫進 [references/gempy3-api.md](references/gempy3-api.md) 的用法都來自實際跑通的 notebook，不是從記憶或網路教學抄來的。 2. **提供一套可複製的建模／不確定性分析流程紀律** —— Step 0～10 的 notebook 模板、 唯讀輸入正本、路徑集中管理、realization 命名與可重現性要求。 ## 核心原則 1. **禁止臆造 API**。GemPy 從 v2 到 v3 改版幅度極大，網路上大量教學仍是 v1/v2 語法（`gp.create_data`、`gp.set_interpolator`、Theano/Aesara 相關）， 直接照抄一定壞。寫任何 GemPy 程式碼前，先確認該用法出現在 [references/gempy3-api.md](references/gempy3-api.md) 或官方文件 docs.gempy.org。 不確定就明講不確定，並提供查證方式。 2. **外科手術式修改**。只動使用者要求的部分；notebook 的其他 cell 與既有變數命名 保持原樣。地質建模 notebook 的 cell 之間有大量隱性依賴（globals 旗標、helper 函式），順手「整理」極容易弄壞下游。 3. **每一步都要有可驗證輸出**。每個 Step 結束時印出摘要、畫圖或存檔—— 地質模型的錯誤常常是「安靜地算出錯的東西」，沒有中間檢查就抓不到。 4. **模型參數或地質假設有疑義時先問**。擾動哪個參數、用什麼機率分布、 內插解析度、接觸關係（ERODE/ONLAP）——這些是地質判斷，不要替使用者默默決定。 5. **輸入資料視為唯讀正本**。擾動或修改一律另存新檔／新資料夾，不覆蓋原始 CSV。 詳見 [references/project-conventions-template.md](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](references/workflow.md)。 ## 常見任務入口 - **寫或改 GemPy 程式碼** → 先讀 [references/gempy3-api.md](references/gempy3-api.md) 確認 API 簽名與已驗證用法。 - **建立新專案 / 訂定專案慣例** → 用 [references/project-conventions-template.md](references/project-conventions-template.md) 填出該專案的凍結參數、資料夾規範與地層清單，放進專案根目錄，之後一律以它為準。 - **不確定性分析、多組 realizations、蒙地卡羅** → 讀 [references/uncertainty-analysis.md](references/uncertainty-analysis.md) 的命名規範、擾動設計與可重現性 checklist。 - **從地表露頭計算地層位態（orientations）、V 字法則、三點法** → 讀 [references/orientation-vnotch.md](references/orientation-vnotch.md)。 重點：**不要拿整組露頭點做全域 PCA**，那樣算出來的位態會被地形帶偏。 - **除錯 notebook** → 讀 [references/workflow.md](references/workflow.md) 對應 Step 的常見錯誤段落，以及 gempy3-api.md 末尾的疑難排解表。 - **論文寫作引用 / 理論問題** → 讀 [references/theory-references.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 為準，並告知使用者這是版本差異。