Metadata-Version: 2.4
Name: streamlit-ncu-rep-viewer
Version: 0.1.0
Summary: Unofficial Streamlit viewer for NVIDIA Nsight Compute (.ncu-rep) profiler reports (not affiliated with NVIDIA)
Author-email: Doug <doug@comet.com>
License: MIT
Project-URL: Homepage, https://developer.nvidia.com/nsight-compute
Keywords: nsight,ncu,cuda,gpu,profiling,streamlit
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: System :: Monitoring
Classifier: Environment :: GPU :: NVIDIA CUDA
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit>=1.40
Requires-Dist: plotly>=5.20
Requires-Dist: pandas>=2.0
Requires-Dist: ncu-report>=2025.3.1
Dynamic: license-file

# streamlit-ncu-rep-viewer

A Streamlit viewer that reproduces NVIDIA Nsight Compute's kernel-profiling
visualizations from `.ncu-rep` report files — built for embedding in a Python
Panel on comet.com.

> **Unofficial project.** This is an independent, from-scratch viewer. It is
> **not** affiliated with, endorsed by, or distributed by NVIDIA. "Nsight" and
> "Nsight Compute" are trademarks of NVIDIA Corporation. See
> [Third-party licenses](#third-party-licenses) for the `ncu-report` dependency.

## Install

```bash
pip install streamlit-ncu-rep-viewer
```

This pulls in Streamlit, Plotly, pandas, and NVIDIA's standalone `ncu-report`
report-reader wheel (no full CUDA / Nsight Compute toolkit required).

## Usage

```bash
streamlit-ncu-rep-viewer                 # scan the current directory for *.ncu-rep
streamlit-ncu-rep-viewer path/to/dir     # scan a directory
streamlit-ncu-rep-viewer report.ncu-rep  # open a single report
streamlit-ncu-rep-viewer --samples       # open the bundled sample reports
```

Any extra arguments are forwarded to `streamlit run`, e.g.:

```bash
streamlit-ncu-rep-viewer --samples --server.port 8600 --server.headless true
```

Pick a report and kernel in the sidebar. Three tabs: **Summary** (all kernels),
**Details** (per-kernel sections), **Raw Metrics** (searchable).

## How it works

```
.ncu-rep  ──►  streamlit_ncu_rep_viewer.extract  ──►  JSON  ──►  app.py (Streamlit UI)
              (uses the ncu_report wheel)          (cached)   (pure Python + plotly)
```

- `streamlit_ncu_rep_viewer/extract.py` — dumps every metric + profiler rule from a
  `.ncu-rep` to JSON. Runnable directly: `python -m streamlit_ncu_rep_viewer.extract report.ncu-rep`.
- `streamlit_ncu_rep_viewer/app.py` — the viewer. Shells out to the extractor
  (cached) so report parsing is decoupled from rendering.
- `streamlit_ncu_rep_viewer/cli.py` — the `streamlit-ncu-rep-viewer` console entry point.
- `streamlit_ncu_rep_viewer/sample_reports/` — bundled sample `.ncu-rep` files.

## Details sections (per kernel)

- **NVTX Ranges** — the NVTX ranges active on the call stack when the kernel launched
  (shown only when the report contains NVTX data), so kernels map back to your code's
  phases. Also surfaced as a breadcrumb under the kernel header and an NVTX column in
  the Summary tab.
- **GPU Speed Of Light Throughput** — headline Compute (SM) vs Memory %, duration,
  elapsed cycles, SM/DRAM frequency, and a compute-vs-memory-bound verdict.
- **Compute Workload Analysis** — pipeline utilization (ALU/FMA/LSU/…), busiest pipe highlighted.
- **Memory Workload Analysis** — L1/TEX, L2, DRAM throughput + top memory-unit contributors
  (from the report's own breakdown definitions).
- **Scheduler / Warp State Statistics** — issue active, active warps/cycle, occupancy,
  and PC-sampled warp stall reasons.
- **Instruction Statistics** — executed IPC and per-pipe instruction mix.
- **Launch Statistics**, **Occupancy** (with occupancy-limiter chart), **Analysis & Recommendations**.

## Development

```bash
pip install -e .
streamlit run streamlit_ncu_rep_viewer/app.py   # or: streamlit-ncu-rep-viewer --samples
```

## Not implemented (data not present in the sample reports)

- **Roofline chart** — needs FLOP-count metrics (`--set roofline` / `--set full` profiling).
- **Source page (SASS/PTX per-line counters)** — needs source metrics enabled at profile time.

Scope is intentionally single-file/single-directory for now (no cross-report baselines).

## License

MIT — see `LICENSE`. (Author/copyright placeholder; edit `pyproject.toml` and
`LICENSE` before publishing.)

### Third-party licenses

This package's own code is MIT-licensed, but it depends on **`ncu-report`**, which
is **proprietary NVIDIA software** — not open source. It is distributed under the
**NVIDIA Software License Agreement** (classifier `License :: Other/Proprietary
License`; see the `LICENSE.rst` bundled inside the installed `ncu_report` package,
and <https://docs.nvidia.com/nsight-compute/CopyrightAndLicenses/index.html>).

Notable terms of that agreement: it is non-transferable and non-sublicensable, it
is intended for developing applications for systems with NVIDIA GPUs, and it
restricts redistribution of the software as well as the publication of
benchmark/competitive comparisons against non-NVIDIA platforms without NVIDIA's
prior written permission.

`streamlit-ncu-rep-viewer` does **not** bundle or redistribute `ncu-report`; it is
declared as an ordinary dependency and installed by pip from NVIDIA's own
distribution, under NVIDIA's terms. Review that agreement before use or
redistribution.
