# loop3d/loopstructural architecture

> Architecture diagram of the GitHub repository loop3d/loopstructural, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/loop3d/loopstructural
- Repository: https://github.com/loop3d/loopstructural

## Overview

##### Project type and purpose
- LoopStructural is an open-source Python library for 3D implicit geological modelling.
- It provides: data loading, datatype abstractions, interpolation algorithms, geological model building, export to various formats, and interactive visualisation.

##### File structure
Top-level packages under LoopStructural/ represent the core subsystems:
- datasets: data loaders and example data
- interpolators: various interpolation engines (finite difference, P1/P2, RBF, discrete folds, plus Cython helpers)
- modelling: core geological model object plus feature builders (faults, folds, intrusions) and input processors
- export: exporters for vtk, geoh5, omf, gocad, csv, obj
- visualisation: wrappers around pyvista/trame for interactive views
- utils: shared utilities (maths, linalg, logging, config, exceptions)
Ancillary directories:
- tests: unit & integration tests
- docs: Sphinx source + Docker/CI scripts
- examples: usage scripts demonstrating workflows
- CI/CD: GitHub Actions workflows, conda recipes, PyPI publish scripts

##### README for additional insights
- Lists optional dependencies (pyvista, geoh5py, mira-omf, pyevtk, etc.) that plug into export/visualisation subsystems
- Quickstart shows API flow: load data → instantiate GeologicalModel → add feature → update → evaluate → plot

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Input Layer
    subgraph "Data Input" 
        direction TB
        DataInput["Data Input (datasets)"]:::io
        ExampleData["Example Data"]:::io
    end

    %% Datatypes Layer
    subgraph "Datatypes (Geometry Primitives)"
        direction TB
        Datatypes["Datatypes"]:::core
    end

    %% Core Modelling Layer
    subgraph "GeologicalModel Core"
        direction TB
        Core["GeologicalModel Core"]:::core
    end

    %% Feature Builders Layer
    subgraph "Feature Builders"
        direction TB
        FaultBuilder["_fault_builder"]:::core
        FoldBuilder["_folded_feature_builder"]:::core
        IntrusionBuilder["_intrusion_builder"]:::core
        FrameBuilder["_structural_frame_builder"]:::core
    end

    %% Intrusion Subsystem
    subgraph "Intrusion Features"
        direction TB
        IntrusionCore["intrusion_builder"]:::core
        IntrusionFrame["intrusion_frame_builder"]:::core
        IntrusionFeature["intrusion_feature"]:::core
    end

    %% Interpolator Engine Layer
    subgraph "Interpolator Engine"
        direction TB
        InterpAPI["_api"]:::core
        InterpFactory["_interpolator_factory"]:::core
        InterpBuilders["_builders"]:::core
        Cython["_cython (Cython modules)"]:::core
        Supports["supports"]:::core
    end

    %% Exporters Layer
    subgraph "Exporters"
        direction TB
        Exporters["exporters"]:::io
        FileFormats["file_formats"]:::io
        GeoH5["geoh5"]:::io
        Gocad["gocad"]:::io
        Omf["omf_wrapper"]:::io
    end

    %% Visualisation Layer
    subgraph "Visualisation"
        direction TB
        Visualization["Visualisation"]:::io
    end

    %% Utilities Layer
    subgraph "Utilities"
        direction TB
        Config["config"]:::util
        Logging["logging"]:::util
        Maths["maths"]:::util
        Linalg["linalg"]:::util
        Exceptions["exceptions"]:::util
        Helper["helper"]:::util
        Observer["observer"]:::util
    end

    %% Tests, Examples, CI/CD
    subgraph "Support & Dev"
        direction TB
        Tests["Tests"]:::external
        Examples["Examples"]:::external
        CICD["CI/CD & Packaging"]:::external
    end

    %% External Dependencies
    External["External Dependencies\n(NumPy, pandas, pyvista,\ngeoh5py, mira-omf)"]:::external

    %% Data Flows
    DataInput -->|"load data\n→ DataFrame\n→ Geometry"| Datatypes
    Datatypes -->|"initialize bounding box\n& features"| Core
    Core <-->|"use builders"| FaultBuilder
    Core <-->|"use builders"| FoldBuilder
    Core <-->|"use builders"| IntrusionBuilder
    Core <-->|"use builders"| FrameBuilder
    IntrusionCore -->|"build intrusion"| Core
    Core <-->|"factory selects strategy"| InterpFactory
    InterpAPI --> InterpFactory
    InterpBuilders --> InterpFactory
    Cython --> InterpFactory
    Supports --> InterpFactory
    Core -->|"serialize model"| Exporters
    Core -->|"serialize formats"| FileFormats
    Core -->|"export via plugin"| GeoH5
    Core --> Gocad
    Core --> Omf
    Core -->|"render model"| Visualization
    Core -->|"util functions"| Config
    Core --> Logging
    Core --> Maths
    Core --> Linalg
    Core --> Exceptions
    Core --> Helper
    Core --> Observer
    Tests --> DataInput
    Tests --> Datatypes
    Tests --> Core
    Tests --> Exporters
    Examples --> DataInput
    Examples --> Core
    CICD --> Tests
    CICD --> Examples
    CICD --> Exporters
    CICD --> Visualization
    External --> Exporters
    External --> Visualization

    %% Click Events
    click DataInput "https://github.com/loop3d/loopstructural/tree/master/LoopStructural/datasets/"
    click ExampleData "https://github.com/loop3d/loopstructural/tree/master/LoopStructural/datasets/data/"
    click Datatypes "https://github.com/loop3d/loopstructural/tree/master/LoopStructural/datatypes/"
    click Core "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/core/geological_model.py"
    click FaultBuilder "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/features/builders/_fault_builder.py"
    click FoldBuilder "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/features/builders/_folded_feature_builder.py"
    click IntrusionBuilder "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/features/builders/_intrusion_builder.py"
    click FrameBuilder "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/features/builders/_structural_frame_builder.py"
    click IntrusionCore "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/intrusions/intrusion_builder.py"
    click IntrusionFrame "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/intrusions/intrusion_frame_builder.py"
    click IntrusionFeature "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/modelling/intrusions/intrusion_feature.py"
    click InterpAPI "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/interpolators/_api.py"
    click InterpFactory "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/interpolators/_interpolator_factory.py"
    click Cython "https://github.com/loop3d/loopstructural/tree/master/LoopStructural/interpolators/_cython/"
    click Supports "https://github.com/loop3d/loopstructural/tree/master/LoopStructural/interpolators/supports/"
    click Exporters "https://github.com/loop3d/loopstructural/tree/master/LoopStructural/export/"
    click FileFormats "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/export/file_formats.py"
    click GeoH5 "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/export/geoh5.py"
    click Gocad "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/export/gocad.py"
    click Omf "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/export/omf_wrapper.py"
    click Visualization "https://github.com/loop3d/loopstructural/tree/master/LoopStructural/visualisation/"
    click Config "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/utils/config.py"
    click Logging "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/utils/logging.py"
    click Maths "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/utils/maths.py"
    click Linalg "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/utils/linalg.py"
    click Exceptions "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/utils/exceptions.py"
    click Helper "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/utils/helper.py"
    click Observer "https://github.com/loop3d/loopstructural/blob/master/LoopStructural/utils/observer.py"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef io fill:#D5F5E3,stroke:#145A32,color:#0B5345
    classDef util fill:#FCF3CF,stroke:#7D6608,color:#6E2C00
    classDef external fill:#F5EEF8,stroke:#6C3483,color:#512E5F
```
