enigma.compile()

Full reference for the enigma.compile() function and the CompiledKernel it returns.

Runs the full Enigma compilation pipeline and returns a CompiledKernel.

Signature

enigma.compile(
    fn,
    *jit_args,
    vec_width: int = 0,
    dump_ir: bool = False,
    dump_mlir: bool = False,
    keep_metal_source: bool = False,
    work_dir: str | None = None,
    emit_only: bool | None = None,
) -> CompiledKernel

Parameters

Parameter	Type	Default	Description
fn	@enigma.kernel or @enigma.jit	required	The kernel or JIT function to compile
*jit_args	Tensor, …	—	For @enigma.jit: positional arguments passed to the JIT function at compile time
vec_width	int	0	Vectorization lane width. 0 = scalar. 4 = float4 paths
dump_ir	bool	False	Print the traced IR to stdout
dump_mlir	bool	False	Print the Enigma dialect MLIR to stdout
keep_metal_source	bool	False	Write .metal source file to work_dir
work_dir	str | None	None	Directory for build artifacts. Defaults to a temp directory
emit_only	bool | None	None	Skip Metal compilation. None = auto (True on non-macOS). True = emit MSL only (no .metallib)

Returns: CompiledKernel

Attributes

Attribute	Type	Description
kernel_name	str	Metal function name, e.g. enigma_kernel_vector_add
metallib_path	str	Absolute path to the compiled .metallib file
metallib_bytes	bytes	Raw bytes of the .metallib
metal_source	str	Generated Metal Shading Language source
mlir_source	str | None	Enigma dialect MLIR (when dump_mlir=True)
grid	tuple[int, int, int] | None	For @jit kernels: launch grid computed at compile time
block	tuple[int, int, int] | None	For @jit kernels: threadgroup size computed at compile time

Methods

export_metal(path: str) -> str

Write the generated Metal source to a file. Returns the resolved path.

saved = compiled.export_metal("./artifacts/my_kernel.metal")

Usage

Compiling a @enigma.kernel

@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)

With debug output

compiled = enigma.compile(
    add,
    dump_ir=True,
    dump_mlir=True,
    keep_metal_source=True,
    work_dir="./build/enigma",
)
print(compiled.metal_source)

Vectorized compilation

compiled = enigma.compile(add, vec_width=4)
# kernel uses float4 loads/stores when alignment permits

Compiling a @enigma.jit function

Pass the Tensor arguments that the JIT function receives at compile time:

m, n = 256, 512
A = enigma.Tensor("A", 0, "float", enigma.Layout((m, n), (n, 1)))
B = enigma.Tensor("B", 1, "float", enigma.Layout((m, n), (n, 1)))
C = enigma.Tensor("C", 2, "float", enigma.Layout((m, n), (n, 1)))

compiled = enigma.compile(tiled_add, A, B, C)
# compiled.grid and compiled.block are set

Errors

Error	Cause
xcrun exit code error	Metal compiler toolchain not found. Run xcrun -sdk macosx metal -v to diagnose.
EnigmaError: tiler exceeds tensor	A layout division produced a tiler larger than the tensor in some mode.
TypeError in tracer	Invalid operand types — check that you are not mixing Python values with IRValue in kernel bodies.