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,
info_prefix: str | None = None,
)#

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

Parameters:

  • profiling_data (dict[str, list[ActionData]]) – Raw per-annotation measurements to aggregate.

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

  • configs (List[Tuple[Any, ...]]) – Configuration settings used during profiling runs.

  • iterations (int) – Number of times each configuration was run.

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

  • derive_metric (Callable[..., Any] | None) – Function to transform the raw metric values with config values.

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

  • combine_kernel_metrics (Optional[Callable[[float, float], float]]) – Function to merge multiple kernel metrics.

  • info_collectors_list (List[Tuple[str, Callable[[...], Any], str]] | None)

  • config_scope_columns (List[str] | None)

  • annotation_scope_columns (List[str] | None)

  • info_prefix (str | None)

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,
info_prefix: str | None = None,
)#

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

Parameters:

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

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

  • configs (List[Tuple[Any, ...]]) – Configuration settings used during profiling runs.

  • iterations (int) – Number of times each configuration was run.

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

  • derive_metric (Callable[..., Any] | None) – Function to transform the raw metric values with config values.

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

  • combine_kernel_metrics (Optional[Callable[[float, float], float]]) – Function to merge multiple kernel metrics.

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

  • info_collectors_list (List[Tuple[str, Callable[[...], Any], str]] | None)

  • config_scope_columns (List[str] | None)

  • annotation_scope_columns (List[str] | None)

  • info_prefix (str | None)

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.