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.