Installation and first program¶

Goal: install Tiga, run a neighbor aggregation on an NVIDIA GPU, and obtain results and gradients with ordinary Torch tensors. No compiler IR knowledge is required. Basic Python is assumed; source installation additionally requires a build toolchain.

Install¶

Tiga is alpha software. The distribution name is tiga-lang; the import name is tiga.

From PyPI¶

In a Python 3.11 or 3.12 virtual environment, install Torch first for the examples below (skip the first command if Torch is already installed or native-only execution is intended):

python -m pip install torch
python -m pip install tiga-lang
python -m tiga

For GPU use, install a hardware-compatible Torch build instead of the generic Torch command above. Tiga does not install or upgrade Torch by default. For the optional Triton provider, replace the Tiga install command with:

python -m pip install "tiga-lang[cuda]"

This extra adds neither Torch nor a GPU driver. A compatible prebuilt wheel bundles the compiler tools and native libraries; no separate LLVM/MLIR SDK or C++ build toolchain is needed to install it. The first-release wheel matrix is Linux x86-64, CPython 3.11/3.12, manylinux_2_38_x86_64 (glibc ≥ 2.38). macOS, Windows and other Python versions are not first-release targets. The Torch adapter targets Torch 2.11.x and Triton 3.6.x for CUDA; install a hardware-compatible Torch distribution separately. If no compatible wheel is available, use the source build with its prerequisites; a source distribution is not a precompiled wheel.

To install a downloaded or locally built wheel, use its actual file path:

python -m pip install "/path/to/tiga_lang-0.1.1-<python>-<abi>-<platform>.whl"
python -m tiga

Replace the placeholder filename with a wheel matching the Python version and platform. No PyPI access is needed for the base wheel installation.

Install from source¶

Requirements: Python 3.11–3.12, a C++ compiler, CMake, Ninja and a prebuilt LLVM/MLIR 22.1.8 SDK. Replace the SDK path. The commands below use the supported Linux x86-64 / CPython 3.11–3.12 build environment.

git clone https://github.com/walkerchi/TIGA-lang.git tiga-lang
cd tiga-lang
python -m venv .venv
source .venv/bin/activate
# Torch examples: install Torch first; omit this for native-only use.
python -m pip install torch
export TIGA_LLVM_ROOT=/path/to/llvm-22.1.8
export CMAKE_ARGS="-DMLIR_DIR=$TIGA_LLVM_ROOT/lib/cmake/mlir -DLLVM_DIR=$TIGA_LLVM_ROOT/lib/cmake/llvm"
python -m pip install -e .
python -m tiga

Torch is optional. For GPU use, install the Torch build matching the intended hardware before installing Tiga; reuse an existing Torch environment if available. The default Tiga installation does not install or upgrade Torch. Without Torch, use the native Tensor and CPU JIT path.

python -m tiga should report the package version, native runtime state and resolved compiler tools. Resolve missing tools before continuing: execution and troubleshooting.

First differentiable JIT program¶

Start with three nodes and five edges. Each edge sends its source temperature multiplied by its conductivity; each destination sums the messages and adds a bias. A reducer specifies how messages combine; this example uses sum.

Run these blocks in order. Inputs and outputs use torch.Tensor; Tiga captures the message-passing computation without a public tensor wrapper.

import torch
import tiga as tg

device = torch.device("cuda")

class ConductiveAggregation(tg.MessagePassing):
    reducer = tg.sum()

    def edge(self, src, dst, edge):
        return edge.conductivity * src.temperature

    def node(self, dst, incoming):
        return incoming + dst.bias


graph = tg.Graph.from_csr(
    torch.tensor([0, 2, 3, 5], dtype=torch.int64, device=device),
    torch.tensor([0, 2, 1, 0, 1], dtype=torch.int64, device=device),
    num_src=3,
    validate="full",
)
temperature = torch.tensor([1.0, 2.0, 3.0], device=device, requires_grad=True)
conductivity = torch.tensor([2.0, 3.0, 4.0, 5.0, 6.0], device=device, requires_grad=True)
bias = torch.tensor([0.1, 0.2, 0.3], device=device, requires_grad=True)
kernel = ConductiveAggregation()
output = kernel(graph=graph, src={"temperature": temperature},
                dst={"bias": bias}, edge={"conductivity": conductivity})
d_temperature, d_conductivity, d_bias = torch.autograd.grad(
    output.sum(), (temperature, conductivity, bias))

Observe the results and gradients:

print(output.tolist())        # approximately [11.1, 8.2, 17.3]
print(d_temperature.tolist()) # [7.0, 10.0, 3.0]

The first result, 11.1, comes from two messages arriving at destination 0 plus its bias. The programming model explains the mapping between these edges, arrays and fields.

No explicit compile call or handwritten backward function is needed. The output works with Torch operations, torch.autograd.grad and .backward(). A successful result does not by itself identify a compiled provider; planning and artifact inspection are covered in execution and troubleshooting.

Run the complete source with python examples/torch_quickstart.py. For the same small computation on CPU, replace torch.device("cuda") with torch.device("cpu"). For execution without Torch, see the native example.

Optional installation and dependencies¶

Install Torch separately before Tiga to run the Torch examples. Native Tiga runs without Torch; tiga-lang[torch] is only an explicit opt-in dependency extra.
PyPI extras use tiga-lang[cuda] or tiga-lang[nccl-cu12] (bundled NCCL). From a source checkout, use python -m pip install -e ".[cuda]" or python -m pip install -e ".[nccl-cu12]" instead. CUDA drivers remain an external prerequisite.

Development checks¶

Running a program does not require configuring compiler tests first. For source changes, follow Build and contribute to install test dependencies and configure a separate MLIR test build.

Next¶

Programming model: graphs, fields, messages and aggregation.
Execution and troubleshooting: identify execution paths and failures.
Worked examples: apply the interface to a workload.

Compiler developers can then continue with the compiler introduction and IR walkthrough.