# nvidia/nsight-python architecture

> Architecture diagram of the GitHub repository nvidia/nsight-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/nsight-python
- Repository: https://github.com/nvidia/nsight-python

## Overview

Nsight Python lets Python users benchmark GPU kernels and inspect profiling metrics. The main workflow decorates or annotates kernel-launch code, runs it through a selected Nsight backend, extracts measurements, and analyzes or visualizes results. Separate capabilities include Compute Sanitizer checks, custom information collection, result transformation, and thermal control. The excerpts show the profiling-session and backend relationships; some additional modules are indexed but not sampled in detail, so their connections are omitted where call ownership is unclear.

Main entry points: [`nsight/analyze.py`](https://github.com/nvidia/nsight-python/blob/main/nsight/analyze.py) (Kernel analysis), [`nsight/collection/core.py`](https://github.com/nvidia/nsight-python/blob/main/nsight/collection/core.py) (Profile session), [`nsight/collection/ncu.py`](https://github.com/nvidia/nsight-python/blob/main/nsight/collection/ncu.py) (NCU collector), [`nsight/collection/cupti.py`](https://github.com/nvidia/nsight-python/blob/main/nsight/collection/cupti.py) (CUPTI collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Python interface"]
  node_api["Public API<br/>[__init__.py]"]
  node_kernel_analysis["Kernel analysis<br/>[analyze.py]"]
end

subgraph group_profiling["Profiling workflow"]
  node_annotations["NVTX annotations<br/>[annotation.py]"]
  node_session["Profile session<br/>[core.py]"]
  node_tools["Tool selection<br/>[tools_manager.py]"]
  node_collectors["Custom collectors<br/>[info_collector.py]"]
end

subgraph group_backends["Collection backends"]
  node_ncu["NCU collector<br/>[ncu.py]"]
  node_cupti["CUPTI collector<br/>[cupti.py]"]
  node_extract["Report extraction<br/>[extraction.py]"]
  node_sanitizer_api["Sanitizer activation<br/>[sanitize.py]"]
  node_sanitizer["Compute Sanitizer"]
end

subgraph group_results["Results and controls"]
  node_visualization["Metric visualization<br/>[visualization.py]"]
  node_transformation["Result transformation<br/>[transformation.py]"]
  node_thermal["Thermal control<br/>[thermovision.py]"]
end

subgraph group_support["Diagnostics"]
end

node_user(("Python user"))
node_nvidia_tools["NVIDIA profiling tools"]

node_user -->|"imports"| node_api
node_api -->|"exposes"| node_kernel_analysis
node_user -->|"profiles kernels"| node_kernel_analysis
node_kernel_analysis -->|"runs sessions"| node_session
node_kernel_analysis -->|"uses"| node_visualization
node_kernel_analysis -.->|"selects tools"| node_tools
node_session -->|"profiles with"| node_ncu
node_session -->|"profiles with"| node_cupti
node_ncu -->|"runs sessions"| node_session
node_cupti -->|"runs sessions"| node_session
node_ncu -->|"extracts reports"| node_extract
node_cupti -->|"uses extraction"| node_extract
node_tools -->|"activates"| node_ncu
node_tools -->|"activates"| node_cupti
node_tools -->|"activates"| node_sanitizer
node_sanitizer_api -->|"initializes"| node_sanitizer
node_annotations -->|"collects annotation data"| node_collectors
node_session -->|"collects run data"| node_collectors
node_nvidia_tools -->|"provides profiler"| node_ncu
node_nvidia_tools -->|"provides profiler"| node_cupti
node_nvidia_tools -->|"provides checker"| node_sanitizer
node_kernel_analysis -.->|"transforms results"| node_transformation
node_kernel_analysis -.->|"controls thermals"| node_thermal

click node_api "https://github.com/nvidia/nsight-python/blob/main/nsight/__init__.py"
click node_kernel_analysis "https://github.com/nvidia/nsight-python/blob/main/nsight/analyze.py"
click node_annotations "https://github.com/nvidia/nsight-python/blob/main/nsight/annotation.py"
click node_session "https://github.com/nvidia/nsight-python/blob/main/nsight/collection/core.py"
click node_ncu "https://github.com/nvidia/nsight-python/blob/main/nsight/collection/ncu.py"
click node_cupti "https://github.com/nvidia/nsight-python/blob/main/nsight/collection/cupti.py"
click node_extract "https://github.com/nvidia/nsight-python/blob/main/nsight/extraction.py"
click node_sanitizer_api "https://github.com/nvidia/nsight-python/blob/main/nsight/sanitize.py"
click node_sanitizer "https://github.com/nvidia/nsight-python/blob/main/nsight/collection/compute_sanitizer.py"
click node_tools "https://github.com/nvidia/nsight-python/blob/main/nsight/tools_manager.py"
click node_collectors "https://github.com/nvidia/nsight-python/blob/main/nsight/info_collector.py"
click node_visualization "https://github.com/nvidia/nsight-python/blob/main/nsight/visualization.py"
click node_transformation "https://github.com/nvidia/nsight-python/blob/main/nsight/transformation.py"
click node_thermal "https://github.com/nvidia/nsight-python/blob/main/nsight/thermovision.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_kernel_analysis,node_user toneBlue
class node_annotations,node_session,node_tools,node_collectors toneAmber
class node_ncu,node_cupti,node_extract,node_sanitizer_api,node_sanitizer toneMint
class node_visualization,node_transformation,node_thermal toneRose
class node_nvidia_tools toneIndigo
```

## Components

### Python interface

- [Public API](https://github.com/nvidia/nsight-python/blob/main/nsight/__init__.py): `nsight/__init__.py`
- [Kernel analysis](https://github.com/nvidia/nsight-python/blob/main/nsight/analyze.py): `nsight/analyze.py`

### Profiling workflow

- [NVTX annotations](https://github.com/nvidia/nsight-python/blob/main/nsight/annotation.py): `nsight/annotation.py`
- [Profile session](https://github.com/nvidia/nsight-python/blob/main/nsight/collection/core.py): `nsight/collection/core.py`
- [Tool selection](https://github.com/nvidia/nsight-python/blob/main/nsight/tools_manager.py): `nsight/tools_manager.py`
- [Custom collectors](https://github.com/nvidia/nsight-python/blob/main/nsight/info_collector.py): `nsight/info_collector.py`

### Collection backends

- [NCU collector](https://github.com/nvidia/nsight-python/blob/main/nsight/collection/ncu.py): `nsight/collection/ncu.py`
- [CUPTI collector](https://github.com/nvidia/nsight-python/blob/main/nsight/collection/cupti.py): `nsight/collection/cupti.py`
- [Report extraction](https://github.com/nvidia/nsight-python/blob/main/nsight/extraction.py): `nsight/extraction.py`
- [Sanitizer activation](https://github.com/nvidia/nsight-python/blob/main/nsight/sanitize.py): `nsight/sanitize.py`
- [Compute Sanitizer](https://github.com/nvidia/nsight-python/blob/main/nsight/collection/compute_sanitizer.py): `nsight/collection/compute_sanitizer.py`

### Results and controls

- [Metric visualization](https://github.com/nvidia/nsight-python/blob/main/nsight/visualization.py): `nsight/visualization.py`
- [Result transformation](https://github.com/nvidia/nsight-python/blob/main/nsight/transformation.py): `nsight/transformation.py`
- [Thermal control](https://github.com/nvidia/nsight-python/blob/main/nsight/thermovision.py): `nsight/thermovision.py`

### Other components

- **Python user**
- **NVIDIA profiling tools**

## Connections

- Python user → Public API: imports (evidence: `nsight/__init__.py`)
- Public API → Kernel analysis: exposes (evidence: `nsight/__init__.py`)
- Python user → Kernel analysis: profiles kernels (evidence: `README.md`)
- Kernel analysis → Profile session: runs sessions (evidence: `nsight/analyze.py`)
- Kernel analysis → Metric visualization: uses (evidence: `nsight/analyze.py`)
- Kernel analysis → Tool selection: selects tools (evidence: `nsight/analyze.py`)
- Profile session → NCU collector: profiles with (evidence: `nsight/collection/ncu.py`)
- Profile session → CUPTI collector: profiles with (evidence: `nsight/collection/cupti.py`)
- NCU collector → Profile session: runs sessions (evidence: `nsight/collection/ncu.py`)
- CUPTI collector → Profile session: runs sessions (evidence: `nsight/collection/cupti.py`)
- NCU collector → Report extraction: extracts reports (evidence: `nsight/collection/ncu.py`)
- CUPTI collector → Report extraction: uses extraction (evidence: `nsight/collection/cupti.py`)
- Tool selection → NCU collector: activates (evidence: `nsight/tools_manager.py`)
- Tool selection → CUPTI collector: activates (evidence: `nsight/tools_manager.py`)
- Tool selection → Compute Sanitizer: activates (evidence: `nsight/tools_manager.py`)
- Sanitizer activation → Compute Sanitizer: initializes (evidence: `nsight/sanitize.py`)
- NVTX annotations → Custom collectors: collects annotation data (evidence: `nsight/annotation.py`)
- Profile session → Custom collectors: collects run data (evidence: `nsight/collection/core.py`)
- NVIDIA profiling tools → NCU collector: provides profiler (evidence: `nsight/collection/ncu.py`)
- NVIDIA profiling tools → CUPTI collector: provides profiler (evidence: `nsight/collection/cupti.py`)
- NVIDIA profiling tools → Compute Sanitizer: provides checker (evidence: `nsight/collection/compute_sanitizer.py`)
- Kernel analysis → Result transformation: transforms results
- Kernel analysis → Thermal control: controls thermals