> ## Documentation Index
> Fetch the complete documentation index at: https://klyne-research.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Benchmark & Testing

> Utilities for timing kernels and writing tests.

## enigma.benchmark

### `enigma.benchmark.bench(fn, *args, repeat=50, warmup=5, label=None)`

Wall-clock time a callable over `repeat` runs.

| Parameter           | Type        | Default  | Description                       |
| ------------------- | ----------- | -------- | --------------------------------- |
| `fn`                | callable    | required | Function to benchmark             |
| `*args`, `**kwargs` | any         | —        | Passed to `fn`                    |
| `repeat`            | int         | `50`     | Number of timed runs              |
| `warmup`            | int         | `5`      | Discarded warmup runs             |
| `label`             | str or None | `None`   | Label (defaults to `fn.__name__`) |

Returns a `BenchResult` with `.min_us`, `.median_us`, `.mean_us`, `.stdev_us`.

### `enigma.benchmark.bench_gpu(prepared, grid, threads, *, repeat=50, warmup=5, label=None)`

Time a `PreparedKernel` using GPU timestamps.

| Parameter  | Type               | Default  | Description          |
| ---------- | ------------------ | -------- | -------------------- |
| `prepared` | PreparedKernel     | required | Pre-allocated kernel |
| `grid`     | tuple(int,int,int) | required | Grid dimensions      |
| `threads`  | tuple(int,int,int) | required | Thread dimensions    |
| `repeat`   | int                | `50`     | Timed runs           |
| `warmup`   | int                | `5`      | Warmup runs          |

Returns `BenchResult`.

### `enigma.benchmark.format_bench_result(r, *, throughput_gbps=None)`

One-line formatted string for printing benchmark tables.

### `BenchResult`

| Property    | Type  | Description             |
| ----------- | ----- | ----------------------- |
| `label`     | str   | Benchmark label         |
| `n`         | int   | Number of samples       |
| `min_us`    | float | Minimum time (us)       |
| `median_us` | float | Median time (us)        |
| `mean_us`   | float | Mean time (us)          |
| `stdev_us`  | float | Standard deviation (us) |

## enigma.testing

Test utilities for conditional test execution.

| Function                                 | Description                     |
| ---------------------------------------- | ------------------------------- |
| `enigma.testing.is_darwin()`             | True if host is macOS           |
| `enigma.testing.is_apple_silicon()`      | True if macOS on arm64          |
| `enigma.testing.is_metal_available()`    | True if Metal runtime is usable |
| `@enigma.testing.requires_metal`         | Skip test if no Metal runtime   |
| `@enigma.testing.requires_apple_silicon` | Skip test if not arm64 macOS    |

Set `ENIGMA_FORCE_NO_METAL=1` to force-disable Metal detection for testing.