Extraction#

Extraction utilities for analyzing NVIDIA Nsight Compute profiling data.

This module provides functionality to load .ncu-rep reports, extract performance data, and transform it into structured pandas DataFrames for further analysis.

Functions:
extract_ncu_action_data(action, metrics):

Extracts performance data for a specific kernel action from an NVIDIA Nsight Compute report.

extract_data_from_report(report_path, metrics, func, ignore_kernel_list, verbosity):

Loads an NVIDIA Nsight Compute report and returns a dict of raw per-annotation measurements.

extract_df_from_data(profiling_data, metrics, configs, iterations, func, derive_metric, verbosity, combine_kernel_metrics=None):

Aggregates raw per-annotation measurements (from either tool) into a pandas DataFrame.

extract_df_from_report(report_path, metrics, configs, iterations, func, derive_metric, ignore_kernel_list, verbosity, combine_kernel_metrics=None):

Processes the full NVIDIA Nsight Compute report and returns a pandas DataFrame containing performance metrics.

nsight.extraction.extract_data_from_report(
report_path: str,
metrics: Sequence[str],
func: Callable[[...], Any],
ignore_kernel_list: List[str] | None,
verbosity: VerbosityLevel,
)#

Loads an NVIDIA Nsight Compute report and returns the raw per-annotation measurements.

Parameters:
  • report_path (str) – Path to the report file.

  • metrics (Sequence[str]) – The NVIDIA Nsight Compute metrics to extract.

  • func (Callable[..., Any]) – Function representing the kernel launch with parameter signature.

  • ignore_kernel_list (Optional[List[str]]) – Kernel names to ignore in the analysis.

  • verbosity (VerbosityLevel) – Controls display of extraction progress.

Return type:

dict[str, list[ActionData]]

Returns:

A dictionary mapping annotation name to the list of measurements collected for it.

Raises:

exceptions.ProfilerException – If the report file is missing.

nsight.extraction.extract_df_from_data(
profiling_data: dict[str, list[ActionData]],
metrics: Sequence[str],
configs: List[Tuple[Any, ...]],
iterations: int,
func: Callable[[...], Any],
derive_metric: Callable[[...], Any] | None,
verbosity: VerbosityLevel,
combine_kernel_metrics: Callable[[float, float], float] | None = None,
info_collectors_list: List[Tuple[str, Callable[[...], Any], str]] | None = None,
config_scope_columns: List[str] | None = None,
annotation_scope_columns: List[str] | None = None,
collected_info_per_run: Sequence[Mapping[str, Any]] | None = None,
)#

Aggregates raw per-annotation measurements (from either tool) into a pandas DataFrame.

Parameters:
Return type:

DataFrame

Returns:

A DataFrame containing the extracted and transformed performance data.

Raises:
  • RuntimeError – If multiple kernels are detected per config without a combining function.

  • exceptions.ProfilerException – If profiling results are missing or incomplete.

nsight.extraction.extract_df_from_report(
report_path: str,
metrics: Sequence[str],
configs: List[Tuple[Any, ...]],
iterations: int,
func: Callable[[...], Any],
derive_metric: Callable[[...], Any] | None,
ignore_kernel_list: List[str] | None,
verbosity: VerbosityLevel,
combine_kernel_metrics: Callable[[float, float], float] | None = None,
info_collectors_list: List[Tuple[str, Callable[[...], Any], str]] | None = None,
config_scope_columns: List[str] | None = None,
annotation_scope_columns: List[str] | None = None,
collected_info_per_run: Sequence[Mapping[str, Any]] | None = None,
)#

Extracts and aggregates profiling results from an NVIDIA Nsight Compute report.

Parameters:
Return type:

DataFrame

Returns:

A DataFrame containing the extracted and transformed performance data.

Raises:
  • RuntimeError – If multiple kernels are detected per config without a combining function.

  • exceptions.ProfilerException – If profiling results are missing or incomplete.

nsight.extraction.extract_ncu_action_data(
action: Any,
metrics: Sequence[str],
)#

Extracts performance data from an NVIDIA Nsight Compute kernel action.

Parameters:
  • action (Any) – The NVIDIA Nsight Compute action object.

  • metrics (Sequence[str]) – The metric names to extract from the action.

Return type:

ActionData

Returns:

A data container with extracted metrics, clock rates, and GPU name.