# alisiahkoohi/csgm architecture

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

- Interactive diagram: https://gitdiagram.com/alisiahkoohi/csgm
- Repository: https://github.com/alisiahkoohi/csgm

## Overview

##### Project Type and Purpose
- This is a research‐grade machine‐learning library and experiment suite.
- It provides:
- Core ML components (model definitions, noise scheduling) in a Python package (`csgm/`).
- Configuration files (`configs/`) that drive experiment parameters.
- Training and inference scripts (`scripts/`) that orchestrate end-to-end workflows.
- Data management (on-the-fly generation for toy examples, download for seismic imaging).
- Utilities for logging, checkpointing, normalization, learning-rate scheduling, etc.

##### Top-Level Components
a. User Interface / CLI Layer
- `scripts/train_conditional_quadratic.py`
- `scripts/train_conditional_seismic_imaging.py`
- Flags (`--phase train/test/plot`)
b. Configuration Management
- JSON files in `configs/`
- `csgm/utils/config.py` for parsing and applying hyperparameters
c. Data Layer
- Toy dataset generator (`csgm/utils/toy_dataset.py`)
- Seismic data downloader / loader (implicitly via scripts, stores into `data/`)
d. Core Library (`csgm/` package)
- Model definitions: `network_conditional.py`, `fourier_neural_operator.py`
- Noise scheduling: `noise_scheduler.py`
- Normalization & pre/post processing: `normalizer.py`, `grid.py`
- Hyperparameter utilities: `hyperparam_utils.py`, `lr_scheduler.py`
- Experiment persistence: `save_experiment.py`, `save_results.py`, `project_path.py`
e. Training & Inference Engine
- Loops that call models + scheduler + optimizer
- Checkpointing mechanism (`checkpoint_*.pth`)
- Posterior sampling and plotting
f. External Dependencies & Environment
- `environment.yml` (Conda, PyTorch, CUDA)
- `setup.py` (installs the `csgm` package editable)
- Data storage (`data/` folder, remote URL for pretrained weights)

##### Relationships and Interactions
- The CLI scripts read a JSON config → instantiate a config object.
- Config object drives: dataset loader, model constructor, noise scheduler, optimizer & LR scheduler.
- Training loop:
1. Load batch (toy or real)
2. Forward pass with model + scheduler
3. Backpropagate → update parameters
4. Periodic checkpoint via `save_experiment.py`
- Inference (test phase): uses trained model + scheduler → sample posterior → `save_results.py` → plot.
- Data flow: JSON → Config → Components → Results → Storage.

##### Architectural Patterns & Design Principles
- Modularity: clear separation between “models,” “data,” “training logic,” and “utils.”
- Configuration-driven design: all hyperparameters and experiment settings live in JSON.
- Dependency injection: config module passes parameters into model & scheduler constructors.
- Single-responsibility utilities: each file in `csgm/utils/` has one focus (normalization, saving, etc.).

##### Technologies & Frameworks to Annotate
- Python 3.x, PyTorch, Conda environment
- Fourier Neural Operator (FNO) implementation
- Diffusion/score-based sampling algorithm
- JSON for configuration
- Matplotlib or similar for plotting (implied)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Environment" 
        CONDA["environment.yml"]:::external
        SETUP["setup.py"]:::external
        DATA_STORE["data/ (Storage)"]:::external
    end

    %% Configuration Management
    subgraph "Configuration" 
        CONFIG_FILES["JSON Configs"]:::config
        CONFIG_PARSER["Config Parser\n(csgm/utils/config.py)"]:::config
    end

    %% CLI & Orchestration
    subgraph "CLI Layer" 
        TRAIN_Q["train_conditional_quadratic.py"]:::cli
        TRAIN_S["train_conditional_seismic_imaging.py"]:::cli
        FLAGS["Flags (--phase train/test/plot)"]:::cli
    end

    %% Data Layer
    subgraph "Data Layer" 
        TOY_DS["Toy Dataset Generator\n(csgm/utils/toy_dataset.py)"]:::data
        SEISMIC_DL["Seismic Data Loader\n(implicit → data/)"]:::data
    end

    %% Core Library
    subgraph "Core Library" 
        MODEL_COND["Model Definitions\n(csgm/network_conditional.py)"]:::core
        FNO["Fourier Neural Operator\n(csgm/fourier_neural_operator.py)"]:::core
        SCHEDULER["Noise Scheduler\n(csgm/noise_scheduler.py)"]:::core
    end

    %% Utilities
    subgraph "Utilities (csgm/utils)" 
        NORMALIZER["Normalization\n(csgm/utils/normalizer.py)"]:::util
        GRID["Grid Utils\n(csgm/utils/grid.py)"]:::util
        HYPERPARAM["Hyperparam Utils\n(csgm/utils/hyperparam_utils.py)"]:::util
        LR["LR Scheduler\n(csgm/utils/lr_scheduler.py)"]:::util
        SAVE_EXP["Save Experiment\n(csgm/utils/save_experiment.py)"]:::util
        SAVE_RES["Save Results\n(csgm/utils/save_results.py)"]:::util
        PROJ_PATH["Project Path\n(csgm/utils/project_path.py)"]:::util
    end

    %% Training & Inference Engines
    subgraph "Training Phase" 
        TRAIN_LOOP["Training Loop"]:::process
        CHECKPOINT["Checkpointing\n(checkpoint_*.pth)"]:::storage
    end

    subgraph "Inference Phase" 
        INFER_LOOP["Inference Loop"]:::process
        PLOT["Plotting Results"]:::process
    end

    %% Relationships
    CONFIG_FILES -->|provides params| CONFIG_PARSER
    CONFIG_PARSER -->|injects into| TRAIN_Q
    CONFIG_PARSER -->|injects into| TRAIN_S
    TRAIN_Q -->|uses| TOY_DS
    TRAIN_S -->|downloads/loads| SEISMIC_DL
    TRAIN_Q -->|calls| MODEL_COND
    TRAIN_Q -->|calls| SCHEDULER
    TRAIN_Q -->|calls| HYPERPARAM
    TRAIN_Q -->|calls| LR
    TRAIN_S -->|calls| MODEL_COND
    TRAIN_S -->|calls| FNO
    TRAIN_S -->|calls| SCHEDULER
    TRAIN_S -->|calls| HYPERPARAM
    TRAIN_S -->|calls| LR

    TRAIN_Q -->|executes| TRAIN_LOOP
    TRAIN_S -->|executes| TRAIN_LOOP
    TRAIN_LOOP -->|periodic| SAVE_EXP
    TRAIN_LOOP -->|stores to| CHECKPOINT

    INFER_LOOP -->|loads checkpoint| CHECKPOINT
    INFER_LOOP -->|calls| MODEL_COND
    INFER_LOOP -->|calls| SCHEDULER
    INFER_LOOP -->|generates| SAVE_RES
    SAVE_RES -->|sends to| PLOT

    TRAIN_Q -->|phase flag| FLAGS
    TRAIN_S -->|phase flag| FLAGS

    CONDA -.->|provides| TRAIN_Q
    SETUP -.->|installs| CORE_LIBRARY[/"csgm/ Package"/] 
    CORE_LIBRARY --> MODEL_COND
    CORE_LIBRARY --> FNO
    CORE_LIBRARY --> SCHEDULER
    CORE_LIBRARY -.-> NORMALIZER
    CORE_LIBRARY -.-> GRID
    CORE_LIBRARY -.-> HYPERPARAM
    CORE_LIBRARY -.-> LR
    CORE_LIBRARY -.-> SAVE_EXP
    CORE_LIBRARY -.-> SAVE_RES
    CORE_LIBRARY -.-> PROJ_PATH

    SEISMIC_DL --> DATA_STORE
    CHECKPOINT --> DATA_STORE
    SAVE_RES --> DATA_STORE

    %% Click Events
    click TRAIN_Q "https://github.com/alisiahkoohi/csgm/blob/main/scripts/train_conditional_quadratic.py"
    click TRAIN_S "https://github.com/alisiahkoohi/csgm/blob/main/scripts/train_conditional_seismic_imaging.py"
    click CONFIG_FILES "https://github.com/alisiahkoohi/csgm/blob/main/configs/toy_example_conditional_quadratic.json"
    click CONFIG_FILES "https://github.com/alisiahkoohi/csgm/blob/main/configs/seismic_imaging_conditional.json"
    click CONFIG_PARSER "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/config.py"
    click TOY_DS "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/toy_dataset.py"
    click MODEL_COND "https://github.com/alisiahkoohi/csgm/blob/main/csgm/network_conditional.py"
    click FNO "https://github.com/alisiahkoohi/csgm/blob/main/csgm/fourier_neural_operator.py"
    click SCHEDULER "https://github.com/alisiahkoohi/csgm/blob/main/csgm/noise_scheduler.py"
    click NORMALIZER "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/normalizer.py"
    click GRID "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/grid.py"
    click HYPERPARAM "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/hyperparam_utils.py"
    click LR "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/lr_scheduler.py"
    click SAVE_EXP "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/save_experiment.py"
    click SAVE_RES "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/save_results.py"
    click PROJ_PATH "https://github.com/alisiahkoohi/csgm/blob/main/csgm/utils/project_path.py"
    click CONDA "https://github.com/alisiahkoohi/csgm/blob/main/environment.yml"
    click SETUP "https://github.com/alisiahkoohi/csgm/blob/main/setup.py"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#1E70BF,color:#000;
    classDef config fill:#E8FFD0,stroke:#70BF1E,color:#000;
    classDef data fill:#FFE8D0,stroke:#BF701E,color:#000;
    classDef core fill:#D0FFD0,stroke:#1EBF70,color:#000;
    classDef util fill:#F0F0F0,stroke:#888888,color:#000;
    classDef external fill:#EEEEEE,stroke:#666666,color:#000,stroke-dasharray: 5 5;
    classDef process fill:#FFF0B3,stroke:#BF9E1E,color:#000;
    classDef storage fill:#FFD0D0,stroke:#BF1E1E,color:#000
```
