How mtuqorg/mtuq works
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.