# germanyy0410/graph-attention-network-fpga architecture

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

- Interactive diagram: https://gitdiagram.com/germanyy0410/graph-attention-network-fpga
- Repository: https://github.com/germanyy0410/graph-attention-network-fpga

## Overview

Based on our analysis of the provided file tree and README, this project is an FPGA-based hardware accelerator for Graph Attention Networks (GAT). The goal is to optimize key GAT computations – including DMVM, SPMM, custom softmax, and aggregation – by mapping them onto an FPGA. The project is organized into modules for hardware description (SystemVerilog under the rtl folder), synthesis constraints (syn folder), testbenches (tb folder), and input/output data management (data folder with examples for Citeseer and Cora datasets).

##### Main Components
a. Input Data & Preprocessing:
- Data files organized under “data” (e.g., input text files for a.txt, h_data.txt, node_info.txt, weight.txt) to represent graph data.
- Two layers indicated in the file tree (layer_1 and layer_2) suggest a multi-stage or multi-layer GAT architecture.
b. Hardware Accelerator Modules:
- DMVM Module – Found under rtl/src/DMVM, with supporting files in the corresponding “data” outputs.
- SPMM Module – Found under rtl/src/SPMM, including multiple submodules such as SP_PE and controllers.
- Aggregator Module – Located under rtl/src/aggregator, dealing with feature aggregation.
- Softmax Module – Located specifically in rtl/src/softmax, with its custom implementation utilizing bit-shift operations instead of conventional exponential calculations.
c. Additional Supporting Components:
- Memory Controllers and BRAM/URAM modules – Detailed under rtl/src/memory and rtl/src/others/BRAM.
- Scheduler – Found in rtl/src/scheduler, responsible for controlling the load and operation sequence (e.g., W_loader, scheduler_conv2).
- Other utility modules (multipliers, dividers) in rtl/src/others (e.g., fxp_mul_pipe, fxp_div_pipe).
- Top-level integration modules such as gat_top, gat_conv1, gat_conv2, and the top wrapper (rtl/src/gat_top_wrapper.v) that tie the overall design together.
d. Verification/Testing:
- Testbench modules (tb folder) and simulation artifacts which help verify individual modules and overall system integration.
- Synthesis files (syn folder) and scripts for FPGA implementation.

##### Relationships and Interactions
- Data flows from external inputs (graph data) through a preprocessing stage to feed into the processing modules (DMVM, SPMM, Aggregator, Softmax).
- Each module processes a portion of the GAT computations. For instance, DMVM and SPMM are used for matrix-vector operations that are integral to the GAT’s layer calculations.
- Softmax is implemented with a custom algorithm for hardware efficiency; it receives intermediate results from the aggregator stage.
- The Memory Controller facilitates efficient storage and retrieval across these stages, coordinating with the scheduler.
- The scheduler governs the operation sequencing and data loading to ensure smooth operation across parallel processing elements.
- The top-level module (gat_top and its wrapper) integrates and connects these pipelines so that the accelerator processes the input graph data in a layered, modular fashion.

##### Architectural Patterns and Design Principles
- Modularity: The RTL code is organized per functional blocks (DMVM, SPMM, etc.), which helps to understand data and control flow.
- Parallel Processing: Special emphasis is on parallelism (e.g., multiple processing elements in SPMM) optimizing latency and throughput.
- Hardware-specific Optimizations: The custom softmax using bit-shift operations and dynamic quantization (to INT8) are specially designed for FPGA resource optimization.
- Data and Control Flow Separation: Clearly defined input, processing, and output stages, with dedicated scheduler and memory controller blocks ensuring synchronized operations.

##### Relevant Technologies and Frameworks
- FPGA design using SystemVerilog and Verilog.
- Synthesis constraints (syn folder with XDC files) tailored for FPGA resource utilization.
- Testbench designs (tb folder) likely employing simulation tools to validate behavior.
- Parallel processing and memory optimization techniques implemented in hardware.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Data & Preprocessing
    subgraph "Input Data & Preprocessing"
        DataFiles["Input Data (Citeseer/Cora)"]:::data
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        DMVM["RTL – DMVM Module"]:::computation
        SPMM["RTL – SPMM Module"]:::computation
        subgraph "SPMM Submodules"
            SP_PE["SP_PE"]:::computation
            WH["WH"]:::computation
            NumCtrl["num_node_controller"]:::computation
        end
        Aggregator["RTL – Aggregator Module"]:::computation
        FeatureCtrl["Feature Controller"]:::computation
        Softmax["RTL – Softmax Module"]:::computation
        Exponential["Exponential (Bit-Shift Softmax)"]:::computation
    end

    %% Memory and Control
    subgraph "Memory and Control"
        MemoryController["Memory Controller"]:::memory
        BRAM["BRAM/URAM Modules"]:::memory
        Scheduler["Scheduler"]:::control
        MultiplierModules["Multiplier Modules"]:::utility
        DividerModules["Divider Modules"]:::utility
    end

    %% Top-Level Integration
    subgraph "Top-Level Integration"
        GatTop["GAT Top"]:::integration
        GatConv1["GAT Conv1"]:::integration
        GatConv2["GAT Conv2"]:::integration
        TopWrapper["Top Wrapper"]:::integration
    end

    %% Verification / Testing
    subgraph "Verification/Testing"
        Testbench["Testbench (TB)"]:::verification
        Synthesis["Synthesis Constraints"]:::verification
    end

    %% Data Flow Connections
    DataFiles -->|"feeds"| DMVM
    DataFiles -->|"feeds"| SPMM

    DMVM -->|"outputs"| Aggregator
    SPMM -->|"outputs"| Aggregator
    Aggregator -->|"sends"| Softmax
    Softmax -->|"final result"| GatTop

    %% SPMM Internal Connections
    SPMM --> SP_PE
    SPMM --> WH
    SPMM --> NumCtrl

    %% Memory & Control Interactions
    MemoryController --> DMVM
    MemoryController --> SPMM
    MemoryController --> Aggregator
    MemoryController --> Softmax
    Scheduler --> MemoryController
    Scheduler --> MultiplierModules
    Scheduler --> DividerModules
    BRAM --> MemoryController

    %% Top-Level Integration Connections
    GatTop --> DMVM
    GatTop --> SPMM
    GatTop --> Aggregator
    GatTop --> Softmax
    GatTop --> MemoryController
    GatTop --> Scheduler
    GatTop --> BRAM
    GatTop --> MultiplierModules
    GatTop --> DividerModules
    GatTop --> GatConv1
    GatTop --> GatConv2
    GatTop --> TopWrapper

    %% Verification Connections
    Testbench --> GatTop
    Synthesis --> GatTop

    %% Styling Classes
    classDef data fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef computation fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef memory fill:#fcf3cf,stroke:#333,stroke-width:2px;
    classDef control fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef utility fill:#e8daef,stroke:#333,stroke-width:2px;
    classDef integration fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef verification fill:#d6eaf8,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click DataFiles "https://github.com/germanyy0410/graph-attention-network-fpga/tree/main/data/"
    click DMVM "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/DMVM/DMVM.sv"
    click SPMM "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/SPMM/SPMM.sv"
    click SP_PE "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/SPMM/SP_PE.sv"
    click WH "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/SPMM/WH.sv"
    click NumCtrl "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/SPMM/num_node_controller.sv"
    click Aggregator "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/aggregator/aggregator.sv"
    click FeatureCtrl "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/aggregator/feature_controller.sv"
    click Softmax "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/softmax/softmax.sv"
    click Exponential "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/softmax/exponential.sv"
    click MemoryController "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/memory/memory_controller.sv"
    click BRAM "https://github.com/germanyy0410/graph-attention-network-fpga/tree/main/rtl/src/others/BRAM"
    click Scheduler "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/scheduler/scheduler.sv"
    click MultiplierModules "https://github.com/germanyy0410/graph-attention-network-fpga/tree/main/rtl/src/others/mul"
    click DividerModules "https://github.com/germanyy0410/graph-attention-network-fpga/tree/main/rtl/src/others/div"
    click GatTop "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/gat_top.sv"
    click GatConv1 "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/gat_conv1.sv"
    click GatConv2 "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/gat_conv2.sv"
    click TopWrapper "https://github.com/germanyy0410/graph-attention-network-fpga/blob/main/rtl/src/gat_top_wrapper.v"
    click Testbench "https://github.com/germanyy0410/graph-attention-network-fpga/tree/main/tb/"
    click Synthesis "https://github.com/germanyy0410/graph-attention-network-fpga/tree/main/syn/"
```
