gtop 0.1.0__tar.gz

gtop-0.1.0/LICENSE

@@ -0,0 +1,10 @@
+ The MIT License (MIT)
+
+Copyright © 2025 <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

gtop-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: gtop
+Version: 0.1.0
+Summary: A lightweight CLI tool to monitor GPU
+Author-email: Hossein Ghorbanfekr <hgh.comphys@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hghcomphys/gpu-monitoring-tool
+Project-URL: Repository, https://github.com/hghcomphys/gpu-monitoring-tool
+Keywords: GPU
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nvidia-ml-py>=11.450.129
+Requires-Dist: plotext>=5.2.8
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# GPU Monitoring Tool
+
+A lightweight CLI tool to monitor GPU.
+
+## Motivation
+Current GPU monitoring tools often fall short in two ways:
+
+* No PCI throughput metrics: RX and TX metrics are important, as data transfer between CPU and GPU is frequently the computational bottleneck.
+* Inflexible metric selection: Users should be able to customize which metrics they need to measure, rather than being limited to predefined sets.
+
+<!--
+## Features
+The following features are planned for this tool:
+
+[x] Basic metrics like GPU utilization, memory usage, PCI throughput
+[x] Targeting Nvidia GPUs, with potential extension to AMD GPUs
+* A table of GPU processes
+* User-level customization 
+* Lightweight and minimal
+* Multiple GPU support 
+-->
+
+## Installation
+To install `gtop`, run the following command:
+```bash
+pip install --user gtop
+```
+This will install required dependencies and add `gtop` to your user-specific executable path (`~/.local/bin`). 
+You can then run `gtop` directly.
+
+To uninstall `gtop`, use the following command:
+```bash
+pip uninstall gtop
+```
+
+## Examples
+A screenshot of `gtop` in action is shown below:
+
+<img src="docs/images/screenshot.png" alt="demo screemshot" width="700"/>
+
+### Text-mode
+Text mode can be enabled via `--text-mode` or `-t` flag:
+```bash
+$ gtop -t
+CollectedMetrics(Time=0.10(s), PCI-TX=0.00(MB/s), PCI-RX=0.00(MB/s), Process=0.00(%), Memory=2.31(%))
+CollectedMetrics(Time=1.13(s), PCI-TX=0.00(MB/s), PCI-RX=0.00(MB/s), Process=0.00(%), Memory=2.31(%))
+...
+CollectedMetrics(Time=10.14(s), PCI-TX=0.01(MB/s),  PCI-RX=42.37(MB/s), Process=100.00(%), Memory=3.74(%))
+CollectedMetrics(Time=11.18(s), PCI-TX=11.02(MB/s), PCI-RX=0.03(MB/s),  Process=100.00(%), Memory=3.74(%))
+```
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gtop-0.1.0/README.md

@@ -0,0 +1,53 @@
+# GPU Monitoring Tool
+
+A lightweight CLI tool to monitor GPU.
+
+## Motivation
+Current GPU monitoring tools often fall short in two ways:
+
+* No PCI throughput metrics: RX and TX metrics are important, as data transfer between CPU and GPU is frequently the computational bottleneck.
+* Inflexible metric selection: Users should be able to customize which metrics they need to measure, rather than being limited to predefined sets.
+
+<!--
+## Features
+The following features are planned for this tool:
+
+[x] Basic metrics like GPU utilization, memory usage, PCI throughput
+[x] Targeting Nvidia GPUs, with potential extension to AMD GPUs
+* A table of GPU processes
+* User-level customization 
+* Lightweight and minimal
+* Multiple GPU support 
+-->
+
+## Installation
+To install `gtop`, run the following command:
+```bash
+pip install --user gtop
+```
+This will install required dependencies and add `gtop` to your user-specific executable path (`~/.local/bin`). 
+You can then run `gtop` directly.
+
+To uninstall `gtop`, use the following command:
+```bash
+pip uninstall gtop
+```
+
+## Examples
+A screenshot of `gtop` in action is shown below:
+
+<img src="docs/images/screenshot.png" alt="demo screemshot" width="700"/>
+
+### Text-mode
+Text mode can be enabled via `--text-mode` or `-t` flag:
+```bash
+$ gtop -t
+CollectedMetrics(Time=0.10(s), PCI-TX=0.00(MB/s), PCI-RX=0.00(MB/s), Process=0.00(%), Memory=2.31(%))
+CollectedMetrics(Time=1.13(s), PCI-TX=0.00(MB/s), PCI-RX=0.00(MB/s), Process=0.00(%), Memory=2.31(%))
+...
+CollectedMetrics(Time=10.14(s), PCI-TX=0.01(MB/s),  PCI-RX=42.37(MB/s), Process=100.00(%), Memory=3.74(%))
+CollectedMetrics(Time=11.18(s), PCI-TX=11.02(MB/s), PCI-RX=0.03(MB/s),  Process=100.00(%), Memory=3.74(%))
+```
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gtop-0.1.0/gtop/cli.py

@@ -0,0 +1,56 @@
+import argparse
+import time
+import plotext as plt
+from gtop.collector import collect
+from gtop.config import Config
+from gtop.device import free_device, get_device
+from gtop.visualizer import visualize
+from gtop.metrics import Metrics
+from gtop.collector import CollectedMetricsBuffer
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="A basic CLI tool to Monitor GPU.")
+    parser.add_argument(
+        "--device-gpu-index",
+        "-g",
+        type=int,
+        default=0,
+        help="GPU index to monitor (default: 0)",
+    )
+    parser.add_argument(
+        "--update-interval",
+        "-u",
+        type=float,
+        default=1.0,
+        help="Time interval between updates in seconds (default: 1.0)",
+    )
+    parser.add_argument(
+        "--text-mode",
+        "-t",
+        action='store_true',
+        help="Enable text mode (default: False)",
+    )
+    return parser.parse_args()
+
+
+def main():
+    cfg = Config.from_parser(args=parse_arguments())
+    handle = get_device(cfg)
+    metrics = Metrics.for_device(handle)
+    buffer = CollectedMetricsBuffer(size=cfg.collector_buffer_size)
+    start_time = time.time()
+    try:
+        while True:
+            collected_metrics = collect(metrics, handle, start_time, cfg)
+            buffer.append(collected_metrics)
+            visualize(buffer, plt, cfg)
+            time.sleep(cfg.update_interval)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        free_device()
+
+
+if __name__ == "__main__":
+    main()

gtop-0.1.0/gtop/collector.py

@@ -0,0 +1,68 @@
+import time
+from dataclasses import dataclass, field
+from typing import List
+from gtop.config import Config
+from gtop.device import DeviceHandle
+from gtop.metrics import Metrics
+
+
+@dataclass
+class CollectedMetrics:
+    timestamp: float
+    pci_tx: float
+    pci_rx: float
+    process: float
+    memory: float
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"Time={self.timestamp:0.2f}(s)"
+            f", PCI-TX={self.pci_tx:0.2f}(MB/s)"
+            f", PCI-RX={self.pci_rx:0.2f}(MB/s)"
+            f", Process={self.process:0.2f}(%)"
+            f", Memory={self.memory:0.2f}(%)"
+            ")"
+        )
+
+
+@dataclass
+class CollectedMetricsBuffer:
+    size: int
+    buffer: List[CollectedMetrics] = field(default_factory=list)
+
+    def append(self, item: CollectedMetrics) -> None:
+        self.buffer.append(item)
+        if len(self.buffer) > self.size:
+            self.buffer = self.buffer[-self.size :]
+
+    def __iter__(self):
+        for item in self.buffer:
+            yield item
+
+    @property
+    def last(self) -> CollectedMetrics:
+        return self.buffer[-1]
+
+    @property
+    def first(self) -> CollectedMetrics:
+        return self.buffer[0]
+
+
+def collect(
+    metrics: Metrics,
+    handle: DeviceHandle,
+    start_time: float,
+    cfg: Config,
+) -> CollectedMetrics:
+    now = time.time() - start_time
+    tx, rx = metrics.pci_throughput.measure()
+    process = metrics.gpu_processs.measure()
+    mem_used, mem_total = metrics.gpu_memory.measure()
+    return CollectedMetrics(
+        timestamp=max(now, cfg.collector_min_time_interval),
+        pci_tx=tx,
+        pci_rx=rx,
+        process=process,
+        memory=mem_used / mem_total * 100,
+    )

gtop-0.1.0/gtop/config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+from argparse import Namespace
+
+
+@dataclass
+class Config:
+    device_gpu_index: int = 0
+    update_interval: float = 1.0
+    text_mode: bool = False
+    collector_buffer_size: int = 60
+    collector_min_time_interval: float = 0.1
+    visualizer_plot_size: Optional[tuple[int, int]] = None
+    visualizer_plot_theme: Optional[str] = "matrix"
+    visualizer_plot_marker: str = "dot"
+    visualizer_plot_time_range: float = 60
+
+    @classmethod
+    def from_parser(
+        cls,
+        args: Namespace,
+        cfg: Optional[Config] = None,
+    ) -> Config:
+        if cfg is None:
+            cfg = get_default_config()
+        return cls(
+            **{
+                **cfg.__dict__,
+                **{k: v for k, v in vars(args).items() if v is not None},
+            }
+        )
+
+
+def get_default_config():
+    return Config()

gtop-0.1.0/gtop/device.py

@@ -0,0 +1,19 @@
+import sys
+import pynvml
+from gtop.config import Config
+
+DeviceHandle = pynvml.struct_c_nvmlDevice_t
+
+def get_device(cfg: Config) -> DeviceHandle:
+    try:
+        pynvml.nvmlInit()
+        handle = pynvml.nvmlDeviceGetHandleByIndex(cfg.device_gpu_index)
+
+    except pynvml.NVMLError as error:
+        print(f"GPU Not Detected! ({error})")
+        sys.exit(1)
+    return handle
+
+
+def free_device() -> None:
+    pynvml.nvmlShutdown()

gtop-0.1.0/gtop/metrics.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Protocol
+import pynvml
+
+from gtop.device import DeviceHandle
+from typing import Any, Tuple
+
+
+class MetricInterface(Protocol):
+    def measure() -> Any:
+        ...
+
+
+@dataclass
+class PciThroughputMetric(MetricInterface):
+    handle: DeviceHandle
+
+    def measure(self) -> Tuple[float, float]:
+        tx = (
+            pynvml.nvmlDeviceGetPcieThroughput(
+                self.handle,
+                pynvml.NVML_PCIE_UTIL_TX_BYTES,
+            )
+            / 1024
+        )
+        rx = (
+            pynvml.nvmlDeviceGetPcieThroughput(
+                self.handle,
+                pynvml.NVML_PCIE_UTIL_RX_BYTES,
+            )
+            / 1024
+        )
+        return tx, rx  # MB
+
+
+@dataclass
+class GpuProcessMetric(MetricInterface):
+    handle: DeviceHandle
+
+    def measure(self) -> float:
+        util = pynvml.nvmlDeviceGetUtilizationRates(self.handle)
+        return util.gpu
+
+
+@dataclass
+class GpuMemoryMetric(MetricInterface):
+    handle: DeviceHandle
+
+    def measure(self) -> Tuple[float, float]:
+        mem_info = pynvml.nvmlDeviceGetMemoryInfo(self.handle)
+        mem_used = int(mem_info.used / 1024**2)
+        mem_total = int(mem_info.total / 1024**2)
+        return mem_used, mem_total  # MB
+
+
+@dataclass
+class Metrics:
+    pci_throughput: PciThroughputMetric
+    gpu_processs: GpuProcessMetric
+    gpu_memory: GpuMemoryMetric
+
+    @classmethod
+    def for_device(cls, handle: DeviceHandle):
+        return cls(
+            PciThroughputMetric(handle),
+            GpuProcessMetric(handle),
+            GpuMemoryMetric(handle),
+        )

gtop-0.1.0/gtop/visualizer.py

@@ -0,0 +1,68 @@
+from gtop.config import Config
+from gtop.collector import CollectedMetricsBuffer
+from typing import Any
+
+PlotHandle = Any
+
+
+def visualize(
+    inputs: CollectedMetricsBuffer,
+    plt: PlotHandle,
+    cfg: Config,
+) -> None:
+    if cfg.text_mode:
+        printout_metrics(inputs)
+        return
+    plt.clt()
+    plt.cld()
+    plt.subplots(1, 2)
+    plt.theme(cfg.visualizer_plot_theme)
+    plt.plotsize(cfg.visualizer_plot_size)
+    # --------------
+    plt.subplot(1, 2)
+    timestamps = [input.timestamp for input in inputs]
+    pci_tx_values = [input.pci_tx for input in inputs]
+    pci_rx_values = [input.pci_rx for input in inputs]
+    plt.plot(
+        timestamps,
+        pci_tx_values,
+        label="TX",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.plot(
+        timestamps,
+        pci_rx_values,
+        label="RX",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.title("GPU PCIe Throughput")
+    plt.xlabel("Time (s)")
+    plt.ylabel("Throughput (MB/s)")
+    plt.ylim(0, max(1, max(pci_tx_values + pci_rx_values) * 1.2))
+
+    # --------------
+    plt.subplot(1, 1)
+    process_values = [input.process for input in inputs]
+    memory_values = [input.memory for input in inputs]
+    plt.plot(
+        timestamps,
+        process_values,
+        label="Process",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.plot(
+        timestamps,
+        memory_values,
+        label="Memory",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.title("GPU Utilization")
+    plt.xlabel("Time (s)")
+    plt.ylabel("Utilization (%)")
+    plt.ylim(0, 100)
+
+    plt.show()
+
+
+def printout_metrics(inputs: CollectedMetricsBuffer) -> None:
+    print(inputs.last)

gtop-0.1.0/gtop/visualizer_barplots.py

@@ -0,0 +1,79 @@
+from gtop.config import Config
+from gtop.metrics import Metrics
+from typing import Any
+
+PlotHandle = Any
+
+
+def visualize(
+    metrics: Metrics,
+    plt: PlotHandle,
+    cfg: Config,
+) -> None:
+    plt.clt()
+    plt.cld()
+    plt.theme(cfg.visualizer_plot_theme)
+    plt.plotsize(cfg.visualizer_plot_size)
+    plt.subplots(1, 2)
+
+    # plt.subplot(1, 1)
+    # names = [
+    #     "Process",
+    #     "Memory",
+    #     "TX",
+    #     "RX",
+    # ]
+    # values = [
+    #     metrics.util_values[-1],
+    #     metrics.mem_values[-1],
+    #     metrics.rx_values[-1],
+    #     metrics.tx_values[-1],
+    # ]
+    # plt.simple_bar(
+    #     names,
+    #     values,
+    #     # width=100,
+    #     title="GPU Utilization",
+    # )
+    # plt.xlabel("Percentage")
+    # plt.xlim(0, 100)
+    
+    # --------------
+    plt.subplot(1, 1)
+    plt.plot(
+        metrics.times,
+        metrics.util_values,
+        label="Process",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.plot(
+        metrics.times,
+        metrics.mem_values,
+        label="Memory",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.title("GPU Utilization")
+    plt.xlabel("Time (s)")
+    plt.ylabel("Utilization (%)")
+    plt.ylim(0, 100)
+    # --------------
+    plt.subplot(1, 2)
+    plt.plot(
+        metrics.times,
+        metrics.tx_values,
+        label="TX",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.plot(
+        metrics.times,
+        metrics.rx_values,
+        label="RX",
+        marker=cfg.visualizer_plot_marker,
+    )
+    plt.title("GPU PCIe Throughput")
+    plt.xlabel("Time (s)")
+    plt.ylabel("Throughput (MB/s)")
+    plt.ylim(0, max(1, max(metrics.tx_values + metrics.rx_values) * 1.2))
+
+    plt.sleep(cfg.update_interval)
+    plt.show()

gtop-0.1.0/gtop.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: gtop
+Version: 0.1.0
+Summary: A lightweight CLI tool to monitor GPU
+Author-email: Hossein Ghorbanfekr <hgh.comphys@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hghcomphys/gpu-monitoring-tool
+Project-URL: Repository, https://github.com/hghcomphys/gpu-monitoring-tool
+Keywords: GPU
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nvidia-ml-py>=11.450.129
+Requires-Dist: plotext>=5.2.8
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# GPU Monitoring Tool
+
+A lightweight CLI tool to monitor GPU.
+
+## Motivation
+Current GPU monitoring tools often fall short in two ways:
+
+* No PCI throughput metrics: RX and TX metrics are important, as data transfer between CPU and GPU is frequently the computational bottleneck.
+* Inflexible metric selection: Users should be able to customize which metrics they need to measure, rather than being limited to predefined sets.
+
+<!--
+## Features
+The following features are planned for this tool:
+
+[x] Basic metrics like GPU utilization, memory usage, PCI throughput
+[x] Targeting Nvidia GPUs, with potential extension to AMD GPUs
+* A table of GPU processes
+* User-level customization 
+* Lightweight and minimal
+* Multiple GPU support 
+-->
+
+## Installation
+To install `gtop`, run the following command:
+```bash
+pip install --user gtop
+```
+This will install required dependencies and add `gtop` to your user-specific executable path (`~/.local/bin`). 
+You can then run `gtop` directly.
+
+To uninstall `gtop`, use the following command:
+```bash
+pip uninstall gtop
+```
+
+## Examples
+A screenshot of `gtop` in action is shown below:
+
+<img src="docs/images/screenshot.png" alt="demo screemshot" width="700"/>
+
+### Text-mode
+Text mode can be enabled via `--text-mode` or `-t` flag:
+```bash
+$ gtop -t
+CollectedMetrics(Time=0.10(s), PCI-TX=0.00(MB/s), PCI-RX=0.00(MB/s), Process=0.00(%), Memory=2.31(%))
+CollectedMetrics(Time=1.13(s), PCI-TX=0.00(MB/s), PCI-RX=0.00(MB/s), Process=0.00(%), Memory=2.31(%))
+...
+CollectedMetrics(Time=10.14(s), PCI-TX=0.01(MB/s),  PCI-RX=42.37(MB/s), Process=100.00(%), Memory=3.74(%))
+CollectedMetrics(Time=11.18(s), PCI-TX=11.02(MB/s), PCI-RX=0.03(MB/s),  Process=100.00(%), Memory=3.74(%))
+```
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gtop-0.1.0/gtop.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+gtop/__init__.py
+gtop/cli.py
+gtop/collector.py
+gtop/config.py
+gtop/device.py
+gtop/metrics.py
+gtop/visualizer.py
+gtop/visualizer_barplots.py
+gtop.egg-info/PKG-INFO
+gtop.egg-info/SOURCES.txt
+gtop.egg-info/dependency_links.txt
+gtop.egg-info/entry_points.txt
+gtop.egg-info/requires.txt
+gtop.egg-info/top_level.txt

gtop-0.1.0/gtop.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gtop-0.1.0/gtop.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gtop = gtop.cli:main

gtop-0.1.0/gtop.egg-info/requires.txt

@@ -0,0 +1,7 @@
+nvidia-ml-py>=11.450.129
+plotext>=5.2.8
+
+[dev]
+black
+isort
+pytest

gtop-0.1.0/gtop.egg-info/top_level.txt

@@ -0,0 +1 @@
+gtop

gtop-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires      = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["gtop"]
+
+[project]
+name = "gtop"
+version = "0.1.0"
+description = "A lightweight CLI tool to monitor GPU"
+readme = "README.md"
+authors = [{ name = "Hossein Ghorbanfekr", email = "hgh.comphys@gmail.com" }]
+license = "MIT"
+license-files= ["LICENSE"]
+keywords = ["GPU"]
+dependencies = [
+	'nvidia-ml-py>=11.450.129',
+	'plotext>=5.2.8',
+]
+requires-python = ">=3.8"
+
+[project.optional-dependencies]
+dev = ["black", "isort", "pytest"]
+
+[project.urls]
+Homepage = "https://github.com/hghcomphys/gpu-monitoring-tool" 
+Repository = "https://github.com/hghcomphys/gpu-monitoring-tool" 
+
+[project.scripts]
+gtop = "gtop.cli:main"

gtop-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+