GemPy

https://docs.gempy.org/
Admin
GemPy is an open-source Python library for implicit 3D structural geological modeling and...
Tokens:141,988
Snippets:1,265
Trust Score:7.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manual Installation from Repository

Source: https://docs.gempy.org/_sources/installation.rst.txt

Clones the GemPy repository and performs an editable installation.

```bash
$ git clone https://github.com/cgre-aachen/gempy.git
```

```bash
$ pip install -e .
```

--------------------------------

### Create Model 5 Example

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Initializes a geological model example named 'Model 5'.

```Python
create_example('Model 5')
```

--------------------------------

### Generate Example Models

Source: https://docs.gempy.org/_modules/gempy/API/examples_generator.html

Main entry point for generating specific example models based on the provided enumerator.

```python
def generate_example_model(example_model: ExampleModel, compute_model: bool = True) -> gp.data.GeoModel:
    match example_model:
        case ExampleModel.HORIZONTAL_STRAT:
            return _generate_horizontal_stratigraphic_model(compute_model)
        case ExampleModel.ANTICLINE:
            return _generate_anticline_model(compute_model)
        case ExampleModel.ONE_FAULT:
            return _generate_one_fault_model(compute_model)
        case ExampleModel.TWO_AND_A_HALF_D:
            return _generate_2_5d_model(compute_model)
        case ExampleModel.COMBINATION:
            return _generate_combination_model(compute_model)
        case ExampleModel.ONE_FAULT_GRAVITY:
            return _generate_one_fault_model_gravity(compute_model)
        case ExampleModel.GRABEN:
            return _generate_graben_model(compute_model)
        case ExampleModel.GREENSTONE:
            return _generate_greenstone_model(compute_model)
        case ExampleModel.FAULT_RELATION:
            return _generate_fault_relation_model(compute_model)
        case _:
            raise NotImplementedError(f"Example model {example_model} not implemented.")
```

--------------------------------

### Create Model 8 Example

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Initializes the Model 8 structural example using the create_example function.

```Python
create_example('Model 8')
```

--------------------------------

### Generate Specific Models

Source: https://docs.gempy.org/_downloads/63104c414841e116bba92672ce2656c3/h08_more_examples.ipynb

Examples of calling the create_example function for different model configurations.

```python
create_example('Model 1')
```

```python
create_example('Model 2')
```

```python
create_example('Model 3')
```

--------------------------------

### Create Geological Model Example

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Executes the creation of a specific geological model instance.

```python
create_example('Model 1')
```

--------------------------------

### Create Model 3 Example

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Initializes a specific geological model configuration named 'Model 3'.

```Python
create_example('Model 3')
```

--------------------------------

### Install GemPy Core

Source: https://docs.gempy.org/_sources/installation.rst.txt

Installs the core version of GemPy with minimal dependencies.

```bash
$ pip install gempy
```

--------------------------------

### Install GemPy Viewer

Source: https://docs.gempy.org/_sources/installation.rst.txt

Installs the gempy-viewer package for 2-D and 3-D visualization.

```bash
$ pip install gempy-viewer
```

--------------------------------

### Create Fold Model Example

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Initializes a fold model named 'Model 6'.

```Python
create_example('Model 6')
```

--------------------------------

### gempy.generate_example_model(example_model, compute_model=True)

Source: https://docs.gempy.org/GemPy%20API/gempy.generate_example_model.html

Generates an example model. Returns a GeoModel object.

```APIDOC
## gempy.generate_example_model

### Description
Generates an example model based on the provided ExampleModel configuration.

### Signature
gempy.generate_example_model(example_model: ExampleModel, compute_model: bool = True) -> GeoModel

### Parameters
- **example_model** (ExampleModel) - Required - The configuration object for the example model.
- **compute_model** (bool) - Optional - Whether to compute the model upon generation. Defaults to True.

### Returns
- **GeoModel** - The generated geological model.
```

--------------------------------

### Create Horizontal Tilted Model

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Initializes a geological model example with horizontal tilted layers using the create_example function.

```Python
create_example('Model 9')
```

--------------------------------

### Model Computation Output

Source: https://docs.gempy.org/examples/real/Hecho.html

Example console output showing GPU device usage and condition number calculations during model computation.

```text
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Condition number: 1546449.7334630927.
Chunking done: 21 chunks
Condition number: 1545102.643050272.
Chunking done: 26 chunks
Condition number: 1447785.0114886982.
Chunking done: 21 chunks
Condition number: 40165630.3512226.
Chunking done: 1052 chunks
Chunking done: 9 chunks
Chunking done: 59 chunks
Chunking done: 32 chunks
```

--------------------------------

### Inspect structural element output

Source: https://docs.gempy.org/tutorials/a_getting_started/video_tutorial_model_1.html

Example output showing the properties of structural elements including name, color, and activity status.

```python
[Element(
    name=rock1,
    color=#015482,
    is_active=True
), Element(
    name=rock2,
    color=#9f0052,
    is_active=True
), Element(
    name=rock3,
    color=#ffbe00,
    is_active=True
), Element(
    name=basement,
    color=#728f02,
    is_active=True
)]
```

--------------------------------

### Visualizing model output

Source: https://docs.gempy.org/_sources/examples/geometries/a01_horizontal_stratigraphic.rst.txt

Provides examples for 2D and 3D visualization of the computed geological model.

```Python
gpv.plot_2d(geo_model, direction=['y'], show_results=False)
```

```Python
gpv.plot_2d(geo_model, direction=['x'], show_data=True)
gpv.plot_2d(geo_model, direction=['y'], show_data=True)
```

```Python
gpv.plot_3d(geo_model, show_lith=True, show_boundaries=True, ve=None)
```

--------------------------------

### Initialize Geological Models

Source: https://docs.gempy.org/examples/geometries/h08_more_examples.html

Use the create_example function to load specific geological model configurations.

```python
create_example('Model 1')
```

```python
create_example('Model 2')
```

```python
create_example('Model 3')
```

```python
create_example('Model 5')
```

```python
create_example('Model 6')
```

--------------------------------

### Get Section Arguments

Source: https://docs.gempy.org/_modules/gempy/core/data/grid.html

Retrieves the start and end indices for a specific section by name.

```python
def get_section_args(self, section_name: str):
    # TODO: This method should be part of the sections
    # assert type(section_name) is str, 'Only one section type can be retrieved'
    l0, l1 = self.get_grid_args('sections')
    where = np.where(self.sections.names == section_name)[0][0]
    return l0 + self.sections.length[where], l0 + self.sections.length[where + 1]
```

--------------------------------

### Initialize Environment and Dependencies

Source: https://docs.gempy.org/_downloads/1f573463d0adc854b42179f113f11514/e05_3d_visualization.ipynb

Imports necessary libraries and sets a random seed for reproducibility.

```python
import numpy as np
import pyvista as pv

import gempy as gp
import gempy_viewer as gpv

np.random.seed(1234)
```

--------------------------------

### Install Enhanced GemPy Features

Source: https://docs.gempy.org/_sources/installation.rst.txt

Installs GemPy with specific dependency sets for base, optional, or development features.

```bash
$ pip install gempy[base]
```

```bash
$ pip install gempy[opt]
```

```bash
$ pip install gempy[dev]
```

--------------------------------

### Import Dependencies and Initialize Environment

Source: https://docs.gempy.org/_downloads/512484d2645b889d63f366a1c5d4acd4/b02_gravity.ipynb

Imports necessary libraries and sets global configuration for random seeds and pandas display precision.

```python
import gempy as gp
import gempy_viewer as gpv

# Aux imports
import numpy as np
import pandas as pd
import os
import matplotlib.pyplot as plt


np.random.seed(1515)
pd.set_option('display.precision', 2)
```

--------------------------------

### Create specific geological models

Source: https://docs.gempy.org/examples/geometries/h08_more_examples.html

Use the create_example function to initialize predefined geological model configurations.

```python
create_example('Model 7')
```

```python
create_example('Model 8')
```

```python
create_example('Model 9')
```

--------------------------------

### Define Configuration Backends and Environment Variables

Source: https://docs.gempy.org/_modules/gempy_engine/config.html

Defines enumeration flags for backends and dual contouring, and initializes configuration settings from .env files.

```python
from importlib.util import find_spec
from enum import Enum, auto, Flag
import os
from dotenv import load_dotenv




[docs]
class AvailableBackends(Flag):
    numpy = auto()
    PYTORCH = auto()

class DualContouringOverlap(Flag):
    none = auto()
    pretty = auto()
    watertight = auto()

# Define the paths for the .env files

script_dir = os.path.dirname(os.path.abspath(__file__))

dotenv_path = os.path.join(script_dir, '../.env')
dotenv_gempy_engine_path = os.path.expanduser('~/.env_gempy_engine')

# Check if the .env files exist and prioritize the local .env file
if os.path.exists(dotenv_path):
    load_dotenv(dotenv_path)
elif os.path.exists(dotenv_gempy_engine_path):
    load_dotenv(dotenv_gempy_engine_path)
else:
    load_dotenv()

DEBUG_MODE = os.getenv('DEBUG_MODE', 'False') == 'True'  # Note the handling of Boolean values
OPTIMIZE_MEMORY = os.getenv('OPTIMIZE_MEMORY', 'True') == 'True'
DEFAULT_BACKEND = AvailableBackends[os.getenv('DEFAULT_BACKEND', 'numpy')]
DEFAULT_PYKEOPS = os.getenv('DEFAULT_PYKEOPS', 'False') == 'True'
DEFAULT_TENSOR_DTYPE = os.getenv('DEFAULT_TENSOR_DTYPE', 'float64')
LINE_PROFILER_ENABLED = os.getenv('LINE_PROFILER_ENABLED', 'False') == 'True'
SET_RAW_ARRAYS_IN_SOLUTION = os.getenv('SET_RAW_ARRAYS_IN_SOLUTION', 'True') == 'True'
NOT_MAKE_INPUT_DEEP_COPY = os.getenv('NOT_MAKE_INPUT_DEEP_COPY', 'False') == 'True'
DUAL_CONTOURING_VERTEX_OVERLAP = DualContouringOverlap[os.getenv('DUAL_CONTOURING_VERTEX_OVERLAP', 'none')]
DUAL_CONTOURING_FAULT_OVERLAP_THREADING = os.getenv('DUAL_CONTOURING_FAULT_OVERLAP_THREADING', 'True') == 'True'

is_numpy_installed = find_spec("numpy") is not None
is_tensorflow_installed = find_spec("tensorflow") is not None
is_pytorch_installed = find_spec("torch")
is_pykeops_installed = find_spec("pykeops") is not None
```

--------------------------------

### Initialize GemPy and Data Paths

Source: https://docs.gempy.org/_downloads/72cace2d13ca9f902d5f45391e3637eb/video_tutorial_model_1.ipynb

Imports necessary libraries and defines the remote URL path for tutorial input data.

```python
# Required imports
import gempy as gp
import gempy_viewer as gpv
```

```python
# Path to input data
data_path = "https://raw.githubusercontent.com/cgre-aachen/gempy_data/master/"
path_to_data = data_path + "/data/input_data/video_tutorials_v3/"
```

--------------------------------

### Get Transform Matrix

Source: https://docs.gempy.org/_modules/gempy_engine/core/data/transforms.html

Constructs a 4x4 transformation matrix based on position, rotation, and scale.

```python
def get_transform_matrix(self, transform_type: TransformOpsOrder = TransformOpsOrder.SRT) -> np.ndarray:
        T = np.eye(4)
        R = np.eye(4)
        S = np.eye(4)

        T[:3, 3] = self.position

        rx, ry, rz = np.radians(self.rotation)
        Rx = np.array(
            [[1, 0, 0],
             [0, np.cos(rx), -np.sin(rx)],
             [0, np.sin(rx), np.cos(rx)]]
        )

        Ry = np.array(
            [[np.cos(ry), 0, np.sin(ry)],
             [0, 1, 0],
             [-np.sin(ry), 0, np.cos(ry)]]
        )

        Rz = np.array(
            [[np.cos(rz), -np.sin(rz), 0],
             [np.sin(rz), np.cos(rz), 0],
             [0, 0, 1]]
        )

        R[:3, :3] = Rx @ Ry @ Rz
        S[:3, :3] = np.diag(self.scale)

        match transform_type:
            case TransformOpsOrder.TRS:
                return T @ R @ S
            case TransformOpsOrder.SRT:
                return S @ R @ T
            case _:
                raise NotImplementedError(f"Transform type {transform_type} not implemented")
```

--------------------------------

### Define Data Path

Source: https://docs.gempy.org/_downloads/8af65571858ed0f970292b228d177831/video_tutorial_model_3_onlap.ipynb

Sets the base URL for fetching tutorial input data.

```python
# Path to input data
data_path = "https://raw.githubusercontent.com/cgre-aachen/gempy_data/master/"
path_to_data = data_path + "/data/input_data/video_tutorials_v3/"
```

--------------------------------

### Initialize 3D Plotting and Data Configuration

Source: https://docs.gempy.org/_modules/gempy_viewer/API/_plot_3d_API.html

Sets up the plotting environment by parsing keyword arguments and initializing the GemPyToVista interface.

```python
from gempy_viewer.modules.plot_3d.drawer_input_3d import plot_data
from gempy_viewer.modules.plot_3d.drawer_structured_grid_3d import plot_structured_grid
from gempy_viewer.modules.plot_3d.drawer_surfaces_3d import plot_surfaces
from gempy_viewer.modules.plot_3d.drawer_topography_3d import plot_topography_3d
from gempy_viewer.modules.plot_3d.plot_3d_utils import set_scalar_bar

# * Grab from kwargs all the show arguments and create the proper class. This is for backwards compatibility
can_show_results = model.solutions is not None  # and model.solutions.lith_block.shape[0] != 0
data_to_show = DataToShow(
    n_axis=1,
    show_data=kwargs.get('show_data', True),
    _show_results=kwargs.get('show_results', can_show_results),
    show_surfaces=kwargs.get('show_surfaces', True),
    show_lith=kwargs.get('show_lith', True),
    show_scalar=kwargs.get('show_scalar', False),
    show_boundaries=kwargs.get('show_boundaries', True),
    show_topography=kwargs.get('show_topography', True),
    show_section_traces=kwargs.get('show_section_traces', True),
    show_values=kwargs.get('show_values', False),
    show_block=kwargs.get('show_block', False)
)
kwargs_plot_topography = kwargs_plot_topography or {}
kwargs_plot_structured_grid = kwargs_plot_structured_grid or {}
kwargs_plot_data = kwargs_plot_data or {}
kwargs_plotter = kwargs_plotter or {}
kwargs_plot_surfaces = kwargs_plot_surfaces or {}
kwargs_pyvista_bounds = kwargs_pyvista_bounds or {}
kwargs_pyvista_camera = kwargs_pyvista_camera or {}

if image is True:
    show = True
    kwargs_plotter['off_screen'] = True
    plotter_type = 'basic'

if model.solutions is None:
    data_to_show.show_results = False
    solutions_raw_arrays = None
else:
    solutions_raw_arrays = model.solutions.raw_arrays

    
extent = model.grid.extent if transformed_data is False else model.extent_transformed_transformed_by_input
gempy_vista = GemPyToVista(
    extent=extent,
    plotter_type=plotter_type,
    pyvista_bounds_kwargs=kwargs_pyvista_bounds,
    pyvista_camera_kwargs=kwargs_pyvista_camera,
    **kwargs_plotter
)
```

--------------------------------

### Backend Configuration Output

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Displays the console output confirming the PyTorch backend initialization.

```none
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
```

--------------------------------

### ColorsGenerator.__init__

Source: https://docs.gempy.org/_sources/Helper%20Classes/gempy.core.data.ColorsGenerator.rst.txt

Initializes the ColorsGenerator instance.

```APIDOC
## ColorsGenerator.__init__

### Description
Initializes a new instance of the ColorsGenerator class.
```

--------------------------------

### Initialize GemPy Environment

Source: https://docs.gempy.org/_downloads/df04afb9899e993f296d600a611accac/a01_cell_selection.ipynb

Imports necessary libraries and configures global settings for the simulation.

```python
# Importing gempy
import gempy as gp

# Aux imports
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

np.random.seed(1515)
pd.set_option('display.precision', 2)
```

--------------------------------

### Backend Initialization Logs

Source: https://docs.gempy.org/examples/geometries/h08_more_examples.html

Logs generated during the initialization of the PyTorch backend for geological models.

```text
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
```

```text
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Chunking done: 6 chunks
Chunking done: 9 chunks
```

```text
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Chunking done: 6 chunks
```

```text
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Chunking done: 7 chunks
```

```text
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Chunking done: 7 chunks
Chunking done: 7 chunks
```

--------------------------------

### Define Custom Section Grids

Source: https://docs.gempy.org/_sources/tutorials/a_getting_started/video_tutorial_model_1.rst.txt

Sets up custom cross-section lines within the model grid by defining start, stop, and resolution parameters.

```Python
# Create custom section lines
gp.set_section_grid(
    grid=geo_model.grid,
    section_dict={
        'section1': ([0, 0], [2500, 1000], [100, 50]),
        'section2': ([1000, 1000], [1500, 0], [100, 100]),
    }
)
```

--------------------------------

### Initialize Grid

Source: https://docs.gempy.org/_modules/gempy/core/data/grid.html

The constructor allows for optional initialization of a dense grid using extent and resolution parameters.

```python
def __init__(self, extent=None, resolution=None):

    self.values = np.empty((0, 3))
    self.length = np.empty(0)

    # Init basic grid empty
    if extent is not None and resolution is not None:
        self.dense_grid = RegularGrid(extent, resolution)
```

--------------------------------

### Create Geological Model Instance

Source: https://docs.gempy.org/_downloads/72cace2d13ca9f902d5f45391e3637eb/video_tutorial_model_1.ipynb

Initializes a geomodel with specific extent, resolution, and input data files.

```python
# Create instance of geomodel
geo_model = gp.create_geomodel(
    project_name = 'tutorial_model',
    extent=[0,2500,0,1000,0,1000],
    resolution=[100,40,40],
    importer_helper=gp.data.ImporterHelper(
        path_to_orientations=path_to_data+"tutorial_model_orientations.csv",
        path_to_surface_points=path_to_data+"tutorial_model_surface_points.csv"
    )
)
```

--------------------------------

### Create Geological Model Instance

Source: https://docs.gempy.org/_downloads/43e6d66cb807262eaf7ec5ac06aca137/video_tutorial_model_2_faults.ipynb

Initializes the geomodel with specific dimensions and imports orientation and surface point data.

```python
# Create instance of geomodel
geo_model = gp.create_geomodel(
    project_name = 'tutorial_model_faults',
    extent=[0,3000,0,1000,0,1000],
    resolution=[90,30,30],
    importer_helper=gp.data.ImporterHelper(
        path_to_orientations=path_to_data + "tutorial_model_faults_1_orientations.csv",
        path_to_surface_points=path_to_data + "tutorial_model_faults_1_surface_points.csv"
    )
)
```

--------------------------------

### Initialize and Compute Model

Source: https://docs.gempy.org/_downloads/6e074fa325ab20d7e28620ab80b05b31/d04_topology.ipynb

Creates a geological model, maps surfaces to stacks, defines faults, and computes the interpolation.

```python
data_path = os.path.abspath('../../')

geo_model = gp.create_geomodel(
    project_name='Model_Tutorial6',
    extent=[0, 3000, 0, 20, 0, 2000],
    resolution=[50, 10, 67],
    refinement=1,  # * For this model is better not to use octrees because we want to see what is happening in the scalar fields
    importer_helper=gp.data.ImporterHelper(
        path_to_orientations=data_path + "/data/input_data/tut_chapter6/ch6_data_fol.csv",
        path_to_surface_points=data_path + "/data/input_data/tut_chapter6/ch6_data_interf.csv",
    )
)

gp.map_stack_to_surfaces(
    gempy_model=geo_model,
    mapping_object=
    {
        "fault": "Fault",
        "Rest": ('Layer 2', 'Layer 3', 'Layer 4', 'Layer 5')
    }
)

gp.set_is_fault(geo_model, ['fault'])

geo_model.interpolation_options.mesh_extraction = False
gp.compute_model(geo_model)
```

--------------------------------

### Configure Centered Grid

Source: https://docs.gempy.org/_sources/tutorials/b_fundamentals/c03_grids.rst.txt

Set up a centered grid with specific resolution and radius parameters for physics computations.

```Python
centers = np.array([[1000, 1000, 750]])
gp.set_centered_grid(
    geo_model.grid,
    centers=centers,
    resolution=[10, 10, 20],
    radius=np.array([1000, 1000, 1000])
)
geo_model.grid.active_grids
gp.compute_model(geo_model)
```

```none
Active grids: GridTypes.DENSE|CUSTOM|CENTERED|NONE
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
```

--------------------------------

### Initialize Geological Model

Source: https://docs.gempy.org/_downloads/2d7d09aaf014992a3cad066b50a20c60/Moureze.ipynb

Sets up surface points, orientations, and the structural frame to create a new GemPy geological model.

```python
resolution_requ = [156, 206, 76]
resolution = [77, 103, 38]
resolution_low = [45, 51, 38]


surface_points_table = gp.data.SurfacePointsTable.from_arrays(
    x=surface_points['X'].values,
    y=surface_points['Y'].values,
    z=surface_points['Z'].values,
    names=surface_points['surface'].values.astype(str)
)

orientations_table = gp.data.OrientationsTable.from_arrays(
    x=orientations['X'].values,
    y=orientations['Y'].values,
    z=orientations['Z'].values,
    G_x=orientations['G_x'].values,
    G_y=orientations['G_y'].values,
    G_z=orientations['G_z'].values,
    names=orientations['surface'].values.astype(str),
    name_id_map=surface_points_table.name_id_map  # ! Make sure that ids and names are shared
)

structural_frame = gp.data.StructuralFrame.from_data_tables(
    surface_points=surface_points_table,
    orientations=orientations_table
)

geo_model = gp.create_geomodel(
    project_name='Moureze',
    extent=[-5, 305, -5, 405, -200, -50],
    # resolution=resolution_low,
    refinement=5,
    structural_frame=structural_frame
)
```

--------------------------------

### Initialize Dense Grid

Source: https://docs.gempy.org/_modules/gempy/core/data/grid.html

Creates a new Grid instance with a dense structure.

```python
@classmethod
def init_dense_grid(cls, extent, resolution):
    return cls(extent, resolution)
```

--------------------------------

### Initialize Octree Grid

Source: https://docs.gempy.org/_modules/gempy/core/data/grid.html

Creates a new Grid instance with an octree structure based on the provided extent and levels.

```python
@classmethod
def init_octree_grid(cls, extent, octree_levels, base_resolution: Optional[np.ndarray] = None, legacy: bool = False):
    grid = cls()

    if legacy:
        base_resolution = (np.array([2, 2, 2]))
    elif base_resolution is None:
        lengths = np.array([
                extent[1] - extent[0],  # x
                extent[3] - extent[2],  # y
                extent[5] - extent[4]  # z
        ])

        min_length = np.min(lengths)
        base_resolution = np.round(lengths / min_length).astype(int) * 2

    grid._octree_grid = RegularGrid.octree_init(
        extent=extent,
        octree_levels=octree_levels,
        base_resolution=base_resolution
    )

    grid.active_grids |= grid.GridTypes.OCTREE
    grid._update_values()
    return grid
```

--------------------------------

### Import GemPy Libraries

Source: https://docs.gempy.org/_downloads/15b60ed6fcc7d838a5a5142338f3fb88/b02_fold.ipynb

Initializes the necessary GemPy and GemPy Viewer modules.

```python
# Import necessary libraries
import gempy as gp
import gempy_viewer as gpv

# sphinx_gallery_thumbnail_number = 2
```

--------------------------------

### Import Required Libraries

Source: https://docs.gempy.org/_downloads/2d7d09aaf014992a3cad066b50a20c60/Moureze.ipynb

Initializes the environment by importing GemPy, GemPy Viewer, and standard data manipulation libraries.

```python
import os

# Importing gempy
import gempy as gp
import gempy_viewer as gpv

# Aux imports
import numpy as np
import pandas as pd
```

--------------------------------

### Import GemPy Libraries

Source: https://docs.gempy.org/_downloads/3208e45dad6676218bdfa5746078e216/a01_basics.ipynb

Initializes the necessary libraries for geological modeling and visualization.

```python
import numpy as np

import gempy as gp
import gempy_viewer as gpv
```

--------------------------------

### Initialize Octree Grid

Source: https://docs.gempy.org/_downloads/548a81fce05be005e3a48dc221a0ec19/c03_grids.ipynb

Creates a model using an octree grid by setting resolution to None and specifying refinement levels.

```python
geo_model_octree = build_model('grids_octree', resolution=None, refinement=4)
geo_model_octree.grid.active_grids
```

--------------------------------

### Configure Geophysics Input and Compute Model

Source: https://docs.gempy.org/_modules/gempy/API/examples_generator.html

Sets up geophysical inputs for gravity calculations and computes the model using the PyTorch backend.

```python
geo_model.geophysics_input = gp.data.GeophysicsInput(
        tz=BackendTensor.t.array(gravity_gradient),
        densities=densities_tensor
    )

    # %%
    # Compute the geological model with geophysical data
    # This computation integrates the geological model with gravity data.
    if compute_model:
        sol = gp.compute_model(
            gempy_model=geo_model,
            engine_config=gp.data.GemPyEngineConfig(
                backend=gp.data.AvailableBackends.PYTORCH,
                dtype='float32',
                use_gpu=True
            )
        )
        grav = - sol.gravity
        grav[0].backward()

    return geo_model
```

--------------------------------

### Initializing an Empty SurfacePointsTable

Source: https://docs.gempy.org/_modules/gempy/core/data/surface_points.html

Utility method to create an empty instance of the table.

```python
[docs]
    @classmethod
    def initialize_empty(cls) -> 'SurfacePointsTable':
        """Initialize an empty SurfacePointsTable.

        Returns:
            SurfacePointsTable: An empty instance of SurfacePointsTable.
        """
        return cls(np.zeros(0, dtype=SurfacePointsTable.dt), {})
```

--------------------------------

### Initialize Horizontal Stratigraphic Model

Source: https://docs.gempy.org/_modules/gempy/API/examples_generator.html

Sets up the initial parameters for a horizontal stratigraphic model.

```python
def _generate_horizontal_stratigraphic_model(compute_model: bool) -> gp.data.GeoModel:
    """
    Function to create a geological model of horizontally stacked layers,
    map the geological series to surfaces, and compute the geological model.
    """
    # Define the path to data
    data_path = 'https://raw.githubusercontent.com/cgre-aachen/gempy_data/master/'
```

--------------------------------

### Configuring scene display and output

Source: https://docs.gempy.org/_modules/gempy_viewer/API/_plot_3d_API.html

Handles vertical exaggeration, octree gizmos, screenshot saving, and matplotlib display integration.

```python
    if ve is not None:
        gempy_vista.p.set_scale(zscale=ve)

    if kwargs.get('show_octree', False):
        plot_octree_gizmos(
            model=model, 
            pd3=gempy_vista
        )

    fig_path: str = kwargs.get('fig_path', None)
    if fig_path is not None:
        gempy_vista.p.show(screenshot=fig_path)

    if image is True:
        show = _plot_in_matplotlib(gempy_vista)

    if show is True:
        gempy_vista.p.show()

    return gempy_vista
```

--------------------------------

### View Model Execution Output

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Displays the backend configuration and chunking status during model execution.

```none
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Chunking done: 6 chunks
Chunking done: 9 chunks
```

--------------------------------

### Model Execution Output

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Displays the console output generated during the model initialization process, including backend and GPU settings.

```none
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Chunking done: 6 chunks
```

--------------------------------

### Configure Thumbnail and Plot 3D Model

Source: https://docs.gempy.org/_sources/examples/real/Greenstone.rst.txt

Sets the gallery thumbnail index and renders the 3D geological model with lithology and boundaries enabled.

```Python
sphinx_gallery_thumbnail_number = -1
gpv.plot_3d(geo_model, show_lith=True, show_boundaries=True, ve=None)
```

--------------------------------

### gempy.core.data.ImporterHelper.__init__

Source: https://docs.gempy.org/Helper%20Classes/gempy.core.data.ImporterHelper.html

Initializes the ImporterHelper with file paths and column name mappings for surface points and orientation data.

```APIDOC
## class gempy.core.data.ImporterHelper

### Description
Initializes a helper object to configure the import of geological data, including paths to surface points and orientation files, and mapping of coordinate and orientation column names.

### Constructor
`__init__(path_to_surface_points, path_to_orientations, hash_surface_points=None, hash_orientations=None, coord_x_name='X', coord_y_name='Y', coord_z_name='Z', surface_name='formation', gx_name='G_x', gy_name='G_y', gz_name='G_z', pandas_reader_kwargs=None)`

### Parameters
- **path_to_surface_points** (str | None) - Path to the surface points file.
- **path_to_orientations** (str | None) - Path to the orientations file.
- **hash_surface_points** (str | None) - Optional hash for surface points file.
- **hash_orientations** (str | None) - Optional hash for orientations file.
- **coord_x_name** (str | None) - Column name for X coordinate. Default: 'X'.
- **coord_y_name** (str | None) - Column name for Y coordinate. Default: 'Y'.
- **coord_z_name** (str | None) - Column name for Z coordinate. Default: 'Z'.
- **surface_name** (str | None) - Column name for surface identification. Default: 'formation'.
- **gx_name** (str | None) - Column name for G_x orientation. Default: 'G_x'.
- **gy_name** (str | None) - Column name for G_y orientation. Default: 'G_y'.
- **gz_name** (str | None) - Column name for G_z orientation. Default: 'G_z'.
- **pandas_reader_kwargs** (dict | None) - Additional arguments passed to the pandas reader.
```

--------------------------------

### Initialize Artificial DEM

Source: https://docs.gempy.org/_modules/gempy/core/data/grid_modules/topography.html

Class constructor for creating random topography based on a fractal grid algorithm.

```python
class _LoadDEMArtificial:  # * Cannot think of a good reason to be a class

    def __init__(self, grid=None, fd=2.0, extent=None, resolution=None, d_z=None):
        """Class to create a random topography based on a fractal grid algorithm.

        Args:
            fd:         fractal dimension, defaults to 2.0
            d_z:        maximum height difference. If none, last 20% of the model in z direction
            extent:     extent in xy direction. If none, geo_model.grid.extent
            resolution: desired resolution of the topography array. If none, geo_model.grid.resolution
        """
        self.values_2d = np.array([])
        self.resolution = grid.resolution[:2] if resolution is None else resolution
```

--------------------------------

### Configure Debugging Options

Source: https://docs.gempy.org/_sources/examples/real/Alesmodel.rst.txt

Enable verbose output and condition number computation to assist in tuning model parameters.

```Python
geo_model.interpolation_options.evaluation_options.verbose = True
geo_model.interpolation_options.kernel_options.compute_condition_number = True
```

--------------------------------

### Configure Octree Grid by Levels

Source: https://docs.gempy.org/_modules/gempy/core/data/grid.html

Sets up an octree grid based on a specified number of levels and evaluation options.

```python
def set_octree_grid_by_levels(self, octree_levels: int, evaluation_options: EvaluationOptions, extent: Optional[np.ndarray] = None):
    if extent is None:
        extent = self.extent

    self._octree_grid = RegularGrid(
        extent=extent,
        resolution=np.array([2 ** octree_levels] * 3),
    )
    evaluation_options.number_octree_levels = octree_levels
    self.active_grids |= self.GridTypes.OCTREE
    self._update_values()
```

--------------------------------

### Create and Configure the Geological Model

Source: https://docs.gempy.org/_downloads/1f573463d0adc854b42179f113f11514/e05_3d_visualization.ipynb

Defines the graben model structure, imports input data, maps surfaces to stacks, and sets fault relationships.

```python
data_path = 'https://raw.githubusercontent.com/cgre-aachen/gempy_data/master/'
path_to_data = data_path + "/data/input_data/lisa_models/"

geo_model = gp.create_geomodel(
    project_name="Graben",
    extent=[0, 2000, 0, 2000, 0, 1600],
    resolution=[50, 50, 50],
    refinement=6,
    importer_helper=gp.data.ImporterHelper(
        path_to_orientations=path_to_data + "foliations7.csv",
        path_to_surface_points=path_to_data + "interfaces7.csv",
        hash_surface_points="8c72af50fc56389b620c6458a6af23915b121b5e655b3ce179a790636dc529a5",
        hash_orientations="87cf30b08b5be03b38c5e6d288fa7bb8855263704efb62c7c3cd77673eaae96d"
    )
)

gp.map_stack_to_surfaces(
    gempy_model=geo_model,
    mapping_object={
        "Fault_1"     : 'Fault_1',
        "Fault_2"     : 'Fault_2',
        "Strat_Series": ('Sandstone', 'Siltstone', 'Shale', 'Sandstone_2', 'Schist', 'Gneiss')
    }
)

gp.set_is_fault(geo_model, ['Fault_1', 'Fault_2'])
```

--------------------------------

### Import Dependencies and Configure Environment

Source: https://docs.gempy.org/_downloads/efebcc512a2cf32b32c9f73b9822f2a9/Perth_basin.ipynb

Imports GemPy, GemPy Viewer, and Matplotlib, and sets the default figure size.

```python
import os

# Importing GemPy
import gempy as gp
import gempy_viewer as gpv

# Importing auxiliary libraries
import matplotlib

matplotlib.rcParams['figure.figsize'] = (20.0, 10.0)
```

--------------------------------

### Initialize RawArraysSolution from Engine Outputs

Source: https://docs.gempy.org/_modules/gempy_engine/core/data/raw_arrays_solution.html

Factory method to populate the solution container using octree levels and mesh data.

```python
@classmethod
    def from_gempy_engine_solutions(cls, octrees_output: list[OctreeLevel], meshes: list[DualContouringMesh],
                                    block_solution_type: BlockSolutionType) -> Union["RawArraysSolution", None]:
        raw_arrays_solution = cls()

        first_level_octree: OctreeLevel = octrees_output[0]
        stacks_output = first_level_octree.outputs
        collapsed_output: InterpOutput = stacks_output[-1]  # ! This is the scalar field. Usually we want the last one but not necessarily
        # ? DEP: last_octree_level: OctreeLevel = octrees_output[(-1)]

        raw_arrays_solution._set_scalar_field_at_surface_points(first_level_octree)

        # Region Blocks
        match block_solution_type:
            case cls.BlockSolutionType.OCTREE:
                _fill_block_solutions_with_octree_output(octrees_output, raw_arrays_solution)
                raw_arrays_solution.dense_ids = BackendTensor.t.to_numpy(collapsed_output.ids_block_octree_grid)
            case cls.BlockSolutionType.DENSE_GRID:
                _fill_block_solutions_with_dense_grid(stacks_output, raw_arrays_solution)
                raw_arrays_solution.dense_ids = BackendTensor.t.to_numpy(collapsed_output.ids_block_dense_grid)

        # Endregion

        # Region Grids

        # TODO: Make this more clever to account for the fact that we can have more than one scalar field
        raw_arrays_solution.geological_map = BackendTensor.t.to_numpy(collapsed_output.geological_map)
        raw_arrays_solution.sections = BackendTensor.t.to_numpy(collapsed_output.sections)
        raw_arrays_solution.custom = BackendTensor.t.to_numpy(collapsed_output.custom_grid_values)
        # End region

        # Region Meshes
        if meshes:
            raw_arrays_solution.vertices = [mesh.vertices for mesh in meshes]
            raw_arrays_solution.edges = [mesh.edges for mesh in meshes]

        # Endregion
        return raw_arrays_solution
```

--------------------------------

### Create GeoModel with ImporterHelper

Source: https://docs.gempy.org/_downloads/3208e45dad6676218bdfa5746078e216/a01_basics.ipynb

Initializes a GeoModel using ImporterHelper to load surface points and orientations from CSV files.

```python
data_path = 'https://raw.githubusercontent.com/cgre-aachen/gempy_data/master/'

geo_model = gp.create_geomodel(
    project_name='Tutorial_Basics',
    extent=[0, 2000, 0, 2000, 0, 750],
    refinement=6,
    importer_helper=gp.data.ImporterHelper(
        path_to_orientations=data_path + "/data/input_data/getting_started/simple_fault_model_orientations.csv",
        path_to_surface_points=data_path + "/data/input_data/getting_started/simple_fault_model_points.csv",
        hash_surface_points="4cdd54cd510cf345a583610585f2206a2936a05faaae05595b61febfc0191563",
        hash_orientations="7ba1de060fc8df668d411d0207a326bc94a6cdca9f5fe2ed511fd4db6b3f3526"
    )
)
```

--------------------------------

### Configure Stochastic Simulation Domains

Source: https://docs.gempy.org/_sources/tutorials/c_advanced/c03_kriging.rst.txt

Sets up domain groupings for stochastic simulation, including an anisotropic model configuration.

```Python
rock2_merged = (domain_keys[2], domain_keys[3])
rock1_merged = (domain_keys[4], domain_keys[5])
```

```Python
directional_model = gs.Gaussian(dim=3, var=4, len_scale=1000, anis=[0.05, 0.05], angles=(np.pi / 4, 0, 0))

simulation_configs = {
    rock2_merged: SimulationDomainConfig(model=gaussian_model, seed=1),
    rock1_merged: SimulationDomainConfig(
        model=directional_model,
        conditioned=False,
        srf_kwargs={'mean': 15},
        seed=2,
    ),
}
simulated_field = run_simulation(geo_model, conditioning_data, simulation_configs)
plot_property_field(geo_model, simulated_field)
```

--------------------------------

### Initialize Default StructuralFrame

Source: https://docs.gempy.org/_modules/gempy/core/data/structural_frame.html

Creates a StructuralFrame instance with a default formation and empty surface points and orientations.

```python
structural_frame = initialize_default_structure()
```

--------------------------------

### Initialize Geological Model and Structural Data

Source: https://docs.gempy.org/examples/real/Claudius.html

Initializes surface points, orientations, structural frames, and the geological model, including fault group configuration.

```python
surface_points_table = gp.data.SurfacePointsTable.from_arrays(
    x=surface_points['X'].values,
    y=surface_points['Y'].values,
    z=surface_points['Z'].values,
    names=surface_points['surface'].values
)

orientations_table = gp.data.OrientationsTable.from_arrays(
    x=orientations['X'].values,
    y=orientations['Y'].values,
    z=orientations['Z'].values,
    G_x=orientations['G_x'].values,
    G_y=orientations['G_y'].values,
    G_z=orientations['G_z'].values,
    names=orientations['surface'].values,
    name_id_map=surface_points_table.name_id_map  # ! Make sure that ids and names are shared
)

structural_frame = gp.data.StructuralFrame.from_data_tables(
    surface_points=surface_points_table,
    orientations=orientations_table
)

geo_model = gp.create_geomodel(
    project_name='Claudius',
    extent=[548800, 552500, 7816600, 7822000, -11010, -8400],
    resolution=[38, 55, 30],
    refinement=5,
    structural_frame=structural_frame
)

group_fault = gp.data.StructuralGroup(
    name='Fault1',
    elements=[geo_model.structural_frame.structural_elements.pop(-2)],
    structural_relation=gp.data.StackRelationType.FAULT,
    fault_relations=gp.data.FaultsRelationSpecialCase.OFFSET_ALL
)

geo_model.structural_frame.get_group_by_name("default_formation").elements.pop(-1)

# Insert the fault group into the structural frame:
geo_model.structural_frame.insert_group(0, group_fault)

gp.set_is_fault(geo_model, [geo_model.structural_frame.get_group_by_name('Fault1')])

print(geo_model)
```

--------------------------------

### Verifying ImporterHelper output

Source: https://docs.gempy.org/_sources/tutorials/b_fundamentals/a01_basics.rst.txt

Displays the hash verification results for imported surface points and orientations.

```none
Surface points hash:  4cdd54cd510cf345a583610585f2206a2936a05faaae05595b61febfc0191563
Orientations hash:  7ba1de060fc8df668d411d0207a326bc94a6cdca9f5fe2ed511fd4db6b3f3526
```

--------------------------------

### Configure and Compute Centered Grid

Source: https://docs.gempy.org/_downloads/548a81fce05be005e3a48dc221a0ec19/c03_grids.ipynb

Sets up a centered grid around specified coordinates and computes the model.

```python
centers = np.array([[1000, 1000, 750]])
gp.set_centered_grid(
    geo_model.grid,
    centers=centers,
    resolution=[10, 10, 20],
    radius=np.array([1000, 1000, 1000])
)
geo_model.grid.active_grids
gp.compute_model(geo_model)
```

--------------------------------

### Model Configuration Output

Source: https://docs.gempy.org/_sources/tutorials/b_fundamentals/e05_3d_visualization.rst.txt

Displays the hash verification output from the model configuration process.

```none
Surface points hash:  8c72af50fc56389b620c6458a6af23915b121b5e655b3ce179a790636dc529a5
Orientations hash:  87cf30b08b5be03b38c5e6d288fa7bb8855263704efb62c7c3cd77673eaae96d
```

--------------------------------

### Model computation output logs

Source: https://docs.gempy.org/tutorials/b_fundamentals/c03_grids.html

Console output showing hash verification and backend initialization status.

```text
Surface points hash:  4cdd54cd510cf345a583610585f2206a2936a05faaae05595b61febfc0191563
Orientations hash:  7ba1de060fc8df668d411d0207a326bc94a6cdca9f5fe2ed511fd4db6b3f3526
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
```

--------------------------------

### Generate Greenstone Model from Binary

Source: https://docs.gempy.org/_modules/gempy/API/examples_generator.html

Loads a pre-existing Greenstone model from a binary file and computes it using the NumPy backend.

```python
def _generate_greenstone_model(compute_model: bool) -> gp.data.GeoModel:
    test_dir = os.path.dirname(os.path.abspath(__file__))

    # Build the path relative to the test file location
    path = os.path.join(test_dir, '..', '..', 'examples', 'data', 'gempy_models', 'Greenstone.gempy')
    with open(path, 'rb') as f:
        binary_file = f.read()

    from gempy.modules.serialization.save_load import _load_model_from_bytes
    geo_model: gp.data.GeoModel = _load_model_from_bytes(binary_file)

    if compute_model:
        sol = gp.compute_model(
            gempy_model=geo_model,
            engine_config=gp.data.GemPyEngineConfig(
                backend=gp.data.AvailableBackends.numpy,
                dtype='float32'
            )
        )
    return geo_model
```

--------------------------------

### Generate Graben Model

Source: https://docs.gempy.org/_modules/gempy/API/examples_generator.html

Creates a graben model by importing surface points and orientations from remote CSV files and mapping stacks to surfaces.

```python
def _generate_graben_model(compute_model: bool) -> gp.data.GeoModel:
    # Data path is in root/examples/data
    # script_dir = os.path.dirname(os.path.abspath(__file__))
    # data_path = os.path.join(script_dir, '.../examples/')
    # n_model = 7
    # https: // github.com / gempy - project / gempy / blob / 279
    # bbe904283e16320c54d868fe74be873177cca / examples / data / input_data / lisa_models / interfaces7.csv
    # csv_ = data_path + "/data/input_data/lisa_models/foliations" + n_model + ".csv"

    data_path = 'https://raw.githubusercontent.com/cgre-aachen/gempy_data/master/'
    path_to_data = data_path + "/data/input_data/lisa_models/"

    geo_data: gp.data.GeoModel = gp.create_geomodel(
        project_name="Graben",
        extent=[0, 2000, 0, 2000, 0, 1600],
        resolution=[50, 50, 50],
        refinement=6,  # * For this model is better not to use octrees because we want to see what is happening in the scalar fields
        importer_helper=gp.data.ImporterHelper(
            path_to_orientations=path_to_data + "foliations7.csv",
            path_to_surface_points=path_to_data + "interfaces7.csv"
        )
    )

    gp.map_stack_to_surfaces(
        gempy_model=geo_data,
        mapping_object={
                "Fault_1"     : 'Fault_1', "Fault_2": 'Fault_2',
                "Strat_Series": ('Sandstone', 'Siltstone', 'Shale', 'Sandstone_2', 'Schist', 'Gneiss')
        },
    )

    gp.set_is_fault(geo_data, ['Fault_1', 'Fault_2'])
    if compute_model:
        sol = gp.compute_model(gempy_model=geo_data)

    return geo_data
```

--------------------------------

### Configure and Run Kriging

Source: https://docs.gempy.org/_downloads/3514efe2729d048dd7d1e3bb43011738/c03_kriging.ipynb

Defines Gaussian and exponential models for specific geological domains and executes the kriging process.

```python
gaussian_model = gs.Gaussian(dim=3, var=4, len_scale=400, nugget=0.1)
exponential_model = gs.Exponential(dim=3, var=4, len_scale=400)

domain_configs = {
    rock3_merged: KrigingDomainConfig(model=gaussian_model),
    domain_keys[2]: KrigingDomainConfig(model=exponential_model),
    domain_keys[6]: KrigingDomainConfig(
        model=gaussian_model,
        krige_class=gs.krige.Simple,
        krige_kwargs={'mean': 15},
    ),
}
field = run_kriging(geo_model, conditioning_data, domain_configs)
```

--------------------------------

### Model Execution Output

Source: https://docs.gempy.org/_sources/examples/geometries/h08_more_examples.rst.txt

Displays the console output generated during the model creation process, including backend and device information.

```none
Setting Backend To: AvailableBackends.PYTORCH
GPU enabled. Using device: cuda
GPU device count: 1
Current GPU device: 0
Chunking done: 19 chunks
Chunking done: 21 chunks
Chunking done: 10 chunks
```
Tokens:
Raw