Core Abstractions#

class nsight.collection.core.NsightCollector#

Bases: ABC

abstract collect(
func: Callable[[...], Any],
configs: Sequence[Sequence[Any]],
settings: ProfileSettings,
)#

Collects profiling data for the given function and configurations.

Parameters:
Return type:

DataFrame | None

Returns:

Collected profiling data.

class nsight.collection.core.NsightProfiler(
settings: ProfileSettings,
collector: NsightCollector,
)#

Bases: object

A decorator class for profiling functions using Nsight Python’s profiling tools.

This class allows you to wrap a function with profiling capabilities, collecting performance data and saving the results to CSV files. It uses a collector to gather raw profiling data and processes it according to the provided settings.

Parameters:
settings#

Configuration settings for profiling, including normalization, and other options.

collector#

The collector responsible for gathering raw profiling data.

__call__(func)#

Wraps the given function with profiling logic. Collects raw profiling data, processes it, and saves the results to CSV files. Returns the processed data.

class nsight.collection.core.ProfileResults(results: DataFrame)#

Bases: object

Class to hold profile results for Nsight Python

Parameters:

results (DataFrame)

to_dataframe()#

Returns the processed profiling data as a pandas DataFrame.

This DataFrame contains aggregated statistics across multiple runs for each configuration and annotation combination. The data is equivalent to what is written to the processed_data-<function_name>-<run_id>.csv file when output_csv=True.

Returns:

  • Annotation: Name of the annotated region being profiled

  • <param_name>: One column for each parameter of the decorated function

  • AvgValue: Average metric value across all runs

  • StdDev: Standard deviation of the metric across runs

  • MinValue: Minimum metric value observed

  • MaxValue: Maximum metric value observed

  • NumRuns: Number of runs used for aggregation

  • CI95_Lower: Lower bound of the 95% confidence interval

  • CI95_Upper: Upper bound of the 95% confidence interval

  • RelativeStdDevPct: Standard deviation as a percentage of the mean

  • StableMeasurement: Boolean indicating if the measurement is stable (low variance). The measurement is stable if RelativeStdDevPct < 2 % .

  • Metric: The metric being collected

  • Transformed: Name of the function used to transform the metric (specified via derive_metric), or False if no transformation was applied. For lambda functions, this shows "<lambda>"

  • Kernel: Name of the GPU kernel(s) launched

  • GPU: GPU device name

  • Host: Host machine name

  • ComputeClock: GPU compute clock frequency

  • MemoryClock: GPU memory clock frequency

Return type:

Processed profiling data with the following columns

class nsight.collection.core.ProfileSettings(
configs: Sequence[Sequence[Any]] | None,
runs: int,
output_progress: bool,
output_detailed: bool,
derive_metric: Callable[[...], float] | None,
normalize_against: str | None,
thermal_control: bool,
output_prefix: str | None,
output_csv: bool,
)#

Bases: object

Class to hold profile settings for Nsight Python.

Parameters:
configs: Sequence[Sequence[Any]] | None#

A list of configurations to run the function with. Each configuration is a tuple of arguments for the decorated function. Nsight Python invokes the decorated function len(configs) * runs times. If the configs are not provided at decoration time, they must be provided when calling the decorated function.

derive_metric: Callable[..., float] | None#

A function to transform the collected metric. This can be used to compute derived metrics like TFLOPs that cannot be captured by ncu directly. The function takes the metric value and the arguments of the profile-decorated function and returns the new metric. See the examples for concrete use cases.

normalize_against: str | None#

Annotation name to normalize metrics against. This is useful to compute relative metrics like speedup.

output_csv: bool#

Controls whether to output raw and processed profiling data to CSV files

output_detailed: bool#

Will display a progress bar, detailed output for each config along with the profiler logs

output_prefix: str | None#

All intermediate profiler files are created with this prefix

output_progress: bool#

Will display a progress bar on stdout during profiling

runs: int#

Number of times each configuration should be executed.

thermal_control: bool#

Toggles whether to enable thermal control.

nsight.collection.core.run_profile_session(
func: Callable[[...], Any],
configs: Sequence[Sequence[Any]],
runs: int,
output_progress: bool,
output_detailed: bool,
thermal_control: bool,
)#
Return type:

None

Parameters: