How marco-christiani/zigrad works
Project type and purpose
• Zigrad is a high-performance machine learning framework written in Zig.
• It provides an automatic differentiation engine, eager execution with optional graph tracing, and backends for CPU (BLAS) and CUDA.
• It integrates with TensorBoard for visualization and ships example applications (DQN, MNIST, CartPole).
File structure
• Top-level “src” folder: core Zig code, subdivided into modules for device abstractions, ndarray/ndtensor, automatic differentiation, graph manager, neural-network layers, and TensorBoard logger.
• “src/cuda”: CUDA kernels and helpers for GPU BLAS, convolutions, neural-network primitives.
• “tensorboard”: Proto definitions + Zig code to emit TensorBoard events.
• “examples”: Standalone demos (hello-world, DQN, MNIST).
• “scripts”: Python/Lua helpers for build or CUDA setup.
• Build/config files: build.zig, zon files, Dockerfile, flake.nix, CI workflows.
• “docs”: Architecture proposals, device design, demos.
a. Main components
• API & Core Engine (Zig):
– ndarray + ndtensor modules
– Autograd engine (backward_context, graph_manager)
– Neural-network modules (nn/layer, loss, optim)
• Device backends:
– CPU (calls BLAS/OpenBLAS or MKL)
– CUDA (src/cuda/*.cu)
• TensorBoard Logger (tensorboard/src)
• Examples & Scripts (entry points, wrappers)
• External Libraries: BLAS, CUDA Toolkit, Python (for examples and scripts)
• Build & Deployment: Zig build, Docker, Nix/Flake, CI
b. Relationships & data flow
1. User code (examples or research scripts) → calls Zigrad API
2. API creates Tensors (ndarray) → records operations in Autograd Context
3. GraphManager optionally traces static graph → emits protobuf events → TensorBoardLogger
4. During forward/backward: operations dispatched to CPU or CUDA backend
5. CPU backend links with external BLAS (MKL/OpenBLAS)
6. CUDA backend launches custom kernels via CUDA Toolkit
7. Optimizer updates parameters in host or device memory
c. Architectural patterns & design principles
• Layered architecture: API → core engine → device abstraction → hardware
• Opt-in graph tracing: supports both eager and graph modes
• Plugin-style backends: separate CPU and GPU implementations
• Event/Logging subsystem decoupled via TensorBoard protobufs
d. Key technologies & frameworks
• Zig language & build system
• BLAS (MKL/OpenBLAS)
• NVIDIA CUDA (kernels in .cu)
• Protocol Buffers for TensorBoard events
• CI/CD: GitHub Actions, Docker, Nix flakes
Detail
• CUDA sub-directory as a composite component with kernels (BLAS, nn primitives).
• Proto folder under TensorBoard as part of event serialization.