reprospect.tools.ncu.report module

class reprospect.tools.ncu.report.Action(index: int, nvtx_range: dataclasses.InitVar[Any])View on GitHub

Bases: object

Wrapper around IAction.

__init__(index: int, nvtx_range: dataclasses.InitVar[Any]) → None

action: Any

domains: tuple[NvtxDomain, ...]

index: int

nvtx_range: dataclasses.InitVar[Any]

class reprospect.tools.ncu.report.NvtxDomain(index: int, nvtx_state: dataclasses.InitVar[Any])View on GitHub

Bases: object

Wrapper around INvtxDomainInfo.

__init__(index: int, nvtx_state: dataclasses.InitVar[Any]) → None

index: int

nvtx_domain: Any

nvtx_state: dataclasses.InitVar[Any]

reprospect.tools.ncu.report.ProfilingMetricData: TypeAlias = int | float | dict[str, int | float] | reprospect.tools.ncu.metrics.MetricCorrelationData | str

Metric data in profiling results.

class reprospect.tools.ncu.report.ProfilingMetrics(data: dict[str, int | float | dict[str, int | float] | MetricCorrelationData | str])View on GitHub

Bases: Mapping[str, int | float | dict[str, int | float] | MetricCorrelationData | str]

Mapping of profiling metric keys to their values.

Note

It is not decorated with dataclasses.dataclass() because of https://github.com/mypyc/mypyc/issues/1061.

__init__(data: dict[str, int | float | dict[str, int | float] | MetricCorrelationData | str]) → NoneView on GitHub

data: Final[dict[str, int | float | dict[str, int | float] | MetricCorrelationData | str]]

class reprospect.tools.ncu.report.ProfilingResults(data: dict[str, ProfilingResults | ProfilingMetrics] | None = None)View on GitHub

Bases: TreeMixin

Nested tree data structure for storing profiling results.

The data structure consists of internal nodes and leaf nodes:

• The internal nodes are themselves ProfilingResults instances. They organise results hierarchically by the profiling range (e.g. NVTX range) that they were obtained from, terminating by the kernel name.

• The leaf nodes contain the actual profiling metric key-value pairs. Any type implementing the protocol ProfilingMetrics can be used as a profiling metrics entry.

This class provides convenient methods for hierarchical data access and manipulation.

Example structure:

Profiling results
└── 'nvtx range'
    ├── 'nvtx region'
    │   └── 'kernel'
    │       ├── 'metric i'  -> ProfilingMetricData
    │       └── 'metric ii' -> ProfilingMetricData
    └── 'other nvtx region'
        └── 'other kernel'
            ├── 'metric i'  -> ProfilingMetricData
            └── 'metric ii' -> ProfilingMetricData

Note

Using a hierarchical data structure from a package such as hatchet could be a direction to explore in the future.

Note

It is not decorated with dataclasses.dataclass() because of https://github.com/mypyc/mypyc/issues/1061.

__init__(data: dict[str, ProfilingResults | ProfilingMetrics] | None = None) → NoneView on GitHub

aggregate_metrics(accessors: Iterable[str], keys: Iterable[str] | None = None) → dict[str, int | float]View on GitHub

Aggregate metric values across multiple leaf nodes with profiling metrics at accessor path accessors.

Parameters:

keys – Specific metric keys to aggregate. If None, uses all keys from the first leaf node.

assign_metrics(accessors: Sequence[str], data: ProfilingMetrics) → NoneView on GitHub

Set the leaf node with profiling metrics data at accessor path accessors.

Creates the internal nodes in the hierarchy if needed.

data: Final[dict[str, ProfilingResults | ProfilingMetrics]]

iter_metrics(accessors: Iterable[str] = ()) → Generator[tuple[str, ProfilingMetrics], None, None]View on GitHub

Query the accessor path accessors, check that it leads to an internal node, check that all entries are leaf nodes with profiling metrics, and return an iterator over these leaf nodes with profiling metrics.

query(accessors: Iterable[str]) → ProfilingResults | ProfilingMetricsView on GitHub

Get the internal node in the hierarchy or the leaf node with profiling metrics at accessor path accessors.

query_filter(accessors: Iterable[str], predicate: Callable[[str], bool]) → ProfilingResultsView on GitHub

Query the accessor path accessors, check that it leads to an internal node, and return a new ProfilingResults with only the entries whose key satisfies predicate.

query_metrics(accessors: Iterable[str]) → ProfilingMetricsView on GitHub

Query the accessor path accessors, check that it leads to a leaf node with profiling metrics, and return this leaf node with profiling metrics.

query_single_next(accessors: Iterable[str]) → tuple[str, ProfilingResults | ProfilingMetrics]View on GitHub

Query the accessor path accessors, check that it leads to an internal node with exactly one entry, and return this single entry.

This member function is useful for instance to access a single kernel within an NVTX range or region.

>>> from reprospect.tools.ncu import ProfilingResults
>>> results = ProfilingResults()
>>> results.assign_metrics(('my_nvtx_range', 'my_nvtx_region', 'my_kernel'), {'my_metric' : 42})
>>> results.query_single_next(('my_nvtx_range', 'my_nvtx_region'))
('my_kernel', {'my_metric': 42})

query_single_next_metrics(accessors: Iterable[str]) → tuple[str, ProfilingMetrics]View on GitHub

Query the accessor path accessors, check that it leads to an internal node with exactly one entry, check that this entry is a leaf node with profiling metrics, and return this leaf node with profiling metrics.

to_tree() → TreeView on GitHub

Convert to a rich.tree.Tree for nice printing.

class reprospect.tools.ncu.report.Range(index: int, report: dataclasses.InitVar[Any], includes: dataclasses.InitVar[Optional[Iterable[str]]] = None, excludes: dataclasses.InitVar[Optional[Iterable[str]]] = None)View on GitHub

Bases: object

Wrapper around IRange.

This class loads the actions that are in the range.

If both includes and excludes are empty, load all actions in range.

__init__(index: int, report: dataclasses.InitVar[Any], includes: dataclasses.InitVar[Optional[Iterable[str]]] = None, excludes: dataclasses.InitVar[Optional[Iterable[str]]] = None) → None

actions: tuple[Action, ...]

excludes: dataclasses.InitVar[Optional[Iterable[str]]] = None

includes: dataclasses.InitVar[Optional[Iterable[str]]] = None

index: int

range: Any

report: dataclasses.InitVar[Any]

class reprospect.tools.ncu.report.Report(*, path: Path | None = None, name: str | None = None, command: Command | None = None)View on GitHub

Bases: object

This class is a wrapper around the Python tool provided by NVIDIA Nsight Compute to parse its reports.

In particular, the NVIDIA Python tool (ncu_report) provides low-level access to the collected data by iterating over ranges and actions. This class uses these functionalities to extract all the collected data into a custom data structure of type ProfilingResults. This data structures is a nested tree data structure that provides a higher level, direct access to the data of interest by NVTX range (if NVTX is used) and by demangled kernel name.

References:

• https://docs.nvidia.com/nsight-compute/CustomizationGuide/index.html#python-report-interface

• https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly

__init__(*, path: Path | None = None, name: str | None = None, command: Command | None = None) → NoneView on GitHub

Load the report <path>/<name>.ncu-rep or the report generated by reprospect.tools.ncu.session.Command.

collect_metrics_from_action(*, metrics: Iterable[Metric | MetricCorrelation | MetricDeviceAttribute], action: Action) → dict[str, int | float | dict[str, int | float] | MetricCorrelationData | str]View on GitHub

Collect values of the metrics in the action.

References:

• https://github.com/shunting314/gpumisc/blob/37bbb827ae2ed6f5777daff06956c7a10aafe34d/ncu-related/official-sections/FPInstructions.py#L51

• https://github.com/NVIDIA/nsight-training/blob/2d680f7f8368b945bc00b22834808af24eff4c3d/cuda/nsight_compute/python_report_interface/Opcode_instanced_metrics.ipynb

extract_results_in_range(metrics: Collection[Metric | MetricCorrelation | MetricDeviceAttribute], range_idx: int = 0, includes: Iterable[str] | None = None, excludes: Iterable[str] | None = None, demangler: type[CuppFilt | LlvmCppFilt] | None = None) → ProfilingResultsView on GitHub

Extract the metrics of the actions in the range with ID range_idx. Possibly filter by NVTX with includes and excludes.

Parameters:

metrics – Must be iterable from start to end many times.

classmethod fill_metric(action: Action, metric: Metric) → int | float | dict[str, int | float]View on GitHub

Loop over submetrics of metric.

classmethod get_metric_by_name(*, action: Action, metric: str)View on GitHub

Read a metric in action.

get_metric_value(metric: Any, index: int | None = None) → int | float | strView on GitHub

Recent ncu (>= 2025.3.0.0) provide a value method.

reprospect.tools.ncu.report.load_ncu_report() → ModuleTypeView on GitHub

Attempt to load the Nsight Compute Python interface (ncu_report).

Priority:

1. If ncu_report is already imported, return it.

2. Try a regular import ncu_report (for users who set PYTHONPATH).

3. Try to locate ncu via shutil.which, deduce version, and load the bundled Python module from Nsight Compute installation path.