# limbo018/dreamplace architecture

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

- Interactive diagram: https://gitdiagram.com/limbo018/dreamplace
- Repository: https://github.com/limbo018/dreamplace

## Overview

##### Project Type and Purpose
- DREAMPlace is a VLSI placement tool that leverages deep learning toolkits for efficient placement, running on both CPU and GPU.
- Its purpose is to accelerate global and detailed placement computations (e.g., legalization, density mapping, wirelength computation), integrating deep learning framework support (PyTorch) and GPU/CUDA-accelerated operations.
- The README explains that the tool achieves significant speedups over analogous CPU implementations and includes features such as multi-threading and flexible configuration.

##### Analysis of the File Structure
- Top-Level Files: The repository includes top-level files like CMakeLists.txt, Dockerfile, LICENSE, README.md, and requirements.txt – showing that the project is built using CMake (with custom modules in the “cmake” directory) and can be run in Docker.
- The “dreamplace” Directory: Contains the core Python modules (Placer.py, BasicPlace.py, etc.) as well as a “configurations” and parameter definitions. This represents the high-level interface.
- The “dreamplace/ops” Directory: Contains numerous subdirectories (e.g., abacus_legalize, adjust_node_area, dct, density_map, etc.) that house specialized, performance-critical operations implemented in C++, CUDA, and Python bindings. These components form the low-level computational engine.
- Benchmarks and Testing: Directories such as “benchmarks”, “test”, and “unittest” indicate that there are comprehensive automated tests, unit tests, and benchmark scripts for evaluating functionality and performance.
- Third-Party Dependencies: A “thirdparty” directory and inclusion of git submodules (e.g., Limbo, Flute, OpenTimer, cub, and munkres-cpp) indicate that several external libraries and tools are integrated into the build.
- Build & Deployment: The existence of Dockerfile and detailed CMake configuration files (including customized modules under “cmake”) suggests that both containerized and native build processes are supported.

##### Key Components
- User Interface / Configuration Layer:
- JSON Configuration Files (e.g., test/ispd2005/adaptec1.json) and command-line driven entry via dreamplace/Placer.py.
- Python driver scripts that process user input and settings.

- Core Placement Engine:
- High-level Python modules (in dreamplace) that serve as orchestrators between inputs, optimization routines, and calling math/placement algorithms.
- Classes like Placer, PlaceDB, and others act as control centers for placement algorithms.

- Ops (GPU/CPU Accelerated Operations) Layer:
- A large collection of specialized “ops” modules (abacus_legalize, adjust_node_area, dct, density_map, global_swap, etc.) implemented in lower-level C++ and CUDA.
- These are designed to perform computational kernels (e.g., wirelength computation, density map generation, legalization) and are exposed to Python using bindings (possibly via pybind11).

- Integration with External Libraries:
- Dependencies such as PyTorch, Boost, CUDA, and external placement/timing tools like NTUPlace3, OpenTimer, and others are integrated via submodules and specified in the CMake build system.
- There is also an “ops/utility” module that connects to third-party libraries such as CUB for GPU-accelerated operations.

- Build System and Environment:
- CMake as the core build system, with CMakeLists and custom scripts in “cmake”.
- Dockerfile for containerized builds and deployment.
- Unit testing and regression testing support from “unittest” and “test” directories.

##### Relationships and Interactions
- The high-level Python interface (Placer.py) reads configuration files and orchestrates placement flows.
- It calls into the core placement engine (classes in dreamplace) which, in turn, invokes various ops from the “ops” subdirectories.
- The ops modules perform low-level operations either on CPU (with multi-threading) or on GPU (using CUDA kernels), with computation results fed back into the overall placement optimization.
- Data flow passes from input files (DEF/LEF/Bookshelf .aux JSON config files) through pre-processing, core placement optimization, and then output results.
- Dependencies from third-party modules and external libraries are used during operations such as timing analysis (OpenTimer) or estimation (Flute).

##### Architectural Patterns and Design Principles
- Separation of concerns is evident: high-level orchestration in Python versus low-level computational kernels in the “ops” directories.
- Modularity is maintained by isolating each placement operation (abacus_legalize, density mapping, etc.) into independent CMake-buildable modules.
- Extensibility is enabled via Python binding, making it easier to integrate new placement algorithms and optimizers.
- The system supports both CPU and GPU execution pathways, with configurable build options (via CMake options and JSON configuration parameters).

##### Specific Elements
- “User Interface / Config” (Python Placer entry, JSON config)
- “Core Placement Engine” (PlaceDB, Placer classes, Timer, etc.)
- “Ops Modules / Computational Kernels” (listing a few examples like abacus_legalize, adjust_node_area, dct, density_map, etc.)
- “Third-Party Libraries & Submodules” (Limbo, Flute, OpenTimer, etc.)
- “Build System” (CMake, Docker)
- “Testing & Benchmarking” (test and unittest directories)
- Input flows from the configuration files to the Placer.
- The Placer invokes various ops.
- Ops call into GPU kernels or CPU routines.
- Results propagate back to form final placement outputs.
- Annotations for technologies/frameworks:
- Python, C++, CUDA, CMake, Docker, PyTorch.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface / Configuration Layer
    UI_Conf["JSON Config Files"]:::ui
    UI_Entry["Placer.py (Entry)"]:::ui

    %% Core Placement Engine
    Core_Basic["BasicPlace.py"]:::core
    Core_DB["PlaceDB.py"]:::core
    Core_Timer["Timer.py"]:::core
    Core_Nesterov["NesterovAcceleratedGradientOptimizer.py"]:::core
    Core_Nonlinear["NonLinearPlace.py"]:::core
    Core_Params["Params.py"]:::core

    %% Ops Modules / Computational Kernels
    Ops_Main["Ops Directory (dreamplace/ops)"]:::ops
    Ops_Abacus["abacus_legalize"]:::ops
    Ops_Adjust["adjust_node_area"]:::ops
    Ops_DCT["dct"]:::ops
    Ops_Density["density_map"]:::ops
    Ops_Global["global_swap"]:::ops

    %% Integration with External Libraries
    Ext_Thirdparty["Third-Party Dependencies"]:::external
    Ext_Torch["TorchExtension (CMake)"]:::external

    %% Build System & Environment
    Build_CMake["CMakeLists.txt"]:::build
    Build_CMakeDir["cmake/ Directory"]:::build
    Build_Docker["Dockerfile"]:::build

    %% Testing & Benchmarking
    Test_Benchmarks["benchmarks/ Directory"]:::test
    Test_Unittest["unittest/ Directory"]:::test

    %% Connections for User Interface
    UI_Conf -->|"configures"| UI_Entry

    %% Connections from UI to Core Placement Engine
    UI_Entry -->|"orchestrates"| Core_Basic

    %% Core internal flow
    Core_Basic -->|"passes to"| Core_DB
    Core_DB -->|"passes to"| Core_Timer
    Core_Timer -->|"passes to"| Core_Nesterov
    Core_Nesterov -->|"passes to"| Core_Nonlinear
    Core_Nonlinear -->|"passes to"| Core_Params

    %% Core calls Ops Modules
    Core_Basic -->|"calls"| Ops_Main

    %% Ops Module details
    Ops_Main --> Ops_Abacus
    Ops_Main --> Ops_Adjust
    Ops_Main --> Ops_DCT
    Ops_Main --> Ops_Density
    Ops_Main --> Ops_Global

    %% Core integration with External Libraries
    Core_Basic -->|"integrates"| Ext_Thirdparty
    Core_Params -->|"integrates"| Ext_Torch

    %% Build System relationships
    Build_CMake --> Build_CMakeDir
    Build_CMakeDir --> Build_Docker
    Build_CMakeDir -->|"builds"| Ops_Main
    Build_Docker -->|"deploys"| UI_Entry

    %% Testing & Benchmarking flow
    Test_Benchmarks -->|"tests"| Core_Basic
    Test_Unittest -->|"tests"| Core_Basic

    %% Click Events for User Interface / Configuration
    click UI_Entry "https://github.com/limbo018/dreamplace/blob/master/dreamplace/Placer.py"
    click UI_Conf "https://github.com/limbo018/dreamplace/blob/master/test/ispd2005/adaptec1.json"

    %% Click Events for Core Placement Engine
    click Core_Basic "https://github.com/limbo018/dreamplace/blob/master/dreamplace/BasicPlace.py"
    click Core_DB "https://github.com/limbo018/dreamplace/blob/master/dreamplace/PlaceDB.py"
    click Core_Timer "https://github.com/limbo018/dreamplace/blob/master/dreamplace/Timer.py"
    click Core_Nesterov "https://github.com/limbo018/dreamplace/blob/master/dreamplace/NesterovAcceleratedGradientOptimizer.py"
    click Core_Nonlinear "https://github.com/limbo018/dreamplace/blob/master/dreamplace/NonLinearPlace.py"
    click Core_Params "https://github.com/limbo018/dreamplace/blob/master/dreamplace/Params.py"

    %% Click Events for Ops Modules
    click Ops_Main "https://github.com/limbo018/dreamplace/tree/master/dreamplace/ops/"
    click Ops_Abacus "https://github.com/limbo018/dreamplace/tree/master/dreamplace/ops/abacus_legalize/"
    click Ops_Adjust "https://github.com/limbo018/dreamplace/tree/master/dreamplace/ops/adjust_node_area/"
    click Ops_DCT "https://github.com/limbo018/dreamplace/tree/master/dreamplace/ops/dct/"
    click Ops_Density "https://github.com/limbo018/dreamplace/tree/master/dreamplace/ops/density_map/"
    click Ops_Global "https://github.com/limbo018/dreamplace/tree/master/dreamplace/ops/global_swap/"

    %% Click Events for Integration with External Libraries
    click Ext_Thirdparty "https://github.com/limbo018/dreamplace/tree/master/thirdparty/"
    click Ext_Torch "https://github.com/limbo018/dreamplace/blob/master/cmake/TorchExtension.cmake"

    %% Click Events for Build System & Environment
    click Build_CMake "https://github.com/limbo018/dreamplace/blob/master/CMakeLists.txt"
    click Build_CMakeDir "https://github.com/limbo018/dreamplace/tree/master/cmake/"
    click Build_Docker "https://github.com/limbo018/dreamplace/tree/master/Dockerfile"

    %% Click Events for Testing & Benchmarking
    click Test_Benchmarks "https://github.com/limbo018/dreamplace/tree/master/benchmarks/"
    click Test_Unittest "https://github.com/limbo018/dreamplace/tree/master/unittest/"

    %% Styling definitions
    classDef ui fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef ops fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef build fill:#e6e6fa,stroke:#9932cc,stroke-width:2px;
    classDef test fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
```
