LoopStructural

The loop-interpolation package provides core interpolation utilities used throughout the LoopStructural workspace. It includes several types of interpolators for geological modelling:

• Discrete Interpolators: Supports piecewise linear (P1) and piecewise quadratic (P2) interpolation.
• Finite Difference Interpolators: Used for calculating derivatives or working with grid-based data.
• Fold Interpolator: A specialized interpolator used across various LoopStructural workspace packages.

The loop-common package provides shared utilities used across the LoopStructural workspace. It is primarily used for handling geometry, data structures, and mathematical operations required by other LoopStructural packages.

Key capabilities include:

• Bounding box geometry helpers: Utilities for managing and calculating spatial bounds.
• Mesh and grid support types: Shared type definitions and structures for handling meshes and grids.
• Shared math and logging utilities: Common mathematical functions and standardized logging implementations used throughout the ecosystem.

LoopStructural 2.0 is a staged rebuild of the modelling core. The project is transitioning towards a graph-based backend for model storage while maintaining the existing GeologicalModel API for evaluation.

Key architectural changes include:

• Model Definition: Moving towards a YAML/JSON format that captures parameter choices and data references.
• Decoupled Interpolation: Extracting interpolation code to be usable independently of the LoopStructural framework.
• Workspace Integration: loopresources and map2loop are integrated as uv-workspace packages within this repository due to their tight coupling with LoopStructural inputs.
• QGIS Plugin: The QGIS plugin remains in a separate repository and acts as a consumer of published LoopStructural releases to maintain independent release cadences.

LoopStructural supports advanced geological modelling workflows including:

• Direct Model Building: Constructing models directly from raw geological map data using the ProcessInputData class.
• Observability: Inspecting internal processes and model construction steps via LoopStructural's logging output.
• Constraint Control: Adjusting how strongly individual data points constrain the interpolation process.
• Method Comparison: Comparing LoopStructural's mesh-based interpolators against standard scattered-data interpolation methods.

Implicit geological modelling represents geological objects using a mathematical function $f(x,y,z)$ where the function returns the distance to the geological feature. The geometry is approximated by using observations of the location and shape of the objects.

In LoopStructural, you can constrain this function using:

• Value constraints: Specifying the value of the function at specific locations (e.g., $f(x,y,z) = 0$ at a fault trace).
• Normal (Gradient) constraints: Specifying the orientation (strike/dip) and the gradient norm (how quickly the value changes) to further constrain the geometry.

The standard workflow in LoopStructural follows these steps:

1. Data Preparation: Convert a table of X, Y, and Z observations into a GeologicalModel object.
2. Surface Building: Build implicit surfaces from the observation data.
3. Structural Integration: Combine multiple stratigraphic groups, accounting for unconformities and faults.
4. Output: Visualise the resulting model and export the data.

This basic workflow serves as the foundation for more advanced examples in the repository.

Interpolators in LoopStructural are used to construct 2D or 3D scalar fields from geological constraints (such as contacts, folds, or orientations).

All interpolators must inherit from the GeologicalInterpolator base class. This class serves as the entry point for all interpolation logic and provides methods for accessing constraints. The interpolation module also includes supporting structures such as meshes, grids, and operators.

In recent versions, the BoundingBox API has been unified with loop_common.

• Coordinates: origin and maximum are always expressed in world coordinates.
• Local Frame: To define a near-zero interpolation frame, use set_local_transform(local_origin=...).
• Projection: The responsibility for converting between world and local frames has moved to the interpolator/support layer. GeologicalInterpolator.bounding_box handles projecting constraint or query points via project, reproject, project_vectors, or reproject_vectors.

The core of a LoopStructural workflow involves the relationship between a model and its features:

• GeologicalModel: The top-level container for the entire geological environment.
• GeologicalFeature: Represents a specific geological phenomenon (e.g., a stratigraphic sequence, fault, foliation, unconformity, or intrusion). Features can be evaluated for specific values or gradients.
• GeologicalFeatureBuilder: The mechanism used to create a GeologicalFeature. The builder manages the assembly of interpolation constraints and monitors whether the underlying data or constraints have changed to determine if the interpolator needs to be re-executed.