# Gempy 3x

> GemPy 3.x 隱式三維地質建模的實證型工作規範（繁體中文）。 只要使用者提到 GemPy、gempy_engine、gempy_viewer、隱式地質建模、位勢場（potential field） 插值、surface points / orientations CSV、structural frame、lith_block、 地質網格匯出（STL/PLY 給 FLAC3D/3DEC/PyVista）、地質不確定性與 realizations、 蒙地卡羅地質建模、地層位態（orientation / dip / azimuth）計算、V 字法則、三點法、 QGIS→GemPy 前處理，或要新增／修改／批次執行建模 notebook，都應使用本 skill—— 即使沒有明講「GemPy」三個字（例如只說「幫我加一組地質模型」「改剖面」「算位態」）。 嚴禁憑記憶臆造 GemPy API：v1/v2（Theano 時代）語法在 v3 一律無效。

- Skill: `r14521128/gempy-3x` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add r14521128/gempy-3x`
- Raw SKILL.md: https://api.skillmd.com/api/skills/r14521128/gempy-3x/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- License: MIT
- Author: r14521128 (https://skillmd.com/u/r14521128)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/r14521128/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 為準，並告知使用者這是版本差異。