# gempy-project/gempy architecture

> Architecture diagram of the GitHub repository gempy-project/gempy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gempy-project/gempy
- Repository: https://github.com/gempy-project/gempy

## Overview

GemPy is a Python geomodeling library for building implicit 3D geological models. Users define geological structure and observations, configure spatial grids, then compute model solutions; the package also supports fault relationships, topography, serialization, and compatibility workflows. The graph separates API orchestration, model data, computation, and persistence. Several capabilities are documented or indexed but their implementation was not sampled, so some subsystem links are shown as unverified rather than asserted as direct calls.

Main entry points: [`gempy/API/compute_API.py`](https://github.com/gempy-project/gempy/blob/main/gempy/API/compute_API.py) (Compute API), [`gempy/API/initialization_API.py`](https://github.com/gempy-project/gempy/blob/main/gempy/API/initialization_API.py) (Model setup API), [`gempy/API/grid_API.py`](https://github.com/gempy-project/gempy/blob/main/gempy/API/grid_API.py) (Grid API), [`gempy/core/data/structural_frame.py`](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/structural_frame.py) (Structural frame)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User API"]
  node_init_api["Model setup API"]
  node_io_api["Observation I/O<br/>[io_API.py]"]
  node_grid_api["Grid API<br/>[grid_API.py]"]
  node_compute_api["Compute API<br/>[compute_API.py]"]
  node_field_api["Field evaluation"]
  node_fault_api["Fault API<br/>[faults_API.py]"]
end

subgraph group_model["Model data"]
  node_geo_model["GeoModel<br/>[geo_model.py]"]
  node_structure["Structural frame"]
  node_surface_points["Surface observations<br/>[surface_points.py]"]
  node_orientations["Orientation observations<br/>[orientations.py]"]
  node_grid["Spatial grids<br/>[grid.py]"]
  node_regular_grid["Regular grid<br/>[regular_grid.py]"]
  node_topography["Topography<br/>[topography.py]"]
  node_colors["Color palette<br/>[color_generator.py]"]
end

subgraph group_compute["Computation and outputs"]
  node_engine_factory["Interpolation inputs<br/>[_engine_factory.py]"]
  node_engine{{"GemPy engine"}}
  node_mesh["Mesh extraction<br/>[marching_cubes.py]"]
  node_nuggets["Nugget optimization<br/>[_optimizer.py]"]
end

subgraph group_persistence["Persistence and compatibility"]
  node_save_load["Model serialization<br/>[save_load.py]"]
  node_json_io["JSON operations<br/>[json_operations.py]"]
  node_compat_in["Legacy input adapter"]
  node_compat_out["Legacy output adapter"]
  node_optional["Optional dependencies"]
end

node_user(("Model user"))

node_user -->|"defines model"| node_init_api
node_user -->|"provides observations"| node_io_api
node_user -->|"configures grids"| node_grid_api
node_init_api -->|"creates"| node_geo_model
node_init_api -->|"builds structure"| node_structure
node_init_api -->|"uses"| node_io_api
node_io_api -->|"loads points"| node_surface_points
node_io_api -->|"loads orientations"| node_orientations
node_structure -->|"groups observations"| node_surface_points
node_structure -->|"groups observations"| node_orientations
node_structure -->|"assigns colors"| node_colors
node_grid_api -->|"configures"| node_grid
node_grid_api -->|"creates topography"| node_topography
node_grid -->|"uses"| node_regular_grid
node_grid -->|"uses"| node_topography
node_user -->|"requests solution"| node_compute_api
node_compute_api -->|"computes model"| node_geo_model
node_compute_api -->|"uses grid API"| node_grid_api
node_compute_api -->|"uses evaluation API"| node_field_api
node_geo_model -->|"builds inputs"| node_engine_factory
node_engine_factory -->|"reads grid"| node_grid
node_engine_factory -->|"reads structure"| node_structure
node_compute_api -.->|"dispatches computation"| node_engine
node_engine -.->|"supports extraction"| node_mesh
node_compute_api -->|"optimizes nuggets"| node_nuggets
node_compute_api -->|"uses serialization"| node_save_load
node_user -->|"saves or loads"| node_save_load
node_save_load -->|"serializes model"| node_geo_model
node_user -.->|"imports or exports"| node_json_io
node_user -.->|"uses compatibility"| node_compat_in
node_user -.->|"uses compatibility"| node_compat_out
node_init_api -->|"checks dependencies"| node_optional
node_grid_api -->|"checks dependencies"| node_optional

click node_init_api "https://github.com/gempy-project/gempy/blob/main/gempy/API/initialization_API.py"
click node_io_api "https://github.com/gempy-project/gempy/blob/main/gempy/API/io_API.py"
click node_grid_api "https://github.com/gempy-project/gempy/blob/main/gempy/API/grid_API.py"
click node_compute_api "https://github.com/gempy-project/gempy/blob/main/gempy/API/compute_API.py"
click node_field_api "https://github.com/gempy-project/gempy/blob/main/gempy/API/field_evaluation_API.py"
click node_fault_api "https://github.com/gempy-project/gempy/blob/main/gempy/API/faults_API.py"
click node_geo_model "https://github.com/gempy-project/gempy/blob/main/gempy/core/data/geo_model.py"
click node_structure "https://github.com/gempy-project/gempy/blob/main/gempy/core/data/structural_frame.py"
click node_surface_points "https://github.com/gempy-project/gempy/blob/main/gempy/core/data/surface_points.py"
click node_orientations "https://github.com/gempy-project/gempy/blob/main/gempy/core/data/orientations.py"
click node_grid "https://github.com/gempy-project/gempy/blob/main/gempy/core/data/grid.py"
click node_regular_grid "https://github.com/gempy-project/gempy/blob/main/gempy/core/data/grid_modules/regular_grid.py"
click node_topography "https://github.com/gempy-project/gempy/blob/main/gempy/core/data/grid_modules/topography.py"
click node_colors "https://github.com/gempy-project/gempy/blob/main/gempy/core/color_generator.py"
click node_engine_factory "https://github.com/gempy-project/gempy/blob/main/gempy/modules/data_manipulation/_engine_factory.py"
click node_mesh "https://github.com/gempy-project/gempy/blob/main/gempy/modules/mesh_extranction/marching_cubes.py"
click node_nuggets "https://github.com/gempy-project/gempy/blob/main/gempy/modules/optimize_nuggets/_optimizer.py"
click node_save_load "https://github.com/gempy-project/gempy/blob/main/gempy/modules/serialization/save_load.py"
click node_json_io "https://github.com/gempy-project/gempy/blob/main/gempy/modules/json_io/json_operations.py"
click node_compat_in "https://github.com/gempy-project/gempy/blob/main/gempy/API/gp2_gp3_compatibility/gp3_to_gp2_input.py"
click node_compat_out "https://github.com/gempy-project/gempy/blob/main/gempy/API/gp2_gp3_compatibility/gp3_to_gp2_output.py"
click node_optional "https://github.com/gempy-project/gempy/blob/main/gempy/optional_dependencies.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_init_api,node_io_api,node_grid_api,node_compute_api,node_field_api,node_fault_api,node_user toneBlue
class node_geo_model,node_structure,node_surface_points,node_orientations,node_grid,node_regular_grid,node_topography,node_colors toneAmber
class node_engine_factory,node_engine,node_mesh,node_nuggets toneMint
class node_save_load,node_json_io,node_compat_in,node_compat_out,node_optional toneRose
```

## Components

### User API

- [Model setup API](https://github.com/gempy-project/gempy/blob/main/gempy/API/initialization_API.py): `gempy/API/initialization_API.py`
- [Observation I/O](https://github.com/gempy-project/gempy/blob/main/gempy/API/io_API.py): `gempy/API/io_API.py`
- [Grid API](https://github.com/gempy-project/gempy/blob/main/gempy/API/grid_API.py): `gempy/API/grid_API.py`
- [Compute API](https://github.com/gempy-project/gempy/blob/main/gempy/API/compute_API.py): `gempy/API/compute_API.py`
- [Field evaluation](https://github.com/gempy-project/gempy/blob/main/gempy/API/field_evaluation_API.py): `gempy/API/field_evaluation_API.py`
- [Fault API](https://github.com/gempy-project/gempy/blob/main/gempy/API/faults_API.py): `gempy/API/faults_API.py`

### Model data

- [GeoModel](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/geo_model.py): `gempy/core/data/geo_model.py`
- [Structural frame](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/structural_frame.py): `gempy/core/data/structural_frame.py`
- [Surface observations](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/surface_points.py): `gempy/core/data/surface_points.py`
- [Orientation observations](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/orientations.py): `gempy/core/data/orientations.py`
- [Spatial grids](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/grid.py): `gempy/core/data/grid.py`
- [Regular grid](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/grid_modules/regular_grid.py): `gempy/core/data/grid_modules/regular_grid.py`
- [Topography](https://github.com/gempy-project/gempy/blob/main/gempy/core/data/grid_modules/topography.py): `gempy/core/data/grid_modules/topography.py`
- [Color palette](https://github.com/gempy-project/gempy/blob/main/gempy/core/color_generator.py): `gempy/core/color_generator.py`

### Computation and outputs

- [Interpolation inputs](https://github.com/gempy-project/gempy/blob/main/gempy/modules/data_manipulation/_engine_factory.py): `gempy/modules/data_manipulation/_engine_factory.py`
- **GemPy engine**
- [Mesh extraction](https://github.com/gempy-project/gempy/blob/main/gempy/modules/mesh_extranction/marching_cubes.py): `gempy/modules/mesh_extranction/marching_cubes.py`
- [Nugget optimization](https://github.com/gempy-project/gempy/blob/main/gempy/modules/optimize_nuggets/_optimizer.py): `gempy/modules/optimize_nuggets/_optimizer.py`

### Persistence and compatibility

- [Model serialization](https://github.com/gempy-project/gempy/blob/main/gempy/modules/serialization/save_load.py): `gempy/modules/serialization/save_load.py`
- [JSON operations](https://github.com/gempy-project/gempy/blob/main/gempy/modules/json_io/json_operations.py): `gempy/modules/json_io/json_operations.py`
- [Legacy input adapter](https://github.com/gempy-project/gempy/blob/main/gempy/API/gp2_gp3_compatibility/gp3_to_gp2_input.py): `gempy/API/gp2_gp3_compatibility/gp3_to_gp2_input.py`
- [Legacy output adapter](https://github.com/gempy-project/gempy/blob/main/gempy/API/gp2_gp3_compatibility/gp3_to_gp2_output.py): `gempy/API/gp2_gp3_compatibility/gp3_to_gp2_output.py`
- [Optional dependencies](https://github.com/gempy-project/gempy/blob/main/gempy/optional_dependencies.py): `gempy/optional_dependencies.py`

### Other components

- **Model user**

## Connections

- Model user → Model setup API: defines model
- Model user → Observation I/O: provides observations
- Model user → Grid API: configures grids
- Model setup API → GeoModel: creates (evidence: `gempy/API/initialization_API.py`)
- Model setup API → Structural frame: builds structure (evidence: `gempy/API/initialization_API.py`)
- Model setup API → Observation I/O: uses (evidence: `gempy/API/initialization_API.py`)
- Observation I/O → Surface observations: loads points (evidence: `gempy/API/io_API.py`)
- Observation I/O → Orientation observations: loads orientations (evidence: `gempy/API/io_API.py`)
- Structural frame → Surface observations: groups observations (evidence: `gempy/core/data/structural_frame.py`)
- Structural frame → Orientation observations: groups observations (evidence: `gempy/core/data/structural_frame.py`)
- Structural frame → Color palette: assigns colors (evidence: `gempy/core/data/structural_frame.py`)
- Grid API → Spatial grids: configures (evidence: `gempy/API/grid_API.py`)
- Grid API → Topography: creates topography (evidence: `gempy/API/grid_API.py`)
- Spatial grids → Regular grid: uses (evidence: `gempy/core/data/grid.py`)
- Spatial grids → Topography: uses (evidence: `gempy/core/data/grid.py`)
- Model user → Compute API: requests solution
- Compute API → GeoModel: computes model (evidence: `gempy/API/compute_API.py`)
- Compute API → Grid API: uses grid API (evidence: `gempy/API/compute_API.py`)
- Compute API → Field evaluation: uses evaluation API (evidence: `gempy/API/compute_API.py`)
- GeoModel → Interpolation inputs: builds inputs (evidence: `gempy/core/data/geo_model.py`)
- Interpolation inputs → Spatial grids: reads grid (evidence: `gempy/modules/data_manipulation/_engine_factory.py`)
- Interpolation inputs → Structural frame: reads structure (evidence: `gempy/modules/data_manipulation/_engine_factory.py`)
- Compute API → GemPy engine: dispatches computation
- GemPy engine → Mesh extraction: supports extraction
- Compute API → Nugget optimization: optimizes nuggets (evidence: `gempy/API/compute_API.py`)
- Compute API → Model serialization: uses serialization (evidence: `gempy/API/compute_API.py`)
- Model user → Model serialization: saves or loads
- Model serialization → GeoModel: serializes model (evidence: `gempy/modules/serialization/save_load.py`)
- Model user → JSON operations: imports or exports
- Model user → Legacy input adapter: uses compatibility
- Model user → Legacy output adapter: uses compatibility
- Model setup API → Optional dependencies: checks dependencies (evidence: `gempy/API/initialization_API.py`)
- Grid API → Optional dependencies: checks dependencies (evidence: `gempy/API/grid_API.py`)