Getting Started

Set up Enigma and run your first GPU kernel on Apple Metal.

Enigma is a Python-first GPU compute framework for Apple Silicon. You write kernels in Python using a CuTe-inspired layout algebra, and Enigma compiles them to Metal Shading Language (MSL) and dispatches them through the Metal runtime.

What you need

• macOS with an Apple Silicon GPU
• Python 3.11, 3.12, or 3.13
• Xcode Command Line Tools (for xcrun metal and xcrun metallib)

Python distributions above 3.13 are not supported.

In this section

Page	What you will learn
Installation	Install Enigma, verify toolchain
First Kernel	Write, compile, and dispatch a vector-add kernel
Compile-Only Workflow	Iterate on codegen without a GPU

The thirty-second version

import enigma
import numpy as np

@enigma.kernel
def add(A: enigma.f32, B: enigma.f32, C: enigma.f32):
    tid = enigma.thread_position_in_grid
    C[tid] = A[tid] + B[tid]

compiled = enigma.compile(add)
rt = enigma.MetalRuntime()

n = 4096
a = np.random.randn(n).astype(np.float32)
b = np.random.randn(n).astype(np.float32)

raw = rt.execute(compiled, [a, b], output_size=n * 4, grid=(n, 1, 1), threads=(256, 1, 1))
out = np.frombuffer(raw, dtype=np.float32)
np.testing.assert_allclose(out, a + b, rtol=1e-5)
print("ok")

Move on to Installation to set up your environment.