# hkust-zhiyao/rtl-coder architecture

> Architecture diagram of the GitHub repository hkust-zhiyao/rtl-coder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hkust-zhiyao/rtl-coder
- Repository: https://github.com/hkust-zhiyao/rtl-coder

## Overview

##### Main Components
- Data Generation Module:
– Folders: “data_generation” and “dataset”
– Purpose: Automates creating a labeled dataset of design instructions and reference Verilog code. Includes prompt templates (p_example.txt), utilities, and sample data (e.g., Resyn27k.json).
- Inference/Benchmarking Module:
– Folder: “benchmark_inference”
– Purpose: Provides scripts for testing generated RTL code using various benchmarks (RTLLM and Verilog-eval) and for different model variants (RTLCoder-Deepseek, RTLCoder-v1.1, quantized 4-bit versions, etc.).
- Training Module:
– Folder: “train”
– Purpose: Contains scripts for multiple training strategies, including standard Maximum Likelihood Estimation (MLE) training and new LLM training schemes based on code quality scoring. Includes gradient splitting for memory efficiency.
- Supporting Components & Resources:
– “requirements.txt” for dependency management
– “README.md” and “_pic” (images for data generation and training flows) to document system flows and citation/paper references

##### Relationships and Interactions
- The Data Generation module feeds into both Training (providing the large labeled dataset) and benchmarking (if generating new test cases).
- The trained LLM models are then used in the Inference module to generate RTL code when provided with a prompt.
- The Inference scripts have different flows based on the model variant (e.g., Deepseek, GPTQ-4bit) and include special post-processing steps (like handling the “endmodule” token).
- There is a feedback loop in the training methodology which incorporates code quality scoring into the model training, as depicted in the training flow in the README.

##### Architectural Patterns & Technologies
- Modular design: The project clearly divides responsibilities among data generation, benchmarking, and training.
- Pipeline flow: Each module demonstrates a sequential or “stage‐based” flow (e.g., data generation stages described in Figure 1 and training scheme in Figure 2).
- Integration with external packages: For inference, the project leverages external packages like ctransformers and HuggingFace Transformers to load and run the models.
- GPU/CPU considerations: Handling inference on different hardware (e.g. using GPU for standard models or CPU for the gguf quantized version).

– “Data Generation Module” that outputs to both “Dataset Repository” and gets consumed during Training.
– “Training Module” that uses the dataset to fine-tune various LLM models (list the four model variants).
– “Inference/Benchmarking Module” that includes scripts such as “test_on_rtllm.py” and “test_on_verilog-eval.py” along with pre-/post-processing blocks.
- Use notes or side annotations to indicate the use of external libraries (HuggingFace Transformers, ctransformers, deepspeed) and important configurations (GPU memory optimizations, use of quantization).
- Every component (folder/problem domain) is represented, even if briefly—this helps capture the entire project’s scope.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Generation Module"
        DG1("Instruction Generator"):::module
        DG2("Prompt Templates"):::module
        DG3("Utilities"):::module
        DG4("Dataset Repository"):::dataset
    end

    subgraph "Training Module"
        TR1("MLE Training"):::module
        TR2("Scoring Training"):::module
        TR3("Gradient Splitting"):::module
        TM("Trained Model"):::module
    end

    subgraph "Inference/Benchmarking Module"
        IB1("RTLLM Benchmark"):::module
        IB2("Verilog Eval Benchmark"):::module
    end

    subgraph "Dependencies & Documentation"
        DEP1("Requirements"):::doc
        DEP2("README"):::doc
        DEP3("Images"):::doc
    end

    EL("External Libraries: Transformers, ctransformers, deepspeed"):::lib

    %% Data Generation Flow
    DG1 -->|"outputs"| DG4
    DG2 -.->|"supplies"| DG1
    DG3 -.->|"assists"| DG1

    %% Training Flow
    DG4 -->|"dataset_used"| TR1
    DG4 -->|"dataset_used"| TR2
    DG4 -->|"dataset_used"| TR3
    TR1 --> TM
    TR2 --> TM
    TR3 --> TM

    %% Inference Flow
    TM -->|"deploys"| IB1
    TM -->|"deploys"| IB2
    DG4 -->|"test_cases"| IB1

    %% External Libraries Integration
    EL -->|"supports"| TM
    EL -->|"supports"| IB1
    EL -->|"supports"| IB2

    %% Click Events
    click DG1 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/data_generation/instruction_gen.py"
    click DG2 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/data_generation/p_example.txt"
    click DG3 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/data_generation/utils.py"
    click DG4 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/dataset/Resyn27k.json"
    click TR1 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/train/mle.py"
    click TR2 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/train/mle_scoring.py"
    click TR3 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/train/mle_scoring_grad_split.py"
    click IB1 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/benchmark_inference/test_on_rtllm.py"
    click IB2 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/benchmark_inference/test_on_verilog-eval.py"
    click DEP1 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/requirements.txt"
    click DEP2 "https://github.com/hkust-zhiyao/rtl-coder/blob/main/README.md"
    click DEP3 "https://github.com/hkust-zhiyao/rtl-coder/tree/main/_pic"

    %% Styles
    classDef module fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef dataset fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef doc fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef lib fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
