Data And Structure

GemPy data and structure

Use this sub-skill when a request concerns input data or geological organization, before model interpolation. A GemPy model stores input in this hierarchy:

GeoModel -> StructuralFrame -> StructuralGroup -> StructuralElement -> SurfacePointsTable + OrientationsTable.

A group is an ordered series/stack (or a fault group); an element is one named surface or fault. The frame's group order is geological structure, not merely a container order. Keep the same element names/IDs in surface points and orientations, and validate before computing.

Route and boundaries

• Construct or compute a model, map a stack to surfaces, or run interpolation: use modeling.
• Configure regular/custom/section/topography grids or plot input/results: use grids-and-visualization.
• Save/load JSON or .gempy, or use advanced mesh/plugin workflows: use serialization-and-advanced.
• Install GemPy or diagnose missing pandas/viewer/engine dependencies: use environment-and-troubleshooting.

The public data API is available through gempy as gp and gp.data. The recipes below use only caller-provided arrays, DataFrames, or file paths; they do not require GemPy's source checkout or example data.

Core workflow

1. Build SurfacePointsTable and OrientationsTable from equal-length numeric arrays, usually with from_arrays.
2. Use one explicit name_id_map for both tables when IDs must be controlled; otherwise let GemPy generate an opaque ID per distinct name.
3. Build a frame with StructuralFrame.from_data_tables(surface_points, orientations) or start with StructuralFrame.initialize_default_structure() for incremental GeoModel construction.
4. Inspect frame.elements_names, element_id_name_map, counts, and the table .df/.data before mapping or computing.
5. Mutate through gp.add_*/gp.modify_*, or replace a frame table through the model setter. Re-run model.validate() and then route computation to modeling.

A minimal direct construction is:

import numpy as np
import gempy as gp

sp = gp.data.SurfacePointsTable.from_arrays(
    x=np.array([0., 1., 0.]), y=np.array([0., 0., 1.]), z=np.array([0., 0., 0.]),
    names="Layer",
)
ori = gp.data.OrientationsTable.from_arrays(
    x=np.array([0.5]), y=np.array([0.5]), z=np.array([0.]),
    G_x=np.array([0.]), G_y=np.array([0.]), G_z=np.array([1.]),
    names=["Layer"], name_id_map=sp.name_id_map,
)
frame = gp.data.StructuralFrame.from_data_tables(sp, ori)

from_data_tables creates one default erosional group and an element for each surface-point ID. An element with no matching orientation receives an empty orientation table; this is allowed as a data structure, but may be insufficient for later model validation/computation.

Input/mutation recipes

Add to an existing model

# model must already contain an element named "Layer"
gp.add_surface_points(
    model, x=[2., 3.], y=[0., 0.], z=[1., 1.],
    elements_names=["Layer", "Layer"],
)
gp.add_orientations(
    model, x=[2.], y=[0.], z=[1.], elements_names=["Layer"],
    pole_vector=np.array([[0., 0., 1.]]),
)

add_surface_points and add_orientations append rows to the named element and return the model's StructuralFrame. All coordinate/name/pole/nugget sequences must have the same length. An unknown element name raises ValueError; neither add_* creates a new element. Create an element and put it in a group first when adding a new surface.

add_orientations accepts a representation in one of these forms:

• pole_vector: an (n, 3) array of gradient components [G_x, G_y, G_z].
• orientation: an (n, 3) array [azimuth_degrees, dip_degrees, polarity].

Pass one representation. If both are supplied, the current implementation converts orientation and ignores the supplied pole vector. A missing representation raises ValueError. A missing nugget uses GemPy's current defaults (0.01 for orientations and 0.00002 for surface points).

Modify existing rows

# Target by element name, or use a global row index/slice.
gp.modify_surface_points(model, elements_names=["Layer"], Z=np.array([1., 1., 2.]))
gp.modify_surface_points(model, slice=0, X=0.25, nugget=0.00002)
gp.modify_orientations(
    model, slice=slice(0, 1),
    G_x=np.array([0.0]), G_y=np.array([0.0]), G_z=np.array([1.0]),
)

modify_surface_points accepts X, Y, Z, and nugget; modify_orientations accepts those coordinates plus G_x, G_y, G_z, and nugget. Scalars broadcast through NumPy structured-array assignment; arrays must match the selected row count. Surface-point selection cannot specify both elements_names and slice. These functions update the model through the frame table setters; returned value is the updated StructuralFrame.

The current inspected GemPy release exposes angular keyword handling in modify_orientations, but its implementation raises an unpacking ValueError when azimuth, dip, or polarity is used. Treat angular modification as a known compatibility gap: convert angles yourself and write G_x/G_y/G_z, or recreate the orientation rows with add_orientations. Do not claim angular modification works unless a later package version is verified.