Quickstart

Here’s the absolute minimal example to get started with Nsight Python. Just add a decorator to your function and wrap the kernel you want to profile with nsight.annotate():

import torch
import nsight

@nsight.analyze.kernel(runs=10)
def benchmark_matmul(n):
    """
    The simplest possible benchmark.
    We create two matrices and multiply them.
    """
    # Create two NxN matrices on GPU
    a = torch.randn(n, n, device="cuda")
    b = torch.randn(n, n, device="cuda")

    # Mark the kernel we want to profile
    with nsight.annotate("matmul"):
        c = a @ b


if __name__ == "__main__":
    # Run the benchmark
    result = benchmark_matmul(1024)
    print(result.to_dataframe())

The decorated function returns a ProfileResults object. It does not return a value produced by the original function. Decorated benchmark functions should therefore return None; keep any computation whose result you need in an undecorated helper. See nsight.analyze for an example.

That’s it! Nsight Python will automatically profile your kernel and collect metrics. The to_dataframe() method returns the results as a pandas DataFrame for easy analysis.

This example collects ten runs per configuration so the output includes estimates of sample variability. StableMeasurement indicates whether the relative standard deviation is below 2%; repeated runs do not guarantee a stable measurement.

If you omit runs, the API defaults to runs=1. With only one valid sample, StdDev, RelativeStdDevPct, CI95_Lower, and CI95_Upper are NaN because sample variability cannot be estimated. StableMeasurement is then pd.NA (displayed as <NA>): stability cannot be determined from one sample. A zero mean also leaves RelativeStdDevPct undefined, even with multiple runs.

See Profiling results for the output columns, stability criterion, normalization, and geometric mean.

For more advanced examples including parameter sweeps, custom metrics, and visualization, check out the examples directory on GitHub.