Loopstructural

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, featurename, val | Points on geological surfaces | | Orientation | X, Y, Z, featurename, strike, dip | Structural measurements | | Gradient | X, Y, Z, featurename, gx, gy, gz | Normal vectors to surfaces | | Fault | X, Y, Z, featurename, 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](references/geological_features.md) - Feature types and when to use them
• [Interpolators](references/interpolators.md) - Interpolation methods and parameters

Scripts

• [scripts/buildmodel.py](scripts/buildmodel.py) - Build a basic geological model from CSV data

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SteadfastAsArt
• Source: SteadfastAsArt/geoscience-skills
• License: MIT

Install and usage instructions live in the source repository linked above.