project_structure

LuisaCompute Project Structure & Architecture

Executive Summary

LuisaCompute is a high-performance, cross-platform GPU computing framework. The codebase follows a layered architecture: Core → AST/IR → DSL/Runtime → Backends. Source lives in src/; public headers in include/luisa/. The project uses dual build systems (CMake + XMake) and supports multiple language frontends (C++, Python, Rust).

---

Top-Level Directory Map

src/
├── api/           # C API & runtime API layer
├── ast/           # Abstract Syntax Tree (DSL expression/statement/type system)
├── backends/      # Backend plugins (CUDA, DX, Metal, CPU, Vulkan, HIP, etc.)
├── clangcxx/      # C++ shader compiler frontend (Clang-based)
├── core/          # Foundation: types, math, logging, platform, STL wrappers
├── dsl/           # Embedded C++ DSL (kernel/callable authoring)
├── ext/           # Third-party dependencies (git submodules)
├── gui/           # Windowing, ImGui, framerate
├── ir/            # IR translation layer (AST↔IR, transforms)
├── osl/           # Open Shading Language parser support
├── py/            # Python bindings (pybind11 + pure Python luisa package)
├── runtime/       # Unified runtime: device, buffer, image, stream, RTX, raster
├── rust/          # Rust workspace: IR, backend impl, CPU backend, remote
├── tensor/        # Tensor operations & compute graph (fallback kernels)
├── tests/         # Test suites: unit tests, integration tests, examples
├── vstl/          # Virtual STL (custom containers, allocators, hashes)
└── xir/           # Extended IR (SSA, basic blocks, passes, translators)

include/luisa/     # Public headers mirroring src/ module layout

---

Module Deep Dive

src/core/ — Foundation Layer

Purpose: Platform abstractions, math, logging, binary I/O, dynamic modules.

Public headers: include/luisa/core/*

---

src/vstl/ — Virtual STL

Purpose: High-performance custom containers and utilities not covered by core/stl.

Public headers: include/luisa/vstl/* (hash maps, arenas, lockfree queues, ranges)

---

src/ast/ — Abstract Syntax Tree

Purpose: Represents DSL kernels/callables as a tree. The DSL traces C++ lambdas into AST nodes.

Public headers: include/luisa/ast/* (function_builder.h, type.h, expression.h, statement.h, op.h)

---

src/xir/ — Extended IR (Next-Gen Compiler IR)

Purpose: SSA-based IR with basic blocks, instructions, and optimization passes. Receives AST via ast2xir translator.

Key classes: Module, Function, BasicBlock, Instruction, Value, Use, Builder

Public headers: include/luisa/xir/*

---

src/ir/ — IR Bridge Layer

Purpose: Transforms between AST and an older JSON-serializable IR; also hosts high-level transforms.

Public headers: include/luisa/ir/*

---

src/dsl/ — Embedded Domain-Specific Language

Purpose: Allows writing GPU kernels in C++ via lambda tracing.

Public headers: include/luisa/dsl/* (syntax.h, sugar.h, func.h, struct.h, var.h)

---

src/runtime/ — Unified Runtime

Purpose: Resource management, command scheduling, device abstraction (RHI pattern).

Public headers: include/luisa/runtime/*

---

src/backends/ — Backend Plugins

Architecture: Each backend is a dynamically loaded plugin (luisa-backend-<name>.dll/.so). Loaded by Context at runtime.

Backend internal pattern: Each backend implements DeviceInterface (from runtime/rhi/) and provides:

• Codegen: AST/XIR → backend shader source (CUDA C++, HLSL, MSL, SPIR-V, etc.)
• Compiler: Native shader compilation (NVRTC, DXC, etc.)
• Resources: Backend-specific buffer/image/accel implementations
• Commands: Command encoder translating RHI commands to API calls

---

src/rust/ — Rust Workspace

Purpose: IR implementation, CPU backend codegen, and language bindings.

Integration: Rust crates are built via CMake/Cargo interop and linked into C++ targets.

---

src/api/ — C & Runtime API

Purpose: Stable C API for external language bindings and runtime services.

Public headers: include/luisa/api/*

---

src/py/ — Python Frontend

Purpose: Python bindings and pure-Python wrapper library.

---

src/tensor/ — Tensor & Compute Graph

Purpose: High-level tensor operations and automatic kernel generation.

Public headers: include/luisa/tensor/*

---

src/clangcxx/ — C++ Shader Compiler

Purpose: Compiles C++ code (not DSL) directly to GPU shaders using Clang/libTooling.

Public headers: include/luisa/clangcxx/*

---

src/osl/ — Open Shading Language

Purpose: Parses OSL bytecode (.oso) for shader interoperability.

Public headers: include/luisa/osl/*

---

src/gui/ — GUI & Presentation

Purpose: Cross-platform windowing and ImGui integration.

Public headers: include/luisa/gui/*

---

src/ext/ — Third-Party Dependencies

All managed as git submodules.

---

src/tests/ — Test Suites

---

Build System Architecture

CMake (Primary)

• Root: src/CMakeLists.txt adds subdirectories in dependency order.
• Targets: Each module produces luisa-compute-<name> (static/shared library).
• Alias: luisa::compute interface target links all modules.
• Backends: Built as MODULE (plugins) named luisa-backend-<name>.
• Options: LUISA_COMPUTE_ENABLE_CUDA, _DX, _METAL, _CPU, _VULKAN, _HIP, _DSL, _RUST, etc.
• Install: luisa_compute_install(target) helper for consistent packaging.

XMake (Secondary)

• xmake.lua files in src/ and most subdirectories.
• Used by some developers for faster incremental builds.

Bootstrap Script

• bootstrap.py at repo root automates dependency installation and CMake configuration.

---

Compiler Pipeline Flow

User C++ DSL / Python
         │
         ▼
┌─────────────────┐
│   DSL Tracing   │  src/dsl/ — captures C++ lambdas into AST
│  (src/dsl/)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│       AST       │  src/ast/ — expression/statement tree
│  (src/ast/)     │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌──────────┐
│  XIR   │ │   IR     │  src/xir/ (new)  /  src/ir/ (legacy bridge)
│transl. │ │transl.   │
└───┬────┘ └────┬─────┘
    │           │
    ▼           ▼
┌─────────────────┐
│  Backend Codegen│  src/backends/<name>/ — AST/XIR → native shader source
│  + Compilation  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  GPU Execution  │  src/runtime/ — command submission via Stream
│  (src/runtime/) │
└─────────────────┘

Rust IR path: src/rust/luisa_compute_ir/ performs additional IR transforms (autodiff, DCE, SSA, vectorize) before backend codegen.

---

Public Header Organization (include/luisa/)

Headers mirror src/ modules. Key umbrella headers:

---

Key Design Patterns

1. RHI (Rendering Hardware Interface): src/runtime/rhi/ abstracts all GPU APIs into common interfaces.
2. Plugin Architecture: Backends are dynamic modules loaded at runtime by Context.
3. RAII Resources: All runtime objects (Buffer, Image, Stream, Accel) are move-only RAII handles.
4. Command-Based Execution: Work is encoded as Command objects batched into CommandLists and submitted to Streams.
5. DSL Tracing: Operator overloading and lambda capture build an AST at kernel definition time.
6. Dual IR: AST is the frontend tree; XIR is the SSA backend IR with optimization passes.
7. Rust + C++ Hybrid: Performance-critical IR and CPU backend use Rust; C++ handles API and DSL.

---

Naming Conventions

---

File Count Summary (approximate)

---

Maintenance Notes

• Adding a new backend: Create src/backends/<name>/, implement DeviceInterface, register in src/backends/CMakeLists.txt.
• Adding a new XIR pass: Add to src/xir/passes/, register in src/xir/CMakeLists.txt.
• Adding a new runtime resource: Define in src/runtime/rhi/resource.h, implement in each backend, expose in src/runtime/ and include/luisa/runtime/.
• The tensor/ module is currently opt-in and less mature than DSL/Runtime.
• clangcxx/ is experimental for full C++ shader compilation (not DSL tracing).