Back to Details

gempy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GemPy - 3D Geological Modelling

GemPy - 3D地质建模

Quick Reference

快速参考

python
import gempy as gp
python
import gempy as gp

Create model

Create model

geo_model = gp.create_geomodel( project_name='Model', extent=[0, 1000, 0, 1000, 0, 500], # [xmin, xmax, ymin, ymax, zmin, zmax] resolution=[50, 50, 25] )
geo_model = gp.create_geomodel( project_name='Model', extent=[0, 1000, 0, 1000, 0, 500], # [xmin, xmax, ymin, ymax, zmin, zmax] resolution=[50, 50, 25] )

Add surface points and orientations

Add surface points and orientations

gp.add_surface_points(geo_model, x=[100, 500, 900], y=[500, 500, 500], z=[400, 350, 400], surface='TopFormation') gp.add_orientations(geo_model, x=[500], y=[500], z=[375], pole_vector=[0, 0, 1], surface='TopFormation')
gp.add_surface_points(geo_model, x=[100, 500, 900], y=[500, 500, 500], z=[400, 350, 400], surface='TopFormation') gp.add_orientations(geo_model, x=[500], y=[500], z=[375], pole_vector=[0, 0, 1], surface='TopFormation')

Compute and visualize

Compute and visualize

gp.set_interpolator(geo_model) sol = gp.compute_model(geo_model) gp.plot_2d(geo_model, cell_number=[25], direction='y')
undefined
gp.set_interpolator(geo_model) sol = gp.compute_model(geo_model) gp.plot_2d(geo_model, cell_number=[25], direction='y')
undefined

Key Classes

核心类

ClassPurpose
GeoModel
Main container - holds all model data
StructuralFrame
Manages geological relationships
Grid
Computation mesh for interpolation
Solutions
Model results (lithology, scalar fields)
类用途
GeoModel
主容器 - 存储所有模型数据
StructuralFrame
管理地质关系
Grid
用于插值的计算网格
Solutions
模型结果（岩性、标量场）

Essential Operations

关键操作

Define Geological Relationships

定义地质关系

python
gp.map_stack_to_surfaces(geo_model, mapping={
    'Strata1': ['TopFormation', 'BaseFormation'],
    'Basement': ['Basement']
})
geo_model.structural_frame.structural_groups[0].structural_relation = \
    gp.data.StackRelationType.ERODE
python
gp.map_stack_to_surfaces(geo_model, mapping={
    'Strata1': ['TopFormation', 'BaseFormation'],
    'Basement': ['Basement']
})
geo_model.structural_frame.structural_groups[0].structural_relation = \
    gp.data.StackRelationType.ERODE

Add Faults

添加断层

python
gp.add_surface_points(geo_model, x=[300, 300, 300], y=[200, 500, 800],
                      z=[100, 250, 400], surface='Fault1')
gp.add_orientations(geo_model, x=[300], y=[500], z=[250],
                    pole_vector=[1, 0, 0.5], surface='Fault1')
gp.map_stack_to_surfaces(geo_model, mapping={
    'Fault_Series': ['Fault1'],
    'Strata1': ['Layer1', 'Layer2'],
})
geo_model.structural_frame.structural_groups[0].structural_relation = \
    gp.data.StackRelationType.FAULT
python
gp.add_surface_points(geo_model, x=[300, 300, 300], y=[200, 500, 800],
                      z=[100, 250, 400], surface='Fault1')
gp.add_orientations(geo_model, x=[300], y=[500], z=[250],
                    pole_vector=[1, 0, 0.5], surface='Fault1')
gp.map_stack_to_surfaces(geo_model, mapping={
    'Fault_Series': ['Fault1'],
    'Strata1': ['Layer1', 'Layer2'],
})
geo_model.structural_frame.structural_groups[0].structural_relation = \
    gp.data.StackRelationType.FAULT

Load Data from Files

从文件加载数据

python
import pandas as pd

points_df = pd.read_csv('surface_points.csv')  # Columns: X, Y, Z, surface
gp.add_surface_points(geo_model, x=points_df['X'], y=points_df['Y'],
                      z=points_df['Z'], surface=points_df['surface'])

ori_df = pd.read_csv('orientations.csv')  # Columns: X, Y, Z, dip, azimuth, surface
gp.add_orientations(geo_model, x=ori_df['X'], y=ori_df['Y'], z=ori_df['Z'],
                    dip=ori_df['dip'], azimuth=ori_df['azimuth'],
                    surface=ori_df['surface'])
python
import pandas as pd

points_df = pd.read_csv('surface_points.csv')  # Columns: X, Y, Z, surface
gp.add_surface_points(geo_model, x=points_df['X'], y=points_df['Y'],
                      z=points_df['Z'], surface=points_df['surface'])

ori_df = pd.read_csv('orientations.csv')  # Columns: X, Y, Z, dip, azimuth, surface
gp.add_orientations(geo_model, x=ori_df['X'], y=ori_df['Y'], z=ori_df['Z'],
                    dip=ori_df['dip'], azimuth=ori_df['azimuth'],
                    surface=ori_df['surface'])

Visualization

可视化

python
gp.plot_2d(geo_model, cell_number=[25], direction='y', show_data=True)
gp.plot_3d(geo_model, show_data=True, show_surfaces=True)  # Requires PyVista
python
gp.plot_2d(geo_model, cell_number=[25], direction='y', show_data=True)
gp.plot_3d(geo_model, show_data=True, show_surfaces=True)  # Requires PyVista

Access Results

访问结果

python
sol = gp.compute_model(geo_model)
lithology = sol.raw_arrays.lith_block
lith_3d = lithology.reshape(geo_model.grid.regular_grid.resolution)
python
sol = gp.compute_model(geo_model)
lithology = sol.raw_arrays.lith_block
lith_3d = lithology.reshape(geo_model.grid.regular_grid.resolution)

Structural Relation Types

构造关系类型

TypeDescription
ERODE
Younger surface erodes older (unconformity)
ONLAP
Younger onlaps onto older
FAULT
Surface is a fault plane
INTRUSION
Intrusive body
类型描述
ERODE
年轻地层侵蚀老地层（不整合面）
ONLAP
年轻地层超覆于老地层之上
FAULT
该面为断层面
INTRUSION
侵入体

When to Use vs Alternatives

适用场景与替代方案

ScenarioRecommendation
3D implicit geological modelling from surface dataGemPy - purpose-built, Python-native
Complex fold modelling with structural framesLoopStructural - better fold support
Commercial-grade subsurface modellingSKUA-GOCAD - industry standard, proprietary
Quick 2D cross-sections onlyGemPy works but may be overkill; consider manual interpolation
Need gravity/magnetics forward model from geologyGemPy - has built-in potential field support
Choose GemPy when: You need implicit 3D geological modelling from surface contacts and orientations with fault/unconformity relationships, especially when integrated with Python workflows. It has a gentler learning curve than LoopStructural for standard cases.
Avoid GemPy when: Your geology is dominated by complex folding (use LoopStructural), or you need production-grade reservoir modelling (use commercial tools).
场景推荐方案
通过地表数据进行3D隐式地质建模GemPy - 专为该场景打造，原生支持Python
带构造框架的复杂褶皱建模LoopStructural - 褶皱支持更出色
商业级地下建模SKUA-GOCAD - 行业标准，专有软件
仅需快速生成2D剖面图GemPy 可实现但略显冗余；可考虑手动插值
需要基于地质模型生成重力/磁法正演模型GemPy - 内置位场支持
选择GemPy的场景：当你需要通过地表接触点和产状构建包含断层/不整合面关系的隐式3D地质模型，尤其是需要集成到Python工作流中时。对于标准场景，它的学习曲线比LoopStructural更平缓。
避免使用GemPy的场景：当地质情况以复杂褶皱为主时（使用LoopStructural），或者你需要生产级油藏建模时（使用商业工具）。

Common Workflows

常见工作流

Build 3D geological model from surface data

通过地表数据构建3D地质模型

  • Load or define surface contact points (min 2 per surface) and orientations (min 1 per surface)
  • Create 
    GeoModel
    with appropriate extent and resolution
  • Add surface points with 
    gp.add_surface_points()
  • Add orientations with 
    gp.add_orientations()
  • Map geological stack with 
    gp.map_stack_to_surfaces()
  • Set structural relations (ERODE, ONLAP, FAULT)
  • Set interpolator with 
    gp.set_interpolator()
  • Compute model with 
    gp.compute_model()
  • Validate with 2D cross-sections using 
    gp.plot_2d()
  • Visualize 3D result with 
    gp.plot_3d()
    or export to VTK
  • 加载或定义地表接触点（每个地表至少2个）和产状（每个地表至少1个）
  • 创建具有合适范围和分辨率的
    GeoModel
  • 使用
    gp.add_surface_points()
    添加地表点
  • 使用
    gp.add_orientations()
    添加产状
  • 使用
    gp.map_stack_to_surfaces()
    映射地质层序
  • 设置构造关系（ERODE、ONLAP、FAULT）
  • 使用
    gp.set_interpolator()
    设置插值器
  • 使用
    gp.compute_model()
    计算模型
  • 使用
    gp.plot_2d()
    生成2D剖面图验证模型
  • 使用
    gp.plot_3d()
    可视化3D结果或导出为VTK格式

Common Issues

常见问题

IssueSolution
Model not computingCheck min 2 points + 1 orientation per surface
Artifacts at edgesExtend model extent beyond data
Wrong fault offsetCheck pole_vector direction
Memory errorsReduce grid resolution
问题解决方案
模型无法计算检查每个地表是否至少有2个点 + 1个产状
边缘出现伪影将模型范围扩展至数据之外
断层偏移错误检查pole_vector方向
内存错误降低网格分辨率

References

参考资料

  • Structural Relations - Detailed guide on ERODE, ONLAP, FAULT
  • Data Requirements - Input data formats and constraints
  • Troubleshooting - Common problems and solutions
  • 构造关系 - 关于ERODE、ONLAP、FAULT的详细指南
  • 数据要求 - 输入数据格式与约束
  • 故障排查 - 常见问题与解决方案

Scripts

脚本

  • scripts/validate_input.py - Validate input data files
  • scripts/export_model.py - Export model to VTK, numpy, or CSV
  • scripts/validate_input.py - 验证输入数据文件
  • scripts/export_model.py - 将模型导出为VTK、numpy或CSV格式