# mtuqorg/mtuq architecture

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

- Interactive diagram: https://gitdiagram.com/mtuqorg/mtuq
- Repository: https://github.com/mtuqorg/mtuq

## Overview

##### Project Type and Purpose
- mtuq is an open-source Python library/program for moment‐tensor estimation and uncertainty quantification from broadband seismic data.
- It exposes a CLI API (console entry points) and a Python API. It integrates with external Green’s-function solvers (AxiSEM, SPECFEM3D, FK, Syngine), performs grid searches (with MPI support), computes misfits (C-accelerated), and provides visualization utilities.

##### Main Architectural Components
a. **User Interface / Entry Points**
- CLI scripts (console entry points defined in setup.py)
- Python API (import mtuq)
b. **Core Processing Modules**
- `mtuq.dataset` & `mtuq.event` – ingest and represent seismic observations
- `mtuq.io` – I/O clients for local (SAC, NetCDF) and remote (Syngine) Green’s functions
- `mtuq.greens_tensor` – abstractions for different solver outputs
- `mtuq.grid` & `mtuq.grid_search` – parameter‐space grids and search orchestration (MPI‐aware)
- `mtuq.misfit` – waveform and polarity misfit calculations (pure Python + C extension)
- `mtuq.process_data` & `mtuq.station` – preprocessing (filtering, trimming)
- `mtuq.graphics` – plotting backends (Matplotlib, PyGMT, GMT)—user gallery and figure customization
c. **External Dependencies & Services**
- AxiSEM, FK, SPECFEM3D solvers (read via NetCDF/SAC clients)
- IRIS Syngine web service (HTTP API)
- MPI runtime (for parallel grid_search)
- Matplotlib, PyGMT, GMT for plotting
- C compiler (for building misfit C extensions)
d. **Support Infrastructure**
- `data/` – example datasets, Green’s‐tensor caches, test fixtures
- `docs/` – Sphinx documentation
- `tests/` – unit and integration tests, CI workflows

##### Relationships and Data Flow
1. **User / Script**
- Invokes CLI or imports Python API
2. **Data Ingestion**
- `mtuq.dataset` & `mtuq.io.readers` read seismic traces
- `mtuq.io.clients` fetch or read Green’s‐function data
3. **Preprocessing**
- `mtuq.process_data` filters and windows data
4. **Grid Search Coordination**
- `mtuq.grid_search.grid_search` distributes parameter grid (MPI if available)
- For each grid cell:
– Build candidate source parameters via `mtuq.grid.*`
– Fetch precomputed or on‐the‐fly Green’s functions (`mtuq.greens_tensor`)
– Compute misfit (`mtuq.misfit.waveform.level*`, C extension)
5. **Post‐processing & Uncertainty Quantification**
- Aggregate misfits, build likelihood surfaces
6. **Visualization & Output**
- `mtuq.graphics` renders plots (beachball, lune, depth, force, waveforms)
- Results saved as files or returned to calling code

##### Architectural Patterns & Design Principles
- **Modular layering**: clear separation between data I/O, processing, computation (grid, misfit), and visualization.
- **Plugin/adapter pattern**: `io.clients` and `greens_tensor` support multiple solver backends via a common interface.
- **MPI transparency**: grid_search automatically detects MPI environment and parallelizes without code changes.
- **C‐accelerated hot paths**: misfit computations leverage C extensions for performance, wrapped in Python.
- **Extensibility**: new solvers, misfit metrics, or visualization backends can be added by implementing the same interfaces.

##### Detail Level
- Essential modules but group low‐level utilities under “Utilities & Helpers.”
- Don’t overcrowd: focus on data‐flow and module interactions, not every single Python file.
- How configuration files (env.yaml, pyproject.toml, setup.py) feed into the build/deploy process if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface" 
        UI_User["User"]:::user
        CLI["CLI Entry Points\n(setup.py)"]:::user
        PyAPI["Python API\n(mtuq/__init__.py)"]:::user
    end

    %% Data Ingestion
    subgraph "Data Ingestion" 
        DS["mtuq.dataset"]:::python
        EV["mtuq.event"]:::python
        subgraph "Readers"
            SAC["SAC Reader"]:::python
            PK["Pickle Reader"]:::python
        end
        subgraph "Clients"
            AXC["AxiSEM_NetCDF Client"]:::python
            CPS_C["CPS_SAC Client"]:::python
            FK_C["FK_SAC Client"]:::python
            SPECFEM3D_SAC_C["SPECFEM3D_SAC Client"]:::python
            SPECFEM3D_SGT_C["SPECFEM3D_SGT Client"]:::python
            SC["seiscloud Client"]:::python
            SYNC["syngine Client"]:::python
        end
    end

    %% Preprocessing
    subgraph "Preprocessing"
        PD["mtuq.process_data"]:::python
        ST["mtuq.station"]:::python
    end

    %% Grid Search & Structures
    subgraph "Grid Search Engine"
        subgraph "Grid Structures"
            GBASE["grid/base"]:::python
            GFORCE["grid/force"]:::python
            GMOM["grid/moment_tensor"]:::python
        end
        GS["mtuq.grid_search"]:::python
        MPI["MPI Runtime"]:::external
    end

    %% Green's Functions
    subgraph "Green’s-Function Abstractions"
        GBASE_T["base"]:::python
        GAX["AxiSEM"]:::python
        GCPS["CPS"]:::python
        GFK["FK"]:::python
        GSPE["SPECFEM3D"]:::python
        GSY["syngine"]:::python
    end

    %% Misfit Computation
    subgraph "Misfit Engine"
        MPOL["polarity"]:::python
        subgraph "Waveform Misfit"
            L0["level0"]:::python
            L1["level1"]:::python
            L2["level2"]:::python
            STATS["_stats"]:::python
            CEXT["c_ext_L2.c"]:::cext
        end
    end

    %% Aggregator
    AGG["Aggregator / Likelihood Surface"]:::python

    %% Visualization
    subgraph "Visualization"
        MPL["Matplotlib Backend"]:::python
        PGMT["PyGMT Backend"]:::python
        GMT_["GMT Backend"]:::python
        BB["beachball"]:::python
        WF["waveforms"]:::python
        ATTR["attrs"]:::python
        ANNOT["annotations"]:::python
        subgraph "UQ Plots"
            UQ_DEPTH["depth"]:::python
            UQ_LUNE["lune"]:::python
            UQ_FORCE["force"]:::python
            UQ_HYP["hypocenter"]:::python
            UQ_OMEGA["omega"]:::python
            UQ_VW["vw"]:::python
        end
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        WAVE["mtuq.wavelet"]:::python
        MATH["util/math"]:::python
        SIG["util/signal"]:::python
        UBB["util/beachball"]:::python
        CAP["util/cap"]:::python
        GALL["util/gallery"]:::python
        USY["util/syngine"]:::python
    end

    %% External Dependencies
    subgraph "External Dependencies"
        AXI_EXT["AxiSEM Solver"]:::external
        FK_EXT["FK Solver"]:::external
        SPECFEM3D_EXT["SPECFEM3D Solver"]:::external
        SYNG_SERV["IRIS Syngine"]:::external
        MPL_LIB["Matplotlib"]:::external
        PGMT_LIB["PyGMT"]:::external
        GMT_LIB["GMT"]:::external
        CC["C Compiler"]:::external
    end

    %% Support Infrastructure
    subgraph "Support Infrastructure"
        DATA_DIR["data/"]:::external
        DOCS["docs/"]:::external
        TESTS["tests/"]:::external
    end

    %% Connections
    UI_User --> CLI
    UI_User --> PyAPI

    CLI --> DS
    CLI --> EV
    CLI --> SAC
    CLI --> PK
    CLI --> AXC
    CLI --> CPS_C
    CLI --> FK_C
    CLI --> SPECFEM3D_SAC_C
    CLI --> SPECFEM3D_SGT_C
    CLI --> SC
    CLI --> SYNC

    PyAPI --> DS
    PyAPI --> EV
    PyAPI --> SAC
    PyAPI --> PK
    PyAPI --> AXC
    PyAPI --> CPS_C
    PyAPI --> FK_C
    PyAPI --> SPECFEM3D_SAC_C
    PyAPI --> SPECFEM3D_SGT_C
    PyAPI --> SC
    PyAPI --> SYNC

    DS --> PD
    EV --> PD
    SAC --> PD
    PK --> PD
    AXC --> PD
    CPS_C --> PD
    FK_C --> PD
    SPECFEM3D_SAC_C --> PD
    SPECFEM3D_SGT_C --> PD
    SC --> PD
    SYNC --> PD

    PD --> ST
    ST --> GS

    GS --> GBASE
    GS --> GFORCE
    GS --> GMOM
    GS --> MPI
    GS --> GBASE_T
    GS --> GAX
    GS --> GCPS
    GS --> GFK
    GS --> GSPE
    GS --> GSY

    GAX --> AXI_EXT
    GCPS --> FK_EXT
    GFK --> FK_EXT
    GSPE --> SPECFEM3D_EXT
    GSY --> SYNG_SERV

    GS --> MPOL
    GS --> L0
    GS --> L1
    GS --> L2
    GS --> STATS

    L2 --> CEXT
    CEXT --> CC

    MPOL --> AGG
    L0 --> AGG
    L1 --> AGG
    L2 --> AGG

    AGG --> MPL
    AGG --> PGMT
    AGG --> GMT_
    AGG --> BB
    AGG --> WF
    AGG --> ATTR
    AGG --> ANNOT
    AGG --> UQ_DEPTH
    AGG --> UQ_LUNE
    AGG --> UQ_FORCE
    AGG --> UQ_HYP
    AGG --> UQ_OMEGA
    AGG --> UQ_VW

    MPL --> MPL_LIB
    PGMT --> PGMT_LIB
    GMT_ --> GMT_LIB

    AGG --> UI_User

    %% Utilities flows
    PD --> WAVE
    MPOL --> SIG
    MPOL --> MATH
    BB --> UBB
    AGG --> CAP
    AGG --> GALL
    SYNC --> USY

    %% Click Events
    click CLI "https://github.com/mtuqorg/mtuq/blob/master/setup.py"
    click PyAPI "https://github.com/mtuqorg/mtuq/blob/master/mtuq/__init__.py"
    click DS "https://github.com/mtuqorg/mtuq/blob/master/mtuq/dataset.py"
    click EV "https://github.com/mtuqorg/mtuq/blob/master/mtuq/event.py"
    click SAC "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/readers/SAC.py"
    click PK "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/readers/_pickle.py"
    click AXC "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/clients/AxiSEM_NetCDF.py"
    click CPS_C "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/clients/CPS_SAC.py"
    click FK_C "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/clients/FK_SAC.py"
    click SPECFEM3D_SAC_C "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/clients/SPECFEM3D_SAC.py"
    click SPECFEM3D_SGT_C "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/clients/SPECFEM3D_SGT.py"
    click SC "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/clients/seiscloud.py"
    click SYNC "https://github.com/mtuqorg/mtuq/blob/master/mtuq/io/clients/syngine.py"
    click GBASE "https://github.com/mtuqorg/mtuq/blob/master/mtuq/greens_tensor/base.py"
    click GAX "https://github.com/mtuqorg/mtuq/blob/master/mtuq/greens_tensor/AxiSEM.py"
    click GCPS "https://github.com/mtuqorg/mtuq/blob/master/mtuq/greens_tensor/CPS.py"
    click GFK "https://github.com/mtuqorg/mtuq/blob/master/mtuq/greens_tensor/FK.py"
    click GSPE "https://github.com/mtuqorg/mtuq/blob/master/mtuq/greens_tensor/SPECFEM3D.py"
    click GSY "https://github.com/mtuqorg/mtuq/blob/master/mtuq/greens_tensor/syngine.py"
    click PD "https://github.com/mtuqorg/mtuq/blob/master/mtuq/process_data.py"
    click ST "https://github.com/mtuqorg/mtuq/blob/master/mtuq/station.py"
    click GBASE "https://github.com/mtuqorg/mtuq/blob/master/mtuq/grid/base.py"
    click GFORCE "https://github.com/mtuqorg/mtuq/blob/master/mtuq/grid/force.py"
    click GMOM "https://github.com/mtuqorg/mtuq/blob/master/mtuq/grid/moment_tensor.py"
    click GS "https://github.com/mtuqorg/mtuq/blob/master/mtuq/grid_search.py"
    click MPOL "https://github.com/mtuqorg/mtuq/blob/master/mtuq/misfit/polarity.py"
    click L0 "https://github.com/mtuqorg/mtuq/blob/master/mtuq/misfit/waveform/level0.py"
    click L1 "https://github.com/mtuqorg/mtuq/blob/master/mtuq/misfit/waveform/level1.py"
    click L2 "https://github.com/mtuqorg/mtuq/blob/master/mtuq/misfit/waveform/level2.py"
    click STATS "https://github.com/mtuqorg/mtuq/blob/master/mtuq/misfit/waveform/_stats.py"
    click CEXT "https://github.com/mtuqorg/mtuq/blob/master/mtuq/misfit/waveform/c_ext_L2.c"
    click MPL "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/_matplotlib.py"
    click PGMT "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/_pygmt.py"
    click GMT_ "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/_gmt.py"
    click BB "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/beachball.py"
    click WF "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/waveforms.py"
    click ATTR "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/attrs.py"
    click ANNOT "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/annotations.py"
    click UQ_DEPTH "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/uq/depth.py"
    click UQ_LUNE "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/uq/lune.py"
    click UQ_FORCE "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/uq/force.py"
    click UQ_HYP "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/uq/hypocenter.py"
    click UQ_OMEGA "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/uq/omega.py"
    click UQ_VW "https://github.com/mtuqorg/mtuq/blob/master/mtuq/graphics/uq/vw.py"
    click WAVE "https://github.com/mtuqorg/mtuq/blob/master/mtuq/wavelet.py"
    click MATH "https://github.com/mtuqorg/mtuq/blob/master/mtuq/util/math.py"
    click SIG "https://github.com/mtuqorg/mtuq/blob/master/mtuq/util/signal.py"
    click UBB "https://github.com/mtuqorg/mtuq/blob/master/mtuq/util/beachball.py"
    click CAP "https://github.com/mtuqorg/mtuq/blob/master/mtuq/util/cap.py"
    click GALL "https://github.com/mtuqorg/mtuq/blob/master/mtuq/util/gallery.py"
    click USY "https://github.com/mtuqorg/mtuq/blob/master/mtuq/util/syngine.py"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef cext fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef user fill:#90EE90,stroke:#333,stroke-width:1px
```
