# taichi-dev/taichi architecture

> Architecture diagram of the GitHub repository taichi-dev/taichi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taichi-dev/taichi
- Repository: https://github.com/taichi-dev/taichi

## Overview

This repository is the full Taichi Lang stack, organized as a hybrid Python + C++ monorepo around a compiled runtime for numerical computing.

#### High-level architecture

The repo has three major layers:

1. **Python-facing language layer**
   - The `python/taichi` package is the user API.
   - It provides the embedded DSL, decorators like kernels/functions, field and ndarray abstractions, AOT export helpers, UI wrappers, profiling, sparse data utilities, and example programs.
   - This layer is what end users import from Python.

2. **Native compiler/runtime core**
   - The `taichi/` C++ tree is the engine behind Taichi.
   - It contains the IR, optimization/transformation passes, backends, runtime implementations, device abstractions, JIT compilation, sparse structures, AOT module support, and Python bindings/export hooks.

3. **Interoperability and integration layers**
   - `c_api/` exposes a stable C/C++ API for embedding Taichi in native applications.
   - `taichi/ui` and `python/taichi/ui` provide the rendering/UI system.
   - `tests/`, `benchmarks/`, `cpp_examples/`, and `python/taichi/examples/` are validation and usage surfaces rather than core engine code.

#### Main execution path

The central data flow is:

**Python user code**
→ parsed/transformed by the Python frontend
→ lowered into Taichi IR
→ optimized by compiler passes
→ translated into backend-specific code
→ executed by a runtime on CPU/GPU devices
→ results flow back into Python, UI, or AOT artifacts.

More concretely:

##### 1) Python frontend and DSL
The `python/taichi/lang` subtree is the frontend language implementation:
- AST analysis and transformation live under `python/taichi/lang/ast`.
- Kernels, functions, expressions, matrices, fields, ndarrays, SNodes, and runtime helpers are implemented here.
- The frontend converts Python syntax into an internal Taichi representation and prepares kernel launches, argument marshalling, and type checks.

This layer is intentionally thin relative to the native core: it provides the Pythonic programming model and defers heavy compilation/execution to C++.

##### 2) C++ IR and compiler pipeline
The `taichi/ir`, `taichi/transforms`, and `taichi/analysis` directories form the compiler pipeline.

- `taichi/ir` defines the core intermediate representation, statements, expressions, control flow, types, SNodes, meshes, and offloaded task structures.
- `taichi/analysis` implements program analyses used by optimization and lowering passes, such as alias analysis, statement gathering, read/write analysis, and off-line cache key generation.
- `taichi/transforms` contains the major compiler passes: type checking, lowering, constant folding, simplification, inlining, loop transformations, block-local/thread-local optimizations, AD-specific transforms, access lowering, and offload compilation.

This is the “compiler core” where Python-facing kernels become optimized Taichi IR and then backend-ready offloaded tasks.

##### 3) Program/runtime orchestration
The `taichi/program` and `taichi/runtime` areas manage execution state and launches.

- `taichi/program` contains the logical program model: kernels, functions, launch contexts, graphs, ndarrays, textures, sparse matrices, and profiler integration.
- `taichi/runtime` contains backend-specific runtime implementations for CPU, CUDA, AMDGPU, Metal, Vulkan, OpenGL, DX12, and graphics-oriented runtime paths.
- `taichi/compilation_manager` coordinates kernel compilation and caching.

This layer bridges compilation output with live device execution and resource management.

##### 4) Hardware abstraction and backend drivers
The `taichi/rhi` directory is the low-level rendering/hardware interface boundary.

It provides device, context, allocator, driver, and interop implementations for:
- CPU
- CUDA
- AMDGPU
- Vulkan
- Metal
- OpenGL
- DX / DX12
- interop paths such as Vulkan-CPU and Vulkan-CUDA

The `rhi` layer is a key architectural boundary: above it, the runtime speaks Taichi concepts; below it, the code talks in terms of platform/device APIs, command submission, memory pools, and backend capabilities.

##### 5) Backend-specific code generation
The `taichi/codegen` subtree specializes the compiler output per target:
- `cpu`
- `cuda`
- `amdgpu`
- `dx12`
- `llvm`
- `spirv`

This is where IR gets lowered into LLVM IR, SPIR-V, or backend-specific kernels depending on the target architecture. The LLVM path is especially important for CPU execution and some offline/AOT flows; SPIR-V is central for Vulkan and graphics-oriented targets.

#### Important subsystems

##### Python package surface
The Python package is not just bindings; it is a significant part of the product:
- `python/taichi/lang`: user language runtime and AST transformation
- `python/taichi/aot`: ahead-of-time export tooling
- `python/taichi/ui`: GUI and rendering-facing APIs
- `python/taichi/linalg`, `python/taichi/math`, `python/taichi/sparse`, `python/taichi/graph`, `python/taichi/profiler`: higher-level libraries built on the core runtime

These modules are consumer-facing and provide the “Taichi experience” in Python.

##### AOT pipeline
Ahead-of-time compilation is a first-class subsystem:
- Python-side export lives in `python/taichi/aot`
- C++ module builder/loader logic is in `taichi/aot` and runtime-specific AOT implementations under `taichi/runtime/*/`
- There are tests for AOT across LLVM, Vulkan, OpenGL, DX12, and graphics backends

This subsystem is a separate architectural path from pure JIT execution:
- JIT path: Python → compile at runtime → device execution
- AOT path: Python or C++ export → serialized module → later load/run in a target runtime

##### UI and visualization
The UI stack is split across Python and C++:
- Python API: `python/taichi/ui`
- Native rendering/windowing: `taichi/ui`
- Two broad styles exist:
  - general GUI/windowing
  - `ggui`, a graphics-oriented renderer that works with the native rendering backends

This subsystem depends heavily on platform window systems, graphics APIs, and shader assets.

##### C API
The `c_api` subtree exposes a stable ABI for native integration. It is a separate boundary from the Python package and is intended for embedding Taichi into non-Python applications. It includes:
- public headers
- backend-specific implementation files
- generated docs
- compatibility and behavior tests

This is important architecturally because it lets external applications consume Taichi without going through Python.

#### Data and control flow boundaries

##### Frontend boundary
The transition from Python to C++ is the major language boundary:
- Python code defines kernels, fields, and structures.
- The frontend transforms those constructs into internal IR and launch metadata.
- The native side takes over for optimization and execution.

##### Compilation boundary
Within native code, the compiler pipeline is separated from execution:
- IR construction and transforms are pure compiler concerns.
- Codegen emits target-specific artifacts.
- Runtime components own resource lifetimes, kernel dispatch, caching, and execution synchronization.

##### Device boundary
The backend/device boundary is explicit through `rhi`:
- memory allocation, command queues, GPU context setup, and platform drivers are abstracted behind device interfaces.
- backend runtimes and program implementations use those abstractions rather than calling graphics or compute APIs directly.

##### Serialization boundary
AOT introduces a serialized module boundary:
- exported modules contain kernels, graphs, and metadata.
- loaders reconstruct runtime state in a backend-specific way.

#### Supporting systems

##### Tests
Testing is extensive and mirrors the architecture:
- `tests/python` validates Python-facing language behavior and backend semantics.
- `tests/cpp` validates compiler, runtime, RHI, AOT, IR, and transforms.
- `c_api/tests` validates the external C API.
- `benchmarks` and `misc/baselines` provide performance and regression coverage.

The test layout is a good guide to the repository’s subsystem boundaries.

##### Build and packaging
The project is built as a mixed-language system:
- top-level `CMakeLists.txt` drives the C++ build
- `setup.py`, `pyproject.toml`, and `python/` package files support Python distribution
- GitHub Actions workflows cover CI, release, performance, cache sync, and multi-platform builds
- `external/` vendors third-party dependencies such as LLVM-related components, Vulkan headers, GLFW, imgui, Eigen, googletest, spdlog, and SPIR-V tooling

#### How to draw the architecture

A useful diagram would show these layers and flows:

- **User code / examples / tests**
  → **Python Taichi API**
  → **AST transformation and kernel lowering**
  → **Taichi IR + analysis + transforms**
  → **backend codegen**
  → **runtime/program execution**
  → **RHI device layer**
  → **platform APIs / CPU / CUDA / Vulkan / Metal / OpenGL / DX12 / AMDGPU**

Side branches should include:
- **AOT export/import** flowing from Python and native module builders into serialized modules and backend loaders
- **UI/ggui** consuming runtime data and using graphics backends for visualization
- **C API** exposing native integration independent of Python
- **Benchmarks/tests** validating specific layers rather than being part of the runtime path

In short, Taichi is architected as a compiler + runtime platform for a Python-embedded parallel language, with clear separations between frontend syntax, core IR/compiler passes, backend code generation, device abstraction, and optional AOT/UI/C-API integration.

Main entry points: [`taichi/runtime`](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/runtime) (Runtime backends), [`tests`](https://github.com/taichi-dev/taichi/tree/HEAD/tests) (Tests), [`taichi/program`](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/program) (Program runtime), [`python/taichi`](https://github.com/taichi-dev/taichi/tree/HEAD/python/taichi) (Taichi API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Python API"
  user_code["User code<br/>entrypoint"]
  python_api["Taichi API<br/>python package"]
  python_lang["Language core<br/>frontend"]
  python_aot["AOT export<br/>python subsystem"]
  python_ui["Python UI<br/>python subsystem"]
  python_math["Python libraries<br/>python libs"]
end

subgraph "Native core"
  compiler_ir["Taichi IR<br/>ir core"]
  compiler_analysis["Analysis"]
  compiler_transforms["Transforms<br/>compiler passes"]
  codegen["Codegen"]
  program_runtime["Program runtime<br/>execution manager"]
  compilation_mgr["Compile manager<br/>jit cache"]
  runtime_backends["Runtime backends"]
  rhi["RHI layer<br/>device abstraction"]
  aot_native["AOT modules<br/>native AOT"]
  ui_native["Native UI<br/>graphics ui"]
end

subgraph "Integration"
  c_api["C API<br/>stable ABI"]
  tests["Tests<br/>validation"]
  benchmarks["Benchmarks<br/>perf"]
  examples_cpp["C++ examples"]
end

user_code -->|"imports"| python_api
python_api -->|"frontend"| python_lang
python_lang -->|"lowers to"| compiler_ir
compiler_ir -->|"analyzed by"| compiler_analysis
compiler_analysis -->|"drives"| compiler_transforms
compiler_transforms -->|"emits"| codegen
codegen -->|"launches"| runtime_backends
runtime_backends -->|"uses"| rhi
compilation_mgr -->|"orchestrates"| codegen
program_runtime -->|"requests compile"| compilation_mgr
program_runtime -->|"executes on"| runtime_backends
python_aot -->|"exports to"| aot_native
aot_native -->|"loads in"| runtime_backends
python_ui -->|"wraps"| ui_native
ui_native -->|"renders via"| rhi
c_api -->|"embeds"| runtime_backends
tests -.->|"validates"| python_api
tests -.->|"validates"| compiler_ir
tests -.->|"validates"| runtime_backends
tests -.->|"validates"| aot_native
benchmarks -.->|"measures"| program_runtime
examples_cpp -.->|"demonstrates"| rhi

click user_code "https://github.com/taichi-dev/taichi/tree/master/python/taichi/examples"
click python_api "https://github.com/taichi-dev/taichi/tree/master/python/taichi"
click python_lang "https://github.com/taichi-dev/taichi/tree/master/python/taichi/lang"
click python_aot "https://github.com/taichi-dev/taichi/tree/master/python/taichi/aot"
click python_ui "https://github.com/taichi-dev/taichi/tree/master/python/taichi/ui"
click python_math "https://github.com/taichi-dev/taichi/tree/master/python/taichi/linalg"
click compiler_ir "https://github.com/taichi-dev/taichi/tree/master/taichi/ir"
click compiler_analysis "https://github.com/taichi-dev/taichi/tree/master/taichi/analysis"
click compiler_transforms "https://github.com/taichi-dev/taichi/tree/master/taichi/transforms"
click codegen "https://github.com/taichi-dev/taichi/tree/master/taichi/codegen"
click program_runtime "https://github.com/taichi-dev/taichi/tree/master/taichi/program"
click compilation_mgr "https://github.com/taichi-dev/taichi/tree/master/taichi/compilation_manager"
click runtime_backends "https://github.com/taichi-dev/taichi/tree/master/taichi/runtime"
click rhi "https://github.com/taichi-dev/taichi/tree/master/taichi/rhi"
click aot_native "https://github.com/taichi-dev/taichi/tree/master/taichi/aot"
click ui_native "https://github.com/taichi-dev/taichi/tree/master/taichi/ui"
click c_api "https://github.com/taichi-dev/taichi/tree/master/c_api"
click tests "https://github.com/taichi-dev/taichi/tree/master/tests"
click benchmarks "https://github.com/taichi-dev/taichi/tree/master/benchmarks"
click examples_cpp "https://github.com/taichi-dev/taichi/tree/master/cpp_examples"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class user_code,python_api,python_lang,python_aot,python_ui,python_math toneBlue
class compiler_ir,compiler_analysis,compiler_transforms,codegen,program_runtime,compilation_mgr,runtime_backends,rhi,aot_native,ui_native toneAmber
class c_api,tests,benchmarks,examples_cpp toneMint
```

## Components

### Python API

User-facing Python package, DSL, and helpers

- [User code](https://github.com/taichi-dev/taichi/tree/HEAD/python/taichi/examples): entrypoint · Applications and scripts that import Taichi and define kernels · `python/taichi/examples`
- [Taichi API](https://github.com/taichi-dev/taichi/tree/HEAD/python/taichi): python package · Main Python package surface for the embedded DSL and runtime-facing APIs · `python/taichi`
- [Language core](https://github.com/taichi-dev/taichi/tree/HEAD/python/taichi/lang): frontend · Kernel/function implementation, fields, expressions, SNodes, runtime helpers, and AST tooling · `python/taichi/lang`
- [AOT export](https://github.com/taichi-dev/taichi/tree/HEAD/python/taichi/aot): python subsystem · Python-side ahead-of-time export and module conventions · `python/taichi/aot`
- [Python UI](https://github.com/taichi-dev/taichi/tree/HEAD/python/taichi/ui): python subsystem · Windowing, GUI, canvas, scene, and rendering-facing Python wrappers · `python/taichi/ui`
- [Python libraries](https://github.com/taichi-dev/taichi/tree/HEAD/python/taichi/linalg): python libs · Higher-level math, linalg, sparse, profiler, graph, and algorithm helpers · `python/taichi/linalg`

### Native core

C++ compiler, runtime, and low-level platform layers

- [Taichi IR](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/ir): ir core · Core intermediate representation, statements, types, control flow, and visitors · `taichi/ir`
- [Analysis](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/analysis): compiler analysis · IR analyses supporting lowering, optimization, and cache keys · `taichi/analysis`
- [Transforms](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/transforms): compiler passes · Type checking, lowering, simplification, inlining, loop transforms, and offload compilation · `taichi/transforms`
- [Codegen](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/codegen): backend codegen · Target-specific lowering for CPU, CUDA, AMDGPU, DX12, LLVM, and SPIR-V · `taichi/codegen`
- [Program runtime](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/program): execution manager · Kernel/program objects, launch contexts, graphs, ndarrays, textures, and profiling integration · `taichi/program`
- [Compile manager](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/compilation_manager): jit cache · Coordinates kernel compilation and caching · `taichi/compilation_manager`
- [Runtime backends](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/runtime): runtime · Backend-specific execution paths for CPU, CUDA, AMDGPU, Metal, Vulkan, OpenGL, DX12, and graphics · `taichi/runtime`
- [RHI layer](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/rhi): device abstraction · Device, driver, allocator, interop, and platform-facing hardware abstraction boundary · `taichi/rhi`
- [AOT modules](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/aot): native AOT · Native module builder and loader for serialized kernels and graphs · `taichi/aot`
- [Native UI](https://github.com/taichi-dev/taichi/tree/HEAD/taichi/ui): graphics ui · C++ windowing and graphics-oriented renderer, scene, and GUI implementation · `taichi/ui`

### Integration

C API, UI, examples, tests, and benchmarks

- [C API](https://github.com/taichi-dev/taichi/tree/HEAD/c_api): stable ABI · Stable native embedding API with backend-specific implementations and headers · `c_api`
- [Tests](https://github.com/taichi-dev/taichi/tree/HEAD/tests): validation · Python and C++ validation suites covering compiler, runtime, AOT, RHI, and API behavior · `tests`
- [Benchmarks](https://github.com/taichi-dev/taichi/tree/HEAD/benchmarks): perf · Microbenchmarks and performance regression harnesses · `benchmarks`
- [C++ examples](https://github.com/taichi-dev/taichi/tree/HEAD/cpp_examples): examples · Native usage examples, including RHI and AOT samples · `cpp_examples`

## Connections

- User code → Taichi API: imports · User scripts use the Python package surface
- Taichi API → Language core: frontend · Public API delegates language semantics and kernel definition to the frontend
- Language core → Taichi IR: lowers to · AST and kernel constructs become Taichi IR
- Taichi IR → Analysis: analyzed by · IR feeds program analyses used by optimization and lowering
- Analysis → Transforms: drives · Analyses inform transform decisions and legality checks
- Transforms → Codegen: emits · Lowered IR is specialized for target backends
- Codegen → Runtime backends: launches · Generated kernels are executed by backend runtimes
- Runtime backends → RHI layer: uses · Runtimes rely on the hardware abstraction layer for device access
- Compile manager → Codegen: orchestrates · Compilation manager coordinates kernel compilation and reuse
- Program runtime → Compile manager: requests compile · Program objects trigger compilation and cache lookup
- Program runtime → Runtime backends: executes on · Program state and launches are carried out by backend runtimes
- AOT export → AOT modules: exports to · Python-side export helpers produce native AOT modules
- AOT modules → Runtime backends: loads in · Serialized modules are loaded and run by backend runtimes
- Python UI → Native UI: wraps · Python GUI and scene APIs wrap the native UI system
- Native UI → RHI layer: renders via · Native UI uses device and graphics APIs through RHI
- C API → Runtime backends: embeds · External native applications call into backend runtimes through the stable API
- Tests → Taichi API: validates · Python tests exercise the public package and DSL behavior
- Tests → Taichi IR: validates · C++ tests cover IR construction and correctness
- Tests → Runtime backends: validates · Backend and runtime behavior is covered by tests
- Tests → AOT modules: validates · AOT save/load and compatibility flows are tested
- Benchmarks → Program runtime: measures · Benchmarks target execution and compilation performance
- C++ examples → RHI layer: demonstrates · Native examples show direct backend and rendering usage
