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_df_from_report(report_path, metrics, configs, iterations, func, derive_metric, ignore_kernel_list, output_progress, combine_kernel_metrics=None):

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

nsight.extraction.explode_dataframe(df: DataFrame)#

Explode columns with list/tuple/np.ndarray values into multiple rows. Two scenarios:

  1. No derived metrics (all “Transformed” = False): - All columns maybe contain multiple values (lists/arrays). - Use explode() to flatten each list element into separate rows.

  2. With derived metrics: - Metric columns contain either single-element lists or scalars. - Only flatten single-element lists to scalars, don’t create new rows.

Parameters:

df (DataFrame) – Dataframe to be exploded.

Return type:

DataFrame

Returns:

Exploded dataframe.

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,
output_progress: bool,
combine_kernel_metrics: Callable[[float, float], float] | 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.

  • verbose – Toggles the printing of extraction progress.

  • output_progress (bool)

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:

NCUActionData

Returns:

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