# hykrow/ai_sismology architecture

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

- Interactive diagram: https://gitdiagram.com/hykrow/ai_sismology
- Repository: https://github.com/hykrow/ai_sismology

## Overview

##### Project Type and Purpose
- This is a multi-module machine-learning system for seismology, consisting of two main subprojects:
- seisLM: a framework for seismic phase picking, model pretraining/fine-tuning, data conversion, and inference.
- SeisCLIP: a framework for seismic source localization and focal-mechanism estimation, with training, zero-shot, and inference capabilities.

##### Core Components
A. Data Generation & Conversion Layer (emphasize)
1. Raw Data Sources
- HEMEW-3D simulated zip archives (under seisLM/simulated_data)
- STEAD and other waveform repositories (SeisCLIP_content/SeisCLIP/MIFNO/data)
- CSV metadata files for classification, localization, zero-shot tasks
2. Data Conversion & Preprocessing
- seisLM/simulated_data: python scripts to unzip, convert annotations (.zip → CSV/HDF5)
- seisLM/data_pipeline modules:
- augmentations.py (waveform augment)
- collator.py (batch collator)
- foreshock_aftershock_dataset.py (dataset loader)
- pretrain_dataloaders.py
- SeisCLIP_content/SeisCLIP/MIFNO/data: conversion_format_stead.py, conversion_spectrogramme.py, metadata_format_stead.py
3. Metadata & Indexing
- seisLM/seisLM/utils/data_utils.py (path resolution, file indexing)
- SeisCLIP_content/SeisCLIP/Data/*.csv (train/val/test splits)

B. Training & Fine-Tuning Layer
- Pretraining (seisLM/src/pretrain/pretrain_run.py and SeisCLIP_content/SeisCLIP/Pretrain)
- Fine-tuning (seisLM supports SSL finetune; SeisCLIP finetune_seisclip.py)
- Multi-GPU data-parallel support (train_DDP_audio_stead_two_branch_600.py)

C. Model Foundations & Task-Specific Modules
- seisLM/seisLM/model/foundation (wav2vec2 backbones, conv encoder)
- seisLM/seisLM/model/task_specific (phase-pick & foreshock/aftershock heads)
- SeisCLIP_content/SeisCLIP/Event_classification and Zero_shot model_seismic_clip modules

D. Inference & Evaluation Layer
- seisLM/inference (generate_predictions.py, simulated_generate_* scripts)
- seisLM/seisLM/evaluation (pick_eval, analysis)
- SeisCLIP_content/SeisCLIP/test.py, Demo_zeroshot_pred.ipynb

##### Component Relationships & Data Flow
- From Datasets → DataPipeline → DataLoader → Model Training/Fine-tuning
- From Trained Checkpoints → Inference Scripts → Predictions/Visualizations
- Evaluation modules consume predictions + ground truth → Metrics

##### Architectural Patterns & Principles
- Modular pipeline separation: data ingestion, preprocessing, training, inference and evaluation are in distinct directories.
- Configurable via JSON configs (seisLM/seisLM/configs) for reproducibility.
- Extensibility: new models or data sources can plug into existing pipeline modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Generation & Conversion Layer
    subgraph "Data Generation & Conversion"
        direction TB
        RawData["Raw Data Sources"]:::data
        Conversion["Data Conversion & Preprocessing"]:::data
        Preprocessed["Preprocessed Dataset Storage"]:::data
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        direction TB
        Augment["augmentations.py"]:::data
        Collate["collator.py"]:::data
        DatasetLoader["foreshock_aftershock_dataset.py"]:::data
        PretrainDL["pretrain_dataloaders.py"]:::data
    end

    %% Training & Fine-Tuning Layer
    subgraph "Training & Fine-Tuning"
        direction TB
        PretrainRun["pretrain_run.py"]:::train
        PhasepickRun["phasepick_run.py"]:::train
        ForeshockRun["foreshock_aftershock_run.py"]:::train
        DDPTrain["train_DDP_audio_stead_two_branch_600.py"]:::train
        FineTuneCLIP["finetune_seisclip.py"]:::train
        Checkpoints["Checkpoint Storage"]:::train
    end

    %% Model Components
    subgraph "Model Foundations & Task-Specific"
        direction TB
        Foundation["SeisLM Foundation"]:::model
        TaskHeads["Task-Specific Heads"]:::model
        EventClass["Event Classification Models"]:::model
        ZeroShot["Zero-Shot Models"]:::model
    end

    %% Inference & Evaluation Layer
    subgraph "Inference & Evaluation"
        direction TB
        InferenceSLM["generate_predictions.py / simulated_generate_preditions.py"]:::infer
        InferenceCLIP["Demo Zero-Shot Predictions"]:::infer
        EvalPick["pick_eval.py"]:::infer
        EvalAnalysis["analysis.py"]:::infer
    end

    %% Connections
    RawData -->|"feed zips & CSVs"| Conversion
    Conversion -->|"produce HDF5/CSV"| Preprocessed
    Preprocessed -->|"used by"| Augment
    Augment --> Collate
    Collate --> DatasetLoader
    DatasetLoader --> PretrainDL
    PretrainDL -->|"provide batches to"| PretrainRun
    PretrainRun --> Checkpoints
    PhasepickRun --> Checkpoints
    ForeshockRun --> Checkpoints
    DDPTrain --> Checkpoints
    FineTuneCLIP --> Checkpoints
    Checkpoints -->|"load weights for"| Foundation
    Foundation --> TaskHeads
    TaskHeads --> EventClass
    TaskHeads --> ZeroShot
    EventClass --> InferenceCLIP
    ZeroShot --> InferenceCLIP
    Checkpoints --> InferenceSLM
    InferenceSLM --> EvalPick
    InferenceSLM --> EvalAnalysis

    %% Click Events
    click Conversion "https://github.com/hykrow/ai_sismology/tree/main/seisLM/simulated_data"
    click RawData "https://github.com/hykrow/ai_sismology/tree/main/seisLM/simulated_data"
    click Augment "https://github.com/hykrow/ai_sismology/blob/main/seisLM/seisLM/data_pipeline/augmentations.py"
    click Collate "https://github.com/hykrow/ai_sismology/blob/main/seisLM/seisLM/data_pipeline/collator.py"
    click DatasetLoader "https://github.com/hykrow/ai_sismology/blob/main/seisLM/seisLM/data_pipeline/foreshock_aftershock_dataset.py"
    click PretrainDL "https://github.com/hykrow/ai_sismology/blob/main/seisLM/seisLM/data_pipeline/pretrain_dataloaders.py"
    click PretrainRun "https://github.com/hykrow/ai_sismology/blob/main/seisLM/src/pretrain/pretrain_run.py"
    click PhasepickRun "https://github.com/hykrow/ai_sismology/blob/main/seisLM/src/phasepick/phasepick_run.py"
    click ForeshockRun "https://github.com/hykrow/ai_sismology/blob/main/seisLM/src/foreshock_aftershock/foreshock_aftershock_run.py"
    click DDPTrain "https://github.com/hykrow/ai_sismology/blob/main/SeisCLIP_content/SeisCLIP/Pretrain/train_DDP_audio_stead_two_branch_600.py"
    click FineTuneCLIP "https://github.com/hykrow/ai_sismology/blob/main/SeisCLIP_content/SeisCLIP/finetune_seisclip.py"
    click Foundation "https://github.com/hykrow/ai_sismology/tree/main/seisLM/seisLM/model/foundation"
    click TaskHeads "https://github.com/hykrow/ai_sismology/tree/main/seisLM/seisLM/model/task_specific"
    click EventClass "https://github.com/hykrow/ai_sismology/blob/main/SeisCLIP_content/SeisCLIP/Event_classification/model/model_seismic_clip.py"
    click ZeroShot "https://github.com/hykrow/ai_sismology/blob/main/SeisCLIP_content/SeisCLIP/Zero_shot/model/model_seismic_clip.py"
    click InferenceSLM "https://github.com/hykrow/ai_sismology/blob/main/seisLM/inference/generate_predictions.py"
    click EvalPick "https://github.com/hykrow/ai_sismology/blob/main/seisLM/seisLM/evaluation/pick_eval.py"
    click EvalAnalysis "https://github.com/hykrow/ai_sismology/blob/main/seisLM/seisLM/evaluation/analysis.py"
    click InferenceCLIP "https://github.com/hykrow/ai_sismology/blob/main/SeisCLIP_content/SeisCLIP/Zero_shot/Demo_zeroshot_pred.ipynb"

    %% Styles
    classDef data fill:#add8e6,stroke:#000,stroke-width:1px
    classDef train fill:#90ee90,stroke:#000,stroke-width:1px
    classDef model fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef infer fill:#ffa500,stroke:#000,stroke-width:1px
```
