loopstructural

name	loopstructural
description	Build 3D geological models with implicit surfaces, faults, folds, and stratigraphic constraints from structural geology data. Use when Claude needs to: (1) Build 3D geological models from structural data, (2) Model fault networks and displacements, (3) Create folded geology representations, (4) Interpolate geological surfaces, (5) Export models to VTK for visualization, (6) Perform uncertainty analysis on geological models, (7) Evaluate model values on grids.
version	1.0.0
author	Geoscience Skills
license	MIT
tags	["Geological Modelling","3D","Faults","Folds","Structural Geology"]
dependencies	["LoopStructural>=1.5.0","numpy","pandas"]
complements	["gemgis","gempy","pyvista"]
workflow_role	modelling

LoopStructural - 3D Geological Modelling

Quick Reference

from LoopStructural import GeologicalModel
from LoopStructural.visualisation import LavaVuModelViewer
import pandas as pd
import numpy as np

# Create model
model = GeologicalModel(origin=[0, 0, -1000], maximum=[10000, 10000, 0])

# Add data
model.data = pd.DataFrame({
    'X': [5000], 'Y': [5000], 'Z': [-500],
    'feature_name': ['strat'], 'val': [0]
})

# Build and visualize
model.create_and_add_foliation('strat', interpolatortype='PLI')
model.update()

viewer = LavaVuModelViewer(model)
viewer.add_isosurface(model['strat'], isovalue=0)
viewer.interactive()

Key Classes

Class	Purpose
GeologicalModel	Main model container - holds features and data
ProcessInputData	Data preparation and validation
StructuralFrame	Coordinate system for fold modelling
FaultSegment	Individual fault surface with displacement

Essential Operations

Build Stratigraphic Model

model = GeologicalModel([0, 0, -1000], [10000, 10000, 0])
model.data = pd.DataFrame({
    'X': [5000, 5000, 5000],
    'Y': [5000, 5000, 5000],
    'Z': [-200, -500, -800],
    'feature_name': ['strat', 'strat', 'strat'],
    'val': [0, 1, 2]  # Different unit values
})
model.create_and_add_foliation('strat', interpolatortype='PLI', nelements=1000)
model.update()

Add Orientation Data

# Structural measurements (strike/dip)
orientations = pd.DataFrame({
    'X': [2000, 5000, 8000],
    'Y': [5000, 5000, 5000],
    'Z': [-100, -100, -100],
    'feature_name': ['strat', 'strat', 'strat'],
    'strike': [90, 90, 90],
    'dip': [30, 30, 30],
    'val': [np.nan, np.nan, np.nan]
})
model.data = pd.concat([interfaces, orientations])

Model with Fault

# Define fault data
fault_data = pd.DataFrame({
    'X': [5000, 5000], 'Y': [2000, 8000], 'Z': [-500, -500],
    'feature_name': ['fault1', 'fault1'],
    'val': [0, 0], 'coord': [0, 0]
})
fault_orient = pd.DataFrame({
    'X': [5000], 'Y': [5000], 'Z': [-500],
    'feature_name': ['fault1'],
    'gx': [1], 'gy': [0], 'gz': [0]  # Fault normal
})

model.data = pd.concat([fault_data, fault_orient, strat_data])
model.create_and_add_fault('fault1', displacement=200)  # Add fault first
model.create_and_add_foliation('strat')  # Stratigraphy affected by fault
model.update()

Folded Geology

# Generate fold interface data
x = np.linspace(0, 10000, 20)
z = -500 + 200 * np.sin(2 * np.pi * x / 5000)
fold_data = pd.DataFrame({
    'X': x, 'Y': np.ones(20) * 5000, 'Z': z,
    'feature_name': 'strat', 'val': 0
})

model.data = fold_data
model.create_and_add_fold_frame('fold_frame')
model.create_and_add_folded_foliation('strat', fold_frame='fold_frame')
model.update()

Evaluate on Grid

# Create evaluation grid
x = np.linspace(0, 10000, 100)
y = np.linspace(0, 10000, 100)
z = np.linspace(-1000, 0, 50)
xx, yy, zz = np.meshgrid(x, y, z)
points = np.column_stack([xx.ravel(), yy.ravel(), zz.ravel()])

# Evaluate stratigraphy
values = model['strat'].evaluate_value(points)
values_3d = values.reshape(xx.shape)

Export to VTK

import pyvista as pv

# Export isosurface
isosurface = model['strat'].isosurface(isovalue=0)
isosurface.save('horizon.vtk')

# Export regular grid
surfaces = model.regular_grid(nsteps=[50, 50, 50])
grid = pv.StructuredGrid(*surfaces)
grid.save('geological_model.vtk')

Data Requirements

Data Type	Required Columns	Description
Interface	X, Y, Z, feature_name, val	Points on geological surfaces
Orientation	X, Y, Z, feature_name, strike, dip	Structural measurements
Gradient	X, Y, Z, feature_name, gx, gy, gz	Normal vectors to surfaces
Fault	X, Y, Z, feature_name, val, coord	Fault surface points

When to Use vs Alternatives

Scenario	Recommendation
Complex fold modelling with structural frames	LoopStructural - best-in-class fold support
Simple layered geology with faults	GemPy - simpler API, faster setup
Fault network with displacement fields	LoopStructural - explicit displacement control
Commercial subsurface modelling	SKUA-GOCAD - industry standard, proprietary
Uncertainty analysis on geological models	LoopStructural - built-in support

Choose LoopStructural when: Your geology involves folds, complex fault networks with known displacements, or you need structural frame-based modelling. It excels at reproducing realistic fold geometries using fold constraints.

Avoid LoopStructural when: You have simple layered geology (GemPy is easier), or you need a GUI-driven workflow (use commercial tools).

Common Workflows

Build faulted geological model from structural data

• Prepare data as DataFrame with columns: X, Y, Z, feature_name, val (and strike/dip or gx/gy/gz)
• Create GeologicalModel with origin and maximum bounds
• Assign data to model.data
• Add faults first with model.create_and_add_fault() and set displacement
• Add stratigraphy with model.create_and_add_foliation()
• Call model.update() to build the model
• Evaluate on grid with model['feature'].evaluate_value(points)
• Visualize with LavaVuModelViewer or export isosurfaces to VTK
• Validate cross-sections against known geology

Modelling Tips

1. Add faults before stratigraphy - Order matters for geological relationships
2. Use orientation data - Significantly improves model quality
3. Check data consistency - Conflicting data causes interpolation issues
4. Start simple - Add complexity incrementally
5. Validate with sections - Compare cross-sections to known geology

References

• Geological Features - Feature types and when to use them
• Interpolators - Interpolation methods and parameters

Scripts

• scripts/build_model.py - Build a basic geological model from CSV data