# estija/co-vegan architecture

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

- Interactive diagram: https://gitdiagram.com/estija/co-vegan
- Repository: https://github.com/estija/co-vegan

## Overview

##### Project Type and Purpose
- This project implements a complex-valued GAN for compressive sensing MRI reconstruction. It employs deep learning to both reconstruct MRI images from undersampled k-space data and handle complex data representations.
- The README clearly outlines different datasets (MICCAI 2013, MRNet, fastMRI) and points out specific training and testing procedures for real-valued versus complex-valued datasets.

##### File Tree and Its Implications
- The core package is found in the “complexnn” folder, which contains modules like conv.py, dense.py, bn.py, norm.py, pool.py, fft.py, init.py, and utils.py. These files define layers and utilities used to build the complex-valued neural network components.
- There are training scripts (train_model.py and train_model_complex.py) and testing scripts (test_model.py and test_model_complex.py) that dictate the training/inference process.
- Standalone scripts such as dataset_load.py and usamp_data.py are responsible for data preparation: one for loading the GT dataset and one for generating undersampled data.
- The “masks” folder includes several undersampling mask files which are used when preparing the data pipeline for undersampled reconstruction.
- Additional files like metrics.py and wvt_loss.py suggest custom evaluation metrics and loss functions used during training.

##### Architectural Components
- Data Preparation Layer:
- Components: dataset_load.py, usamp_data.py, and the “masks” directory.
- Function: Download datasets, create ground truth and undersampled datasets using the different masks provided.
- Model Components:
- Core library: “complexnn” package, containing custom implementations for convolutional, dense, batch normalization, pooling, FFT-based layers, and other utilities.
- Architectural patterns: Likely use of GAN architecture with distinct Generator (and possibly Discriminator) components that integrate these complex-valued neural modules.
- Training/Testing Framework:
- Scripts: Separate entry points for training (train_model.py for real-valued data and train_model_complex.py for complex data) and testing (test_model.py and test_model_complex.py).
- Interaction: These scripts call various layers from the “complexnn” package and use defined loss functions, metrics, and custom masks.
- External Dependencies/Environment:
- Dependencies such as TensorFlow, Keras, and CUDA form part of the backend execution environment.
- Hardware requirements: Use of multiple GPUs (as specified in the README).

##### Relationships and Interactions
- Data Flow:
- Data Preparation Phase: Raw MRI data is downloaded → processed by dataset_load.py → undersampled using usamp_data.py with reference to mask files.
- Model Training: The training scripts load the processed data, initialize the complex-valued network components from “complexnn,” and then execute training with designated loss functions (wvt_loss.py) and metrics (metrics.py).
- Model Testing: Testing scripts validate model performance on either real or complex-valued datasets.
- Control Flow:
- The entry scripts serve as the orchestration layer, invoking data preparation, model building, training loops, and evaluation in sequence.
- The various Python modules in complexnn abstract out specific functionalities (e.g., FFT-based operations for complex data) to modularize the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation Layer
    subgraph "Data Preparation Layer"
        DS["dataset_load.py"]:::data
        US["usamp_data.py"]:::data
        MASKS["Masks (Directory)"]:::data
    end

    %% Complex-Valued Neural Network Library
    subgraph "Complex-Valued NN Library"
        CONV["conv.py"]:::nn
        DENSE["dense.py"]:::nn
        BN["bn.py"]:::nn
        FFT["fft.py"]:::nn
        INIT["init.py"]:::nn
        NORM["norm.py"]:::nn
        POOL["pool.py"]:::nn
        UTILS["utils.py"]:::nn
    end

    %% Training and Testing Framework
    subgraph "Training and Testing Framework"
        TR1["train_model.py (Real)"]:::train
        TR2["train_model_complex.py (Complex)"]:::train
        TS1["test_model.py (Real)"]:::train
        TS2["test_model_complex.py (Complex)"]:::train
    end

    %% Custom Loss and Metrics
    subgraph "Loss & Metrics"
        LOSS["wvt_loss.py"]:::loss
        METRICS["metrics.py"]:::loss
    end

    %% External Dependencies/Infrastructure
    subgraph "External Dependencies"
        PY["Python 3.6"]:::infra
        TF["TensorFlow/Keras"]:::infra
        CUDA["CUDA/cuDNN"]:::infra
        GPU["Multi-GPU Environment"]:::infra
    end

    %% Data Flow: Data Preparation to Training
    DS -->|"data_flow"| TR1
    DS -->|"data_flow"| TR2
    US -->|"data_flow"| TR1
    US -->|"data_flow"| TR2
    MASKS -->|"applied"| TR1
    MASKS -->|"applied"| TR2

    %% Training Scripts calling NN Library (using conv.py as representative)
    TR1 -->|"calls"| CONV
    TR2 -->|"calls"| CONV
    TS1 -->|"calls"| CONV
    TS2 -->|"calls"| CONV

    %% Training & Testing using Loss & Metrics
    TR1 -->|"evaluates"| LOSS
    TR2 -->|"evaluates"| LOSS
    TS1 -->|"evaluates"| METRICS
    TS2 -->|"evaluates"| METRICS

    %% External Dependencies supporting Training & Testing
    PY -->|"supports"| TR1
    PY -->|"supports"| TR2
    PY -->|"supports"| TS1
    PY -->|"supports"| TS2

    TF -->|"framework"| TR1
    TF -->|"framework"| TR2
    TF -->|"framework"| TS1
    TF -->|"framework"| TS2

    %% External Dependencies supporting NN Library
    TF -->|"framework"| CONV
    CUDA -->|"acceleration"| CONV
    GPU -->|"runs_on"| CONV

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef nn fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef train fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef loss fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events for Data Preparation Layer
    click DS "https://github.com/estija/co-vegan/blob/master//dataset_load.py"
    click US "https://github.com/estija/co-vegan/blob/master//usamp_data.py"
    click MASKS "https://github.com/estija/co-vegan/tree/master//masks"

    %% Click Events for Complex-Valued NN Library
    click CONV "https://github.com/estija/co-vegan/blob/master//complexnn/conv.py"
    click DENSE "https://github.com/estija/co-vegan/blob/master//complexnn/dense.py"
    click BN "https://github.com/estija/co-vegan/blob/master//complexnn/bn.py"
    click FFT "https://github.com/estija/co-vegan/blob/master//complexnn/fft.py"
    click INIT "https://github.com/estija/co-vegan/blob/master//complexnn/init.py"
    click NORM "https://github.com/estija/co-vegan/blob/master//complexnn/norm.py"
    click POOL "https://github.com/estija/co-vegan/blob/master//complexnn/pool.py"
    click UTILS "https://github.com/estija/co-vegan/blob/master//complexnn/utils.py"

    %% Click Events for Training/Testing Framework
    click TR1 "https://github.com/estija/co-vegan/blob/master//train_model.py"
    click TR2 "https://github.com/estija/co-vegan/blob/master//train_model_complex.py"
    click TS1 "https://github.com/estija/co-vegan/blob/master//test_model.py"
    click TS2 "https://github.com/estija/co-vegan/blob/master//test_model_complex.py"

    %% Click Events for Custom Loss and Metrics
    click LOSS "https://github.com/estija/co-vegan/blob/master//wvt_loss.py"
    click METRICS "https://github.com/estija/co-vegan/blob/master//metrics.py"
```
