gempy-3x

name

gempy-3x

description

GemPy 3.x 三維地質建模與石門聯通管多參數分析專案（D:\gempy）的完整工作規範。 只要使用者提到 GemPy、gempy_engine、gempy_viewer、隱式地質建模、位勢場插值、 地質模型、surface points / orientations CSV、lith_block、地質網格匯出（STL/PLY）、 D:\gempy 底下任何檔案、m1/m4 等模型代號、多參數分析、地質不確定性、realizations、 地層位態（orientation/dip/azimuth）計算、V 字法則、三點法、QGIS 前處理， 或要新增/修改/批次執行建模 notebook，都必須使用本 skill——即使使用者沒有明講 「GemPy」三個字（例如只說「幫我加一組模型」「改剖面」「算位態」）。 嚴禁憑記憶臆造 GemPy API：一律以本 skill 的 references 與官方文件為準。

GemPy 3.x 建模與石門多參數分析

本 skill 服務兩件事：(1) 正確使用 GemPy 3.x API；(2) 遵守 D:\gempy 石門聯通管 多參數分析專案的架構規範。兩者綁在一起，因為此專案所有 GemPy 工作都發生在同一套 資料夾架構與 notebook 流程模板上，改錯一個路徑或參數就會汙染整個機率統計分析。

核心原則

1. 禁止臆造 API。GemPy 3.x 改版幅度大，網路上大量教學是 v1/v2 語法（Theano 時代）， 直接照抄會壞。寫任何 GemPy 程式碼前，先確認該用法出現在 references/gempy3-api.md（來自實際跑通的 notebook） 或官方文件 docs.gempy.org。不確定就明講不確定，並提供查證方式。
2. 繁體中文：所有註解與說明用繁體中文（專案硬性規定）。
3. 外科手術式修改：只動使用者要求的部分。notebook 的其他 cell、變數命名 （geo_model、auto_extent、_INPUT/_OUTPUT 等）保持原樣。
4. 每一步都要有可驗證輸出：印出摘要、畫圖或存檔。這是專案 CLAUDE.md 的要求， 也是 notebook 模板每個 Step 都有 print 檢查的原因。
5. 凍結參數勿動：SHIFT_X = 270000、SHIFT_Y = 2740000（TWD97→局部座標平移量） 與 MANUAL_EXTENT = [800, 4800, 3500, 6500, 0, 1000] 是全專案統一基準， 改了會讓不同模型的成果無法疊合比較。除非使用者明確要求，否則不得修改。
6. 模型參數或地質假設有疑義時先問：擾動哪個參數、用什麼分布、內插設定等 屬於地質判斷，不要替使用者默默決定。

專案架構速覽

D:\gempy\
├── input\    共用輸入（唯一資料來源）：dem\20m_dem.tif、surface\、borehole\、
│             assumption\（m4 輸入）、fault\（預留，空）、tunnel\（預留，空）
├── code\     建模 notebook：m1_surf_only.ipynb、m4_faultdip.ipynb、
│             Investigates_QGIS_to_gempy .ipynb（位態計算前處理，檔名含空格）
├── output\mX\  各模型計算輸出（剖面圖、lith_block、平移後 DEM）
├── mesh\mX\    各模型 STL/PLY 網格（供 FLAC3D/3DEC 使用）
├── compare\  模型比較    ├── concept\  概念模型    ├── database\  資料前處理
└── AI_Agent\ AI 協作資料（本 skill 的同步副本在 AI_Agent\skill\）

鐵則：輸入只從 input\ 讀，輸出只寫進自己模型代號的 output\mX\ 與 mesh\mX\。 notebook 內只有兩處路徑設定：Step 1 的 _INPUT/_OUTPUT 與 Step 9 的 mesh_output_dir。新增模型時就只改這兩處加上輸入檔名。

⚠️ 資料血緣（詳見 references/project-structure.md； 2026-07-09 重整後）：assumption\ 是 m4 的計算輸入（309 點 = 鑽孔 303 + 6 個 深部假設控制點）；orientations 為遞增鏈 surface(18) ⊂ borehole(20) ⊂ assumption(26)， 同位置參數一致；fault\ 與 tunnel\ 為空的預留資料夾。擾動或修改輸入資料前， 先跑 code\input_inventory.py 確認現況，改完再跑一次留下變更記錄。

建模流程模板（Step 0～10）

所有模型 notebook 共用同一套流程，m1 與 m4 只差輸入檔與少數 cell：

Step	內容	關鍵輸出
0	匯入套件（gempy、gempy_viewer、pyvista、rasterio）	GemPy 版本號
1	路徑設定 _INPUT/_OUTPUT + 檔案存在檢查	✅/⚠️ 檔案清單
2	讀 CSV + 欄位驗證 + 地層名稱交叉比對	筆數、地層種類
3	座標平移（SHIFT_X/Y）+ DEM 仿射平移 + MANUAL_EXTENT	dem_cropped_local.tif
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	_MODEL_COMPUTED
7.5	lith_block 匯出（npy + csv + ID 對照表）	lith_block_3d.npy
8A/8B	2D 剖面視覺化（俯視圖、X/Y 剖面、自訂剖面）	PNG 圖組
9	網格匯出：STL（原始）+ PLY（地表裁切+精簡）+ CSV	mesh\mX\*.stl/.ply
10	互動式 3D（gpv.plot_3d，預設註解掉）	—

每個 Step 的細節、常見錯誤與陷阱（例如 lith_block 的 C/F order 轉換、 cropped_dem_path 其實是「平移」不是「裁切」）見 references/workflow.md。

常見任務入口

• 新增一組模型（含 realizations） → 讀 references/multiparam.md 的命名規範與 checklist，再複製最接近的基準 notebook 修改。
• 寫或改 GemPy 程式碼 → 先讀 references/gempy3-api.md 確認 API 簽名與已驗證用法。
• 動輸入資料 / 找檔案 / 理解資料來源 → 讀 references/project-structure.md（含 QGIS 前處理脈絡與 MD5 資料血緣表）。
• 計算或討論地層位態（orientations）、V 字法則、三點法、凹口選點 → 讀 references/vnotch-orientation.md。此專案的 orientations 不是拿整組露頭點 PCA 出來的——那樣會偏差；正規流程是 V 字三點法。
• 除錯 notebook → 讀 references/workflow.md 對應 Step 的 常見錯誤段落。
• 論文寫作引用 / 理論問題 → 讀 references/theory-references.md（引用鏈、完整書目、 不可引用的資料警告）。

執行與驗證習慣

• 跑 notebook 用 jupyter 執行或請使用者在 VS Code 執行；改完 cell 後至少驗證 JSON 結構有效、路徑存在、無殘留舊路徑（可用 python -c 快速檢查）。
• GemPy 模型每次重大修改後要能重新 compute 出結果才算完成（Step 7 成功 + Step 8 有圖），不要只改完程式碼就宣告完工。
• 產出檔案後回報實際路徑與筆數/尺寸，讓使用者能快速抽查。