Skip to content

Tools

compile_check

torchlinops.tools.compile_check profiles a user-provided linop with eager execution versus torch.compile on a sample input. It always benchmarks the wrapped operator (linop, linop.H, or linop.N), since that is what user code calls in practice.

import torch
from torchlinops import NUFFT
from torchlinops.tools import compile_check

locs = torch.randn(4096, 2, device="cuda")
A = NUFFT(locs, (64, 64), output_shape=("K",))
x = torch.randn(64, 64, dtype=torch.complex64, device="cuda")

result = compile_check(A, x, variants=["forward", "adjoint"])

The sample input determines the device, dtype, and input shape. An output-shaped sample is constructed independently for adjoint profiling. variants defaults to ["forward", "adjoint"]; pass "normal" to include the normal operator. The result includes:

  • eager and compiled median times and speedup,
  • numerical differences versus eager,
  • graph-break count and locations (unless fullgraph=True),
  • tensor shapes and byte sizes.

Autograd/backward profiling is not included yet. For full benchmark matrices, see the torch.compile benchmarks.

torchlinops.tools.compile_check

compile_check(
    linop,
    sample_input: Tensor,
    variants: list[str] | tuple[str, ...] = (
        "forward",
        "adjoint",
    ),
    *,
    warmup: int = 5,
    iters: int = 20,
    fullgraph: bool = False,
    explain_graph_breaks: bool = True,
    print_results: bool = True,
) -> CompileCheckResult

Profile eager vs torch.compile for a user-provided linop.

This always benchmarks the wrapped operator (linop, linop.H, or linop.N), which is what users call in practice. The sample input sets the device, dtype, and input shape. An output-shaped sample is constructed independently for adjoint profiling.

PARAMETER DESCRIPTION
linop

Operator to profile.

TYPE: NamedLinop

sample_input

Input-shaped sample. Determines device, dtype, and shape.

TYPE: Tensor

variants

Variants to run. Accepts "forward"/"fwd", "adjoint"/"adj", and "normal"/"norm".

TYPE: sequence of str DEFAULT: ("forward", "adjoint")

warmup

Timing protocol for both eager and compiled calls.

TYPE: int DEFAULT: 5

iters

Timing protocol for both eager and compiled calls.

TYPE: int DEFAULT: 5

fullgraph

Passed to torch.compile. Graph breaks are not measured when true.

TYPE: bool DEFAULT: False

explain_graph_breaks

Measure graph breaks with torch._dynamo.explain.

TYPE: bool DEFAULT: True

print_results

Print a summary table before returning.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
CompileCheckResult

Tensor sizes, timings, speedups, numerical differences, and break locations for each requested variant.

Notes

Autograd/backward profiling is not included yet.

Source code in src/torchlinops/tools.py
def compile_check(
    linop,
    sample_input: torch.Tensor,
    variants: list[str] | tuple[str, ...] = ("forward", "adjoint"),
    *,
    warmup: int = 5,
    iters: int = 20,
    fullgraph: bool = False,
    explain_graph_breaks: bool = True,
    print_results: bool = True,
) -> CompileCheckResult:
    """Profile eager vs ``torch.compile`` for a user-provided linop.

    This always benchmarks the wrapped operator (``linop``, ``linop.H``, or
    ``linop.N``), which is what users call in practice. The sample input sets
    the device, dtype, and input shape. An output-shaped sample is constructed
    independently for adjoint profiling.

    Parameters
    ----------
    linop : NamedLinop
        Operator to profile.
    sample_input : torch.Tensor
        Input-shaped sample. Determines device, dtype, and shape.
    variants : sequence of str, default ("forward", "adjoint")
        Variants to run. Accepts ``"forward"``/``"fwd"``,
        ``"adjoint"``/``"adj"``, and ``"normal"``/``"norm"``.
    warmup, iters : int
        Timing protocol for both eager and compiled calls.
    fullgraph : bool, default False
        Passed to ``torch.compile``. Graph breaks are not measured when true.
    explain_graph_breaks : bool, default True
        Measure graph breaks with ``torch._dynamo.explain``.
    print_results : bool, default True
        Print a summary table before returning.

    Returns
    -------
    CompileCheckResult
        Tensor sizes, timings, speedups, numerical differences, and break
        locations for each requested variant.

    Notes
    -----
    Autograd/backward profiling is not included yet.
    """
    if not isinstance(sample_input, torch.Tensor):
        raise TypeError("sample_input must be a torch.Tensor")
    if not variants:
        raise ValueError("At least one variant must be requested")

    normalized = []
    for variant in variants:
        key = _VARIANT_ALIASES.get(str(variant).lower())
        if key is None:
            raise ValueError(
                f"Unknown variant {variant!r}; use forward, adjoint, or normal"
            )
        if key not in normalized:
            normalized.append(key)

    device = sample_input.device
    try:
        eager_output = linop(sample_input)
    except Exception as exc:
        raise RuntimeError(
            "compile_check could not run the linop on sample_input; check the "
            "input shape and dtype"
        ) from exc
    output_sample = torch.randn_like(eager_output)

    rows: list[CompileCheckRow] = []
    for variant in normalized:
        if variant == "forward":
            target = lambda t: linop(t)
            input_ = sample_input
        elif variant == "adjoint":
            target = lambda t: linop.H(t)
            input_ = output_sample
        else:
            target = lambda t: linop.N(t)
            input_ = sample_input

        row = CompileCheckRow(
            variant=variant,
            input_shape=tuple(input_.shape),
            output_shape=tuple(eager_output.shape),
            input_bytes=_tensor_bytes(input_),
            output_bytes=_tensor_bytes(eager_output),
        )
        try:
            reference = target(input_)
            row.eager_time = _median_time(
                lambda target=target, input_=input_: target(input_),
                warmup=warmup,
                iters=iters,
                device=device,
            )
        except Exception:  # noqa: BLE001 - recorded in the result row
            row.status = "error"
            row.error = traceback.format_exc().strip()[-1200:]
            rows.append(row)
            continue

        torch._dynamo.reset()
        try:
            compiled = torch.compile(target, fullgraph=fullgraph)
            compiled_out = compiled(input_)
            row.compiled_time = _median_time(
                lambda compiled=compiled, input_=input_: compiled(input_),
                warmup=warmup,
                iters=iters,
                device=device,
            )
            row.max_abs_diff, row.max_rel_diff = _diff_metrics(reference, compiled_out)
            row.status = (
                "ok" if (row.max_rel_diff or 0.0) <= 1e-3 else "numeric_mismatch"
            )
            if explain_graph_breaks:
                row.graph_breaks, row.break_locations = _graph_breaks(
                    target, input_, fullgraph
                )
        except Exception:  # noqa: BLE001 - recorded in the result row
            row.status = "error"
            row.error = traceback.format_exc().strip()[-1200:]
        if row.eager_time and row.compiled_time:
            row.speedup = row.eager_time / row.compiled_time
        rows.append(row)

    result = CompileCheckResult(
        device=str(device),
        dtype=sample_input.dtype,
        input_shape=tuple(sample_input.shape),
        output_shape=tuple(eager_output.shape),
        input_bytes=_tensor_bytes(sample_input),
        output_bytes=_tensor_bytes(eager_output),
        rows=rows,
    )
    if print_results:
        print(result.summary())
    return result