# llvm/polygeist architecture

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

- Interactive diagram: https://gitdiagram.com/llvm/polygeist
- Repository: https://github.com/llvm/polygeist

## Overview

##### Project type and purpose
- This is a compiler-toolchain project built as an MLIR/Clang plugin (“Polygeist”) that
- Defines a new MLIR dialect for C/C++ constructs (“polygeist” dialect),
- Provides passes to “raise” C to MLIR, optimize (affine/polyhedral/Ops transforms), and lower back to LLVM IR or CUDA/HIP,
- Includes optional integration with the “Polymer” polyhedral optimizer (Pluto/ISL backends),
- Ships command-line tools (cgeist, polygeist-opt, polymer), and a test suite driven by LLVM’s lit harness.

##### File structure
- Top‐level CMake files (+ cmake/modules) orchestrate building:
- /polygeist & lib/polygeist: dialect definitions (.td, .h) and implementation of passes, runtime wrappers, ExecutionEngine support for CUDA/ROCm, etc.
- llvm-project: submodule providing MLIR, Clang, LLVM core.
- tools/cgeist, tools/polygeist-opt, tools/polymer: distinct executables that invoke the plugin passes.
- test/: lit configuration and .mlir test cases for polygeist-opt and cgeist.
- tools/polymer: an optional, heavier polyhedral subsystem with its own includes, libs, tools, tests, and examples.

##### README for architecture hints
- Shows that Polygeist plugs into MLIR/Clang via CMake options, registers dialect + passes, and can be built standalone or as an external LLVM project.
- Mentions GPU backends, Polymer (Pluto/ISL), and test targets (check-polygeist-opt, check-cgeist, check-polymer).

a. External Dependencies
- LLVM Core (llvm‐project/llvm)
- Clang Frontend (llvm‐project/clang)
- MLIR Core (llvm‐project/mlir)
- Optional: Polly (llvm subproject) for ISL, or Pluto libraries for Polymer
b. Polygeist Core
- Dialect Registration (include/polygeist/Dialect.td → generated code)
- Passes (include/polygeist/Passes & lib/polygeist/Passes/*.cpp)
- ExecutionEngine Extensions (CudaRuntimeWrappers, RocmRuntimeWrappers)
c. Polymer Subsystem (tools/polymer)
- Its own dialect/transforms/plugins built via CMake hooks when POLYMER enabled
- Pluto/ISL backends under the hood
d. Tools / CLI
- cgeist → C/C++ → MLIR translator (uses ClangAST → MLIR polygeist dialect)
- polygeist-opt → MLIR optimizer: loads MLIR, runs polygeist passes, lowers to LLVM/DialectOps
- polymer-opt (or polymer-translate) → invokes polymer transformations
e. Code Generation & Runtime
- MLIR → LLVM IR lowering passes (ConvertPolygeistToLLVM, ConvertToOpaquePtr, etc.)
- JIT / ExecutionEngine (CPU or GPU backends)
- CUDA/ROCm runtime wrappers for barrier sync, memory, kernels
f. Tests / CI
- lit.cfg.py, lit.site.cfg.py.in drive test cases under test/ and tools/polymer/test/.

##### Architectural patterns & design principles
- Plugin architecture: dialect & pass registration via MLIR’s PassManager
- Layered compilation pipeline:
1. Frontend (ClangAST → MLIR polygeist dialect)
2. Raising/Canonicalization passes (polygeist)
3. Polyhedral transformations (optional polymer plugin)
4. Lowering passes (MLIR → LLVM dialect → LLVM IR)
5. Codegen & JIT/Runtime
- Modularity: separate CMake targets, clear dependency isolation (include vs lib vs tools)
- Extensibility: optional GPU and polymer features turned on via CMake flags

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        LLVM["LLVM Core"]:::external
        Clang["Clang Frontend"]:::external
        MLIR["MLIR Core"]:::external
    end

    %% Polygeist Core
    subgraph "Polygeist Core" 
        direction TB
        DialectTD["Dialect Definition (.td)"]:::core
        OpsDefs["Ops Definitions"]:::core
        DialectReg["Dialect Registration Header"]:::core
        PassesTD["Passes Declarations (.td/.h)"]:::core
        PassesUtils["Passes Utilities"]:::core
        PassesImpl["Passes Implementation"]:::core
        CoreImpl["Core Implementation (.cpp)"]:::core
        ExecExt["ExecutionEngine Extensions"]:::core
    end

    %% Polymer Subsystem
    subgraph "Polymer Subsystem" 
        direction TB
        PolymerInc["Polymer Includes"]:::polymer
        PolymerLib["Polymer Libraries"]:::polymer
        PolyOpt["polymer-opt"]:::polymer
        PolyTrans["polymer-translate"]:::polymer
    end

    %% CLI Tools
    subgraph "CLI Tools" 
        direction TB
        Cgeist["cgeist"]:::cli
        PGOpt["polygeist-opt"]:::cli
    end

    %% Pipeline Flow
    subgraph "Compilation Pipeline"
        direction TB
        Src["C/C++ Source"]:::artifact
        MLIRFile[".mlir File"]:::artifact
        OptStage["MLIR Optimization (polygeist)"]:::artifact
        PolyStage["Polyhedral Transform (optional)"]:::artifact
        LowerIR["Lower to LLVM IR"]:::artifact
        JIT["JIT/Runtime"]:::artifact
    end

    %% Test Harness
    subgraph "Tests / CI"
        direction TB
        PGTest["Polygeist Test Harness"]:::test
        PolymerTest["Polymer Test Harness"]:::test
    end

    %% Relationships
    Src -->|"cgeist"| MLIRFile
    MLIRFile -->|"polygeist-opt"| OptStage
    OptStage -->|"+Polymer"| PolyStage
    PolyStage -->|"lowering"| LowerIR
    LowerIR -->|"JIT" | JIT

    Cgeist -->|uses| DialectReg
    Cgeist -->|uses| PassesTD
    PGOpt -->|registers dialect/passes| DialectReg
    PGOpt -->|registers passes| PassesTD

    LLVM -->|provides infrastructure| MLIR
    Clang -->|frontend AST| Cgeist
    MLIR -->|core APIs| DialectTD
    MLIR -->|PassManager| PassesImpl

    DialectTD --> OpsDefs
    DialectReg --> CoreImpl
    PassesTD --> PassesImpl
    PassesUtils --> PassesImpl
    CoreImpl --> ExecExt

    PolymerInc --> PolymerLib
    PolymerLib --> PolyOpt
    PolymerLib --> PolyTrans
    PolyOpt --> PolyStage
    PolyTrans --> PolyStage

    JIT --> ExecExt

    PGTest -->|invokes| Cgeist
    PGTest -->|invokes| PGOpt
    PolymerTest -->|invokes| PolyOpt
    PolymerTest -->|invokes| PolyTrans

    %% Click Events
    click LLVM "https://github.com/llvm/polygeist/tree/main/llvm-project/llvm"
    click Clang "https://github.com/llvm/polygeist/tree/main/llvm-project/clang"
    click MLIR "https://github.com/llvm/polygeist/tree/main/llvm-project/mlir"
    click DialectTD "https://github.com/llvm/polygeist/blob/main/include/polygeist/Dialect.td"
    click OpsDefs "https://github.com/llvm/polygeist/blob/main/include/polygeist/Ops.h"
    click OpsDefs "https://github.com/llvm/polygeist/blob/main/include/polygeist/PolygeistOps.td"
    click DialectReg "https://github.com/llvm/polygeist/blob/main/include/polygeist/Dialect.h"
    click PassesTD "https://github.com/llvm/polygeist/blob/main/include/polygeist/Passes/Passes.td"
    click PassesTD "https://github.com/llvm/polygeist/blob/main/include/polygeist/Passes/Passes.h"
    click PassesUtils "https://github.com/llvm/polygeist/blob/main/include/polygeist/Passes/Utils.h"
    click PassesImpl "https://github.com/llvm/polygeist/blob/main/lib/polygeist/Passes/*.cpp"
    click PassesImpl "https://github.com/llvm/polygeist/blob/main/lib/polygeist/Passes/PassDetails.h"
    click CoreImpl "https://github.com/llvm/polygeist/blob/main/lib/polygeist/Dialect.cpp"
    click CoreImpl "https://github.com/llvm/polygeist/blob/main/lib/polygeist/Ops.cpp"
    click ExecExt "https://github.com/llvm/polygeist/blob/main/lib/polygeist/ExecutionEngine/CudaRuntimeWrappers.cpp"
    click ExecExt "https://github.com/llvm/polygeist/blob/main/lib/polygeist/ExecutionEngine/RocmRuntimeWrappers.cpp"
    click ExecExt "https://github.com/llvm/polygeist/blob/main/lib/polygeist/ExecutionEngine/PGORuntime.h"
    click Cgeist "https://github.com/llvm/polygeist/tree/main/tools/cgeist"
    click PGOpt "https://github.com/llvm/polygeist/blob/main/tools/polygeist-opt/polygeist-opt.cpp"
    click PolyOpt "https://github.com/llvm/polygeist/blob/main/tools/polymer/tools/polymer-opt/polymer-opt.cc"
    click PolyTrans "https://github.com/llvm/polygeist/blob/main/tools/polymer/tools/polymer-translate/polymer-translate.cc"
    click PolymerInc "https://github.com/llvm/polygeist/tree/main/tools/polymer/include/polymer"
    click PolymerLib "https://github.com/llvm/polygeist/tree/main/tools/polymer/lib"
    click PGTest "https://github.com/llvm/polygeist/blob/main/test/lit.cfg.py"
    click PGTest "https://github.com/llvm/polygeist/blob/main/test/lit.site.cfg.py.in"
    click PGTest "https://github.com/llvm/polygeist/blob/main/test/polygeist-opt/*.mlir"
    click PolymerTest "https://github.com/llvm/polygeist/blob/main/tools/polymer/test/lit.cfg.py"
    click PolymerTest "https://github.com/llvm/polygeist/blob/main/tools/polymer/test/lit.site.cfg.py.in"
    click PolymerTest "https://github.com/llvm/polygeist/blob/main/tools/polymer/test/polymer-opt/**/*.mlir"

    %% Styles
    classDef external fill:#CCE5FF,stroke:#1C3D5A,color:#1C3D5A
    classDef core fill:#D5F5E3,stroke:#196F3D,color:#196F3D
    classDef polymer fill:#FDEBD0,stroke:#D35400,color:#D35400
    classDef cli fill:#E8DAEF,stroke:#6C3483,color:#6C3483
    classDef artifact fill:#F2F3F4,stroke:#566573,color:#566573
    classDef test fill:#E5E7E9,stroke:#424949,color:#424949
```
