# zmoka-zht/cdmamba architecture

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

- Interactive diagram: https://gitdiagram.com/zmoka-zht/cdmamba
- Repository: https://github.com/zmoka-zht/cdmamba

## Overview

##### Main Components
- Data Management Layer – Represented by the “data” directory, this module deals with dataset handling, preprocessing, list generation (e.g., generate_list.py), and utility functions.
- Core Functionalities – Found in the “core” directory, which includes basic utilities such as logging (logger.py) and metrics (metrics.py) essential for monitoring training and inference.
- Model Architectures – The “models” directory houses numerous deep neural network implementations (e.g., CDMamba, ChangeFormer, FC-EF, SNUNet, etc.). Note the subdirectories (like “backbone”, “changemamba_cd_help”, “darnet_help”, etc.) that indicate modular designs and possible reuse of components.
- Configuration Management – “config” holds different JSON configurations for various experimental settings (for example, levir_cdmamba.json, levir_test_cdmamba.json). These files define hyperparameters, dataset paths, and other runtime options.
- Miscellaneous Utilities – The “misc” folder contains additional scripts for tasks such as metric computation and auxiliary PyTorch utilities.
- Training & Testing Pipeline – Scripts like train_cd.py and test_cd.py serve as entry points for training and evaluating the models, tying the above components together.

##### Relationships and Data Flow
- Preprocessing and Utility Functions: Indicate that the “data/util.py” and “data/colormap.py” assist in handling and preparing data before it is fed to the models.
- Core Processing: Show that after a model processes the data, the “core” components (logging and metrics) capture outputs, errors, performance data, and other signals during training and testing.
- Kernel / Low-level Operations: Within the “models/changemamba_cd_help/kernels” sub-tree, there is a specialized sub-system (written in C/C++ for CUDA kernels) to optimize selective scanning operations. Represent these as a “CUDA Kernel Module” linked to the main model execution allowing for GPU-accelerated operations.
- External Libraries: Mark dependencies like PyTorch, CUDA, and potential external libraries (mamba-ssm and causal-conv1d as hinted in the README) to give context on the runtime environment.

##### Architectural Patterns and Design Principles
- Integration of Optimized Low-level Routines: The use of custom CUDA kernels for selective scan operations (in “changemamba_cd_help/kernels/selective_scan”) indicates optimized performance paths for critical operations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        ED1["README"]:::external
        ED2["Requirement.txt"]:::external
    end

    %% Data Input
    DI["Data Input (Raw Satellite Imagery)"]:::input

    %% Data Management Subgraph
    subgraph "Data Management"
        DM1["Generate List"]:::data
        DM2["Data Utils"]:::data
        DM3["Colormap"]:::data
    end

    %% Configuration Management Subgraph
    subgraph "Configuration Management"
        CM1["Levir+ CDMamba Config"]:::config
        CM2["Mamba Config"]:::config
    end

    %% Model Architectures Subgraph
    subgraph "Model Architectures"
        MA1["CDMamba"]:::model
        MA2["ChangeFormer"]:::model
        MA3["SNUNet"]:::model
        MA4["Backbone"]:::model
        MA5["Darnet Help"]:::model
    end

    %% CUDA Kernel Module
    CKM["CUDA Kernel Module"]:::cuda

    %% Core Utilities (Logging & Metrics) Subgraph
    subgraph "Core Utilities"
        CU1["Logger"]:::core
        CU2["Metrics"]:::core
    end

    %% Miscellaneous Utilities Subgraph
    subgraph "Miscellaneous Utilities"
        MU1["Calculate Metric"]:::misc
        MU2["Metric Tools"]:::misc
        MU3["Torch Utils"]:::misc
    end

    %% Training/Testing Pipeline Subgraph
    subgraph "Training/Testing Pipeline"
        TP1["Train Script"]:::pipeline
        TP2["Test Script"]:::pipeline
    end

    %% Data Flow Connections
    DI -->|"feeds"| DM1
    DI -->|"feeds"| DM2
    DI -->|"feeds"| DM3

    %% Configuration influences Model Architectures and Pipeline
    CM1 -->|"config-controls"| MA1
    CM1 -->|"config-controls"| TP1
    CM2 -->|"config-controls"| MA2
    CM2 -->|"config-controls"| TP2

    %% Data Management to Model Architectures
    DM1 --- DM2
    DM2 --- DM3
    DM1 -->|"processed-data"| MA1
    DM2 -->|"processed-data"| MA2
    DM3 -->|"processed-data"| MA3

    %% Model Architectures internal flow
    MA1 --> MA2
    MA2 --> MA3
    MA3 --> MA4
    MA4 --> MA5

    %% Model Architectures linking to CUDA Kernel Module
    MA1 -->|"GPU-acceleration"| CKM

    %% Model output flows to Core Utilities
    MA5 -->|"logs/metrics"| CU1
    MA5 -->|"logs/metrics"| CU2

    %% Core Utilities to Miscellaneous Utilities
    CU1 -->|"further-analysis"| MU1
    CU2 -->|"further-analysis"| MU2
    CU2 -->|"further-analysis"| MU3

    %% Training/Testing Pipeline triggers the process
    TP1 -->|"orchestrates"| DM1
    TP1 -->|"orchestrates"| MA1
    TP1 -->|"orchestrates"| CU1
    TP2 -->|"orchestrates"| DM1
    TP2 -->|"orchestrates"| MA1
    TP2 -->|"orchestrates"| CU2

    %% External Dependencies support the entire system
    ED1 --- DI
    ED2 --- TP1

    %% Click Events for Data Management Layer
    click DM1 "https://github.com/zmoka-zht/cdmamba/blob/main/data/generate_list.py"
    click DM2 "https://github.com/zmoka-zht/cdmamba/blob/main/data/util.py"
    click DM3 "https://github.com/zmoka-zht/cdmamba/blob/main/data/colormap.py"

    %% Click Events for Core Functionalities
    click CU1 "https://github.com/zmoka-zht/cdmamba/blob/main/core/logger.py"
    click CU2 "https://github.com/zmoka-zht/cdmamba/blob/main/core/metrics.py"

    %% Click Events for Model Architectures
    click MA1 "https://github.com/zmoka-zht/cdmamba/blob/main/models/CDMamba.py"
    click MA2 "https://github.com/zmoka-zht/cdmamba/blob/main/models/changeformer.py"
    click MA3 "https://github.com/zmoka-zht/cdmamba/blob/main/models/snunet.py"
    click MA4 "https://github.com/zmoka-zht/cdmamba/tree/main/models/backbone"
    click MA5 "https://github.com/zmoka-zht/cdmamba/tree/main/models/darnet_help"

    %% Click Event for CUDA Kernel Module
    click CKM "https://github.com/zmoka-zht/cdmamba/tree/main/models/changemamba_cd_help/kernels/selective_scan/"

    %% Click Events for Configuration Management
    click CM1 "https://github.com/zmoka-zht/cdmamba/blob/main/config/levir+_cdmamba/levir+_cdmamba.json"
    click CM2 "https://github.com/zmoka-zht/cdmamba/blob/main/config/mamba/levir_cdmamba.json"

    %% Click Events for Miscellaneous Utilities
    click MU1 "https://github.com/zmoka-zht/cdmamba/blob/main/misc/caculate_metric.py"
    click MU2 "https://github.com/zmoka-zht/cdmamba/blob/main/misc/metric_tools.py"
    click MU3 "https://github.com/zmoka-zht/cdmamba/blob/main/misc/torchutils.py"

    %% Click Events for Training/Testing Pipeline
    click TP1 "https://github.com/zmoka-zht/cdmamba/blob/main/train_cd.py"
    click TP2 "https://github.com/zmoka-zht/cdmamba/blob/main/test_cd.py"

    %% Click Events for External Dependencies
    click ED1 "https://github.com/zmoka-zht/cdmamba/blob/main/README.md"
    click ED2 "https://github.com/zmoka-zht/cdmamba/blob/main/requirement.txt"

    %% Styles
    classDef input fill:#fef9c3,stroke:#d97706,stroke-width:2px;
    classDef data fill:#dbeafe,stroke:#3b82f6,stroke-width:2px;
    classDef config fill:#fee2e2,stroke:#ef4444,stroke-width:2px;
    classDef model fill:#e0f2fe,stroke:#0284c7,stroke-width:2px;
    classDef cuda fill:#fde68a,stroke:#f59e0b,stroke-width:2px;
    classDef core fill:#dcfce7,stroke:#22c55e,stroke-width:2px;
    classDef misc fill:#f3e8ff,stroke:#8b5cf6,stroke-width:2px;
    classDef pipeline fill:#fff1f2,stroke:#f43f5e,stroke-width:2px;
    classDef external fill:#e0e7ff,stroke:#6366f1,stroke-width:2px;
```
