lzwei196/kiss-knowledge-infrastructure-for-scientific-simulation/gempy

MANDATORY EXECUTION POLICY — READ BEFORE PROCEEDING

You MUST run the actual model binary or package described in this document.

If the model fails to import, compile, or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern

2. Try the fix suggested in the triplet's remedy section

3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python formula, regression equation,

or hand-coded approximation in place of the real model.

Before starting, run: python preflight_check.py (in this KI directory)

to verify that the model binary/package and required data are available.

DEBUGGING PROTOCOL — When something goes wrong, follow this order:

1. Check triplets — diagnostics/triplets.yaml may already cover this error

2. Read official docs — The model's own documentation for expected formats/units

3. Find working examples — Check outputs/ or the model's shipped test data

4. Fix the tool — With knowledge of what "correct" looks like

Do NOT write custom debug scripts. The answers are in the docs and examples.

<!-- KI-MAP:BEGIN (projected by generate_skill_map.py — edit the KI, not this table) -->

KI map — what to read, and when

Projected 2026-08-17 from the KI's actual contents — 9 components present. Refresh: `python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>`. <!-- KI-MAP:END -->

<!-- KI-TOOL-INDEX:BEGIN (projected by generate_skill_map.py — the discoverability contract: every public tool, exact path; PURPOSE stays human-authored elsewhere) -->

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

4 public tools; `_`-prefixed helpers and packaging files excluded. <!-- KI-TOOL-INDEX:END -->

GemPy Knowledge Infrastructure — SKILL.md

Data Preparation

Forcing data

Data Sources: Use from ki_tools_common.load_forcing import load_daily_forcing for CMFD/MSWX/NASA POWER.

Data Validation Reference: See data_ki/DTB/SKILL.md for depth-to-bedrock data.

Depth-to-bedrock (DTB) modelling notes

Reference dataset: DTB_CHINA_100.tif — ML-derived product (machine learning applied to geological, topographic, and remote-sensing predictors). Not borehole measurements. A comparison against it is a model-to-model consistency check, not an observational validation.

Key implementation notes confirmed by debugging:

• Use DENSE grid (resolution=[nx,ny,nz]), NOT octree (octree hangs for DTB-scale data)
• GemPy block ID mapping: ID=1 = above ground surface (z>0), ID=2 = soil layer

(0 > z > −DTB), ID=3 = basement/bedrock (z < −DTB). Extract DTB as first occurrence of ID=3 in a surface-to-depth probe column — NOT the first change from ID=1 (that triggers at z≈0, giving wrong near-zero DTB predictions)

• Custom grid via gp.set_custom_grid(model.grid, test_profiles) then

model.solutions.raw_arrays.custom.lith_block

Point correlation (R) against a fine raster: GemPy fits a smooth geological surface and cannot reproduce fine-scale ML raster variability (sub-km spatial correlation), so a low R against such a raster is expected and is not by itself a sign of a broken setup.

1. Overview

GemPy is an open-source Python library for constructing 3D implicit geological models. It uses potential-field interpolation (universal co-kriging) to create continuous scalar fields from which geological surfaces, fault networks, and unconformities are extracted. GemPy represents geology implicitly — each formation boundary is an iso-surface of a scalar field, enabling arbitrary topology without explicit surface meshing during interpolation.

Core Capabilities

• Implicit surface modeling via potential-field interpolation (kriging)
• Fault networks with configurable fault–fault and fault–formation relations
• Unconformities (erosion, onlap) via structural group stacking
• Octree refinement for variable-resolution grids (efficient computation)
• Dual contouring / marching cubes for mesh extraction
• Geophysics integration — forward gravity/magnetics from 3D geology
• Probabilistic modeling via PyTorch backend (automatic differentiation)
• Serialization to .gempy binary format (zlib-compressed)

Architecture (v3)

GemPy v3 is split into four packages:

2. Installation

Quick Install (pip)

python -m venv venv && source venv/bin/activate
pip install "gempy[base]"       # core + viewer + pandas
pip install "gempy[opt]"        # + plugins, pooch, scipy, scikit-image

From Source

git clone https://github.com/cgre-aachen/gempy.git
cd gempy
pip install -e ".[base]"

Dependencies

Smoke Test

import gempy as gp
model = gp.create_geomodel(
    project_name="test",
    extent=[0, 1000, 0, 1000, 0, 1000],
    resolution=[10, 10, 10],
    refinement=4
)
print(model)  # Should print GeoModel summary

3. Pipeline Architecture

┌─────────────────┐
│ S1: Input Data   │  CSV surface points + orientations
│   Preparation    │  (X, Y, Z, formation, G_x, G_y, G_z)
└────────┬────────┘
         │
┌────────▼────────┐
│ S2: GeoModel     │  create_geomodel() with extent, resolution
│   Initialization │  ImporterHelper for CSV column mapping
└────────┬────────┘
         │
┌────────▼────────┐
│ S3: Structural   │  map_stack_to_surfaces()
│   Organization   │  Define series, groups, fault relations
└────────┬────────┘
         │
┌────────▼────────┐
│ S4: Grid         │  OCTREE / DENSE / CUSTOM / TOPOGRAPHY
│   Configuration  │  set_active_grid(), set_section_grid()
└────────┬────────┘
         │
┌────────▼────────┐
│ S5: Fault        │  set_is_fault(), set_fault_relation()
│   Configuration  │  Finite fault support (prototype)
└────────┬────────┘
         │
┌────────▼────────┐
│ S6: Interpolation│  compute_model(engine_config)
│   Computation    │  Backend: NumPy (default) or PyTorch
└────────┬────────┘
         │
┌────────▼────────┐
│ S7: Solution     │  scalar_field, block model, meshes
│   Extraction     │  Marching cubes / dual contouring
└────────┬────────┘
         │
┌────────▼────────┐
│ S8: Validation   │  Cross-section plots, 3D visualization
│   & Visualization│  Geophysics forward modeling (gravity)
└────────┬────────┘
         │
┌────────▼────────┐
│ S9: Export &     │  .gempy binary, VTK, CSV, JSON
│   Serialization  │  save_model() / load_model()
└─────────────────┘

Stage Dependencies

4. Input Formats

Surface Points CSV