# smousavi05/eqtransformer architecture

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

- Interactive diagram: https://gitdiagram.com/smousavi05/eqtransformer
- Repository: https://github.com/smousavi05/eqtransformer

## Overview

##### Main Components
a. Data Ingestion & Storage
- Downloader (EQTransformer/utils/downloader.py) fetches continuous seismic waveforms.
- HDF5 Maker (EQTransformer/utils/hdf5_maker.py) packages raw traces into HDF5.
- Sample Data & Models directory (ModelsAndSampleData/) holds .h5 model files, .hdf5 datasets, .npy indices.
b. Preprocessing & Utilities
- Plotting (EQTransformer/utils/plot.py) for visualization.
- Associator (EQTransformer/utils/associator.py) for simple phase association.
c. Core Engine
- Trainer (EQTransformer/core/trainer.py) builds and trains new models in TensorFlow.
- Tester (EQTransformer/core/tester.py) evaluates model performance on test sets.
- Predictor (EQTransformer/core/predictor.py) applies models to single‐station data.
- MSEED Predictor (EQTransformer/core/mseed_predictor.py) batches prediction on miniSEED directories.
- Utils (EQTransformer/core/EqT_utils.py) shared neural‐network utilities.
d. External Interfaces
- Python API (module entry points exposed by setup.py).
- Jupyter notebooks (examples/ and EQTransformerviaGoogleColab.ipynb) demonstrating workflows.
- CLI hooks (if configured in setup.py) or direct module calls.
e. Development & Deployment
- Tests (tests/*.py) for unit and integration testing.
- CI Pipeline (.github/workflows/python-publish.yml) automates linting, tests, packaging, publishing.
- Documentation (docs/) generated via Sphinx.

##### Architectural Patterns & Principles
- Modular layered architecture:
- “Utils” layer (data download & formatting)
- “Core” layer (AI model lifecycle: train, test, predict)
- “Interface” layer (Jupyter/CLI)
- Data‐pipeline pattern: raw data → preprocessing → model training/prediction → postprocessing.
- Separation of concerns: each module has one responsibility.
- Use of external libraries: Obspy (waveform I/O), TensorFlow (modeling), HDF5 (storage).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Storage
    subgraph "Data Ingestion & Storage"
        Downloader["Downloader"]:::utils
        HDF5Maker["HDF5 Maker"]:::utils
        SampleModels[(Sample Data & Models)]:::data
    end

    %% Preprocessing & Utilities
    subgraph "Preprocessing & Utilities"
        Plotter["Plotting"]:::utils
        Associator["Associator"]:::utils
    end

    %% Core Engine
    subgraph "Core Engine"
        Trainer["Trainer"]:::core
        Tester["Tester"]:::core
        Predictor["Predictor"]:::core
        MSEEDPred["MSEED Predictor"]:::core
        NNUtils["EqT_utils"]:::core
    end

    %% External Interfaces
    subgraph "External Interfaces"
        PythonAPI["Python API"]:::interface
        JupyterExamples["examples/"]:::interface
        JupyterColab["EQTransformerviaGoogleColab.ipynb"]:::interface
        CLI["CLI"]:::interface
    end

    %% Development & Deployment
    subgraph "Development & Deployment"
        Tests["Tests"]:::infra
        CI["CI Pipeline"]:::infra
        Docs["Documentation"]:::infra
    end

    %% Data Flows
    Downloader -->|"waveform traces"| HDF5Maker
    HDF5Maker -->|"HDF5 dataset"| SampleModels
    HDF5Maker -->|"HDF5 dataset"| Trainer
    SampleModels -->|"trained .h5 model"| Trainer
    Trainer -->|"trained .h5 model"| SampleModels
    SampleModels -->|"model & data"| Predictor
    SampleModels -->|"model & data"| MSEEDPred
    Predictor -->|"predictions"| Tester
    MSEEDPred -->|"predictions"| Tester
    Predictor -->|"predictions"| Associator
    MSEEDPred -->|"predictions"| Associator
    Predictor -->|"predictions"| Plotter
    MSEEDPred -->|"predictions"| Plotter

    %% Interfaces Invoking Pipeline
    JupyterExamples --> PythonAPI
    JupyterColab --> PythonAPI
    CLI --> PythonAPI
    PythonAPI --> Downloader
    PythonAPI --> Trainer
    PythonAPI --> Predictor
    PythonAPI --> MSEEDPred

    %% Development Infrastructure
    Tests --> Trainer
    Tests --> Predictor
    CI --> Tests
    CI --> Trainer
    Docs --> PythonAPI

    %% Click Events
    click Downloader "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/utils/downloader.py"
    click HDF5Maker "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/utils/hdf5_maker.py"
    click SampleModels "https://github.com/smousavi05/eqtransformer/tree/master/ModelsAndSampleData/"
    click Plotter "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/utils/plot.py"
    click Associator "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/utils/associator.py"
    click Trainer "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/core/trainer.py"
    click Tester "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/core/tester.py"
    click Predictor "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/core/predictor.py"
    click MSEEDPred "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/core/mseed_predictor.py"
    click NNUtils "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformer/core/EqT_utils.py"
    click PythonAPI "https://github.com/smousavi05/eqtransformer/blob/master/setup.py"
    click JupyterExamples "https://github.com/smousavi05/eqtransformer/tree/master/examples/"
    click JupyterColab "https://github.com/smousavi05/eqtransformer/blob/master/EQTransformerviaGoogleColab.ipynb"
    click Tests "https://github.com/smousavi05/eqtransformer/tree/master/tests/"
    click CI "https://github.com/smousavi05/eqtransformer/blob/master/.github/workflows/python-publish.yml"
    click Docs "https://github.com/smousavi05/eqtransformer/tree/master/docs/"

    %% Styles
    classDef utils fill:#cce5ff,stroke:#000
    classDef core fill:#b3d9ff,stroke:#000
    classDef data fill:#ccffcc,stroke:#000
    classDef interface fill:#ffe0b3,stroke:#000
    classDef infra fill:#e0e0e0,stroke:#000
```
