How taichi-dev/taichi works
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: runtime Runtime backends · tests Tests · program Program runtime · taichi Taichi API
Components 20
Python API
User-facing Python package, DSL, and helpers
- User code · Applications and scripts that import Taichi and define kernels
python/taichi/examples - Taichi API · Main Python package surface for the embedded DSL and runtime-facing APIs
python/taichi - Language core · Kernel/function implementation, fields, expressions, SNodes, runtime helpers, and AST tooling
python/taichi/lang - AOT export · Python-side ahead-of-time export and module conventions
python/taichi/aot - Python UI · Windowing, GUI, canvas, scene, and rendering-facing Python wrappers
python/taichi/ui - Python libraries · 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 · Core intermediate representation, statements, types, control flow, and visitors
taichi/ir - Analysis · IR analyses supporting lowering, optimization, and cache keys
taichi/analysis - Transforms · Type checking, lowering, simplification, inlining, loop transforms, and offload compilation
taichi/transforms - Codegen · Target-specific lowering for CPU, CUDA, AMDGPU, DX12, LLVM, and SPIR-V
taichi/codegen - Program runtime · Kernel/program objects, launch contexts, graphs, ndarrays, textures, and profiling integration
taichi/program - Compile manager · Coordinates kernel compilation and caching
taichi/compilation_manager - Runtime backends · Backend-specific execution paths for CPU, CUDA, AMDGPU, Metal, Vulkan, OpenGL, DX12, and graphics
taichi/runtime - RHI layer · Device, driver, allocator, interop, and platform-facing hardware abstraction boundary
taichi/rhi - AOT modules · Native module builder and loader for serialized kernels and graphs
taichi/aot - Native UI · C++ windowing and graphics-oriented renderer, scene, and GUI implementation
taichi/ui
Integration
C API, UI, examples, tests, and benchmarks
- C API · Stable native embedding API with backend-specific implementations and headers
c_api - Tests · Python and C++ validation suites covering compiler, runtime, AOT, RHI, and API behavior
tests - Benchmarks · Microbenchmarks and performance regression harnesses
benchmarks - C++ examples · Native usage examples, including RHI and AOT samples
cpp_examples
Connections 22
- 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