reprospect 0.0.7__tar.gz

reprospect-0.0.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ULiege CSM
+
+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.

reprospect-0.0.7/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: reprospect
+Version: 0.0.7
+Summary: A framework for reproducible prospecting of CUDA applications.
+Author: Arnst Maarten, Tomasetti Romin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/uliegecsm/reprospect
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: attrs
+Requires-Dist: backports.strenum
+Requires-Dist: blake3
+Requires-Dist: cmake-file-api==0.0.8.3
+Requires-Dist: ijson
+Requires-Dist: mypy_extensions
+Requires-Dist: pandas
+Requires-Dist: pyelftools
+Requires-Dist: regex
+Requires-Dist: rich
+Requires-Dist: rich-tools
+Requires-Dist: semantic_version
+Requires-Dist: system-helpers>=0.0.3
+Requires-Dist: typing-extensions>=4.4.0
+Dynamic: license-file

reprospect-0.0.7/README.md

@@ -0,0 +1,11 @@
+![logo](docs/source/_static/logo.svg)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/reprospect?color=blue)](https://pypi.org/project/reprospect/)
+![PyPI - Wheel](https://img.shields.io/pypi/wheel/reprospect)
+![PyPI - Implementation](https://img.shields.io/pypi/implementation/reprospect)
+
+# reprospect
+
+`ReProspect` provides a framework and tools for reproducible prospecting of CUDA applications.
+
+See [the documentation](https://uliegecsm.github.io/reprospect/index.html) for more information.

reprospect-0.0.7/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = [
+    "setuptools",
+    "mypy[mypyc]==1.19.0",
+
+    # mypyc requires that runtime dependencies are also installed
+    # during the build, since it parses the code base.
+    # For now, the only solution is to copy-paste the list here.
+    "attrs",
+    "backports.strenum",
+    "blake3",
+    "cmake-file-api==0.0.8.3",
+    "ijson",
+    "mypy_extensions",
+    "pandas",
+    "pyelftools",
+    "regex",
+    "rich",
+    "rich-tools",
+    "semantic_version",
+    "system-helpers>=0.0.3",
+    "typing-extensions>=4.4.0",
+
+    # Requirements from requirements/requirements.python.txt that are required by mypyc.
+    "types-regex",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = [
+    "reprospect",
+    "reprospect.installers",
+    "reprospect.test",
+    "reprospect.test.sass",
+    "reprospect.test.sass.matchers",
+    "reprospect.tools",
+    "reprospect.tools.binaries",
+    "reprospect.tools.sass",
+    "reprospect.utils",
+]
+
+[tool.setuptools.dynamic]
+# https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html#dynamic-metadata
+dependencies = {file = ["requirements/requirements.txt"]}
+
+[project]
+name = "reprospect"
+description = "A framework for reproducible prospecting of CUDA applications."
+version = "0.0.7"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">= 3.10"
+dynamic = [
+    "dependencies",
+]
+authors = [
+  {name = "Arnst Maarten"},
+  {name = "Tomasetti Romin"},
+]
+
+[project.urls]
+Homepage = "https://github.com/uliegecsm/reprospect"
+
+[project.scripts]
+reprospect-install-cuda-bindings = "reprospect.installers.cuda_bindings:main"
+reprospect-install-nsight-systems = "reprospect.installers.nsight_systems:main"
+reprospect-utils-detect-gpus = "reprospect.utils.detect:main"
+
+[tool.mypy]
+follow_untyped_imports = true
+warn_unreachable = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+packages = ["reprospect"]
+
+[tool.ruff.lint.per-file-ignores]
+"docs/source/conf.py" = ["E402"]
+
+[tool.pylint.main]
+fail-on = [
+    "I",
+]
+fail-under = 10
+
+[tool.pylint."messages control"]
+enable = [
+    "useless-suppression",
+]
+disable = [
+    "c-extension-no-member",
+    "line-too-long",
+    "logging-fstring-interpolation",
+    "missing-class-docstring",
+    "missing-function-docstring",
+    "missing-module-docstring",
+    "too-few-public-methods",
+    "too-many-arguments",
+    "too-many-locals",
+    "too-many-positional-arguments",
+]
+
+[tool.cibuildwheel]
+build = []
+archs = []
+
+build-verbosity = 1

reprospect-0.0.7/reprospect/__init__.py

@@ -0,0 +1,6 @@
+from .test.case import TestCase, CMakeAwareTestCase
+
+__all__ = [
+    'CMakeAwareTestCase',
+    'TestCase',
+]

reprospect-0.0.7/reprospect/installers/cuda_bindings.py

@@ -0,0 +1,101 @@
+import argparse
+import json
+import logging
+import os
+import subprocess
+import urllib.request
+
+import packaging.version
+
+def get_available(package : str) -> list[packaging.version.Version]:
+    """
+    Get available versions of `package` from `PyPI`.
+    """
+    with urllib.request.urlopen(f'https://pypi.org/pypi/{package}/json') as resp:
+        data = json.load(resp)
+        return [packaging.version.Version(x) for x in data["releases"]]
+
+def get_candidate(*, target : packaging.version.Version, versions : list[packaging.version.Version]) -> packaging.version.Version | None:
+    """
+    Match exactly if possible; otherwise, match the closest lower patch version that has the same major and minor.
+    """
+    candidate = None
+
+    for version in versions:
+        # Reject pre/dev/post releases.
+        if version.pre or version.dev or version.post:
+            continue
+
+        # Exact match.
+        if version == target:
+            return version
+
+        if version.major == target.major and version.minor == target.minor:
+            if version < target and (candidate is None or version > candidate):
+                candidate = version
+    return candidate
+
+def install_cuda_bindings(target : packaging.version.Version) -> None:
+    """
+    Pick a version of ``cuda-bindings`` that best matches `target`.
+
+    .. warning::
+
+        ``cuda-bindings`` was once part of the ``cuda-python`` package, which is now a meta-package.
+        Therefore, installing ``cuda-bindings`` alone might be impossible for some versions.
+        For instance, there is no standalone ``cuda-bindings==12.6``, but this version can be installed
+        as part of ``cuda-python==12.6``.
+
+    References:
+
+    * https://nvidia.github.io/cuda-python/latest/
+    * https://nvidia.github.io/cuda-python/cuda-bindings/latest/
+    """
+    versions = get_available(package = 'cuda-bindings')
+    logging.info(f'Available versions for \'cuda-bindings\': {versions}.')
+
+    candidate = get_candidate(target = target, versions = versions)
+
+    if candidate is not None:
+        logging.info(f'Installing \'cuda-bindings\' {candidate}.')
+        requirement = f'cuda-bindings=={candidate}'
+    else:
+        logging.warning('Could not find a suitable version of \'cuda-bindings\'.')
+
+        versions = get_available(package = 'cuda-python')
+        logging.info(f'Available versions for \'cuda-python\': {versions}.')
+
+        candidate = get_candidate(target = target, versions = versions)
+
+        if candidate is None:
+            raise RuntimeError('Could not find a suitable version of \'cuda-python\'.')
+
+        logging.info(f'Installing \'cuda-python\' {candidate}.')
+        requirement = f'cuda-python=={candidate}'
+
+    subprocess.check_call(('pip', 'install', requirement))
+
+def parse_args() -> argparse.Namespace:
+    """
+    Parse CLI arguments.
+    """
+    parser = argparse.ArgumentParser(
+        formatter_class = argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    parser.add_argument('--version', type = packaging.version.Version, required = False, default = os.environ['CUDA_VERSION'])
+
+    return parser.parse_args()
+
+def main() -> None:
+
+    logging.basicConfig(level = logging.INFO)
+
+    args = parse_args()
+    logging.info(f'Received arguments: {args}.')
+
+    install_cuda_bindings(target = args.version)
+
+if __name__ == '__main__':
+
+    main()

reprospect-0.0.7/reprospect/installers/nsight_systems.py

@@ -0,0 +1,75 @@
+import argparse
+import logging
+import os
+import re
+import shutil
+import subprocess
+import typing
+
+import semantic_version
+
+import system_helpers.apt.install
+
+from reprospect.utils import nvcc
+
+PACKAGE : typing.Final[str] = 'cuda-nsight-systems'
+
+def parse_args() -> argparse.Namespace:
+    """
+    Parse CLI arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description = "Install Nsight Systems with apt.",
+        formatter_class = argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    parser.add_argument('--version', type = str, required = False, help = f'Version of the package ({PACKAGE}) to install.', default = detect_cuda_version())
+
+    return parser.parse_args()
+
+def install(*, args : argparse.Namespace) -> None:
+    """
+    Install `Nsight Systems` through `apt`.
+    """
+    package = PACKAGE + '-' + args.version
+    logging.info(f'Installing nsight-systems with {package}.')
+    system_helpers.apt.install.install_packages(
+        packages = [package],
+        update = True, clean = True,
+    )
+
+def detect_cuda_version() -> str:
+    """
+    Detect CUDA version using the following strategies:
+
+    #. ``CUDA_VERSION`` environment variable
+    #. ``nvidia-smi --query``
+    #. ``nvcc --version``
+    """
+    if 'CUDA_VERSION' in os.environ:
+        version = semantic_version.Version(os.environ['CUDA_VERSION'])
+        return f'{version.major}-{version.minor}'
+
+    if shutil.which('nvidia-smi') is not None:
+        for line in subprocess.check_output(('nvidia-smi', '--version')).decode().splitlines():
+            if "CUDA Version" in line and (matched := re.search(pattern = r'([0-9]+).([0-9]+)', string = line)) is not None:
+                return f'{matched.group(1)}-{matched.group(2)}'
+
+    if shutil.which('nvcc') is not None:
+        version = nvcc.get_version()
+        return f'{version.major}-{version.minor}'
+
+    raise RuntimeError("Could not deduce CUDA version.")
+
+def main() -> None:
+
+    logging.basicConfig(level = logging.INFO)
+
+    args = parse_args()
+    logging.info(f"Received arguments: {args}")
+
+    install(args = args)
+
+if __name__ == "__main__":
+
+    main()

reprospect-0.0.7/reprospect/test/case.py

@@ -0,0 +1,44 @@
+import abc
+import pathlib
+import typing
+
+from reprospect.tools.architecture import NVIDIAArch
+from reprospect.tools.binaries     import CuppFilt, LlvmCppFilt
+from reprospect.test.cmake         import CMakeMixin
+
+class TestCase(abc.ABC):
+    """
+    Test case.
+    """
+    @property
+    @abc.abstractmethod
+    def cwd(self) -> pathlib.Path:
+        """
+        Working directory.
+        """
+
+    @property
+    @abc.abstractmethod
+    def arch(self) -> NVIDIAArch:
+        """
+        NVIDIA architecture.
+        """
+
+    @property
+    @abc.abstractmethod
+    def executable(self) -> pathlib.Path:
+        """
+        Executable.
+        """
+
+    @property
+    @abc.abstractmethod
+    def demangler(self) -> typing.Type[CuppFilt | LlvmCppFilt]:
+        """
+        Demangler.
+        """
+
+class CMakeAwareTestCase(CMakeMixin, TestCase):
+    """
+    Test case with CMake integration.
+    """

reprospect-0.0.7/reprospect/test/cmake.py

@@ -0,0 +1,99 @@
+import abc
+import functools
+import json
+import pathlib
+import typing
+
+from reprospect.test.environment      import EnvironmentField
+from reprospect.tools.architecture    import NVIDIAArch
+from reprospect.tools.binaries        import CuppFilt, LlvmCppFilt
+from reprospect.utils                 import cmake
+from reprospect.utils.compile_command import get_arch_from_compile_command
+
+def get_demangler_for_compiler(compiler_id : str) -> typing.Type[CuppFilt | LlvmCppFilt]:
+    """
+    Get demangler for compiler with given id.
+    """
+    match compiler_id:
+        case 'NVIDIA':
+            return CuppFilt
+        case 'Clang':
+            return LlvmCppFilt
+        case _:
+            raise ValueError(f'unsupported compiler ID {compiler_id}')
+
+class CMakeMixin(abc.ABC):
+    """
+    Mixin to integrate with CMake build system.
+    """
+    CMAKE_BINARY_DIR = EnvironmentField(converter = pathlib.Path)
+    CMAKE_CURRENT_BINARY_DIR = EnvironmentField(converter = pathlib.Path)
+
+    @classmethod
+    @abc.abstractmethod
+    def get_target_name(cls) -> str:
+        pass
+
+    @functools.cached_property
+    def cwd(self) -> pathlib.Path:
+        """
+        Get working directory for the analysis based on the CMake current binary directory.
+        """
+        cwd = self.CMAKE_CURRENT_BINARY_DIR / (self.get_target_name() + '-case')
+        cwd.mkdir(parents = False, exist_ok = True)
+        return cwd
+
+    @functools.cached_property
+    def arch(self) -> NVIDIAArch:
+        """
+        Retrieve the NVIDIA architecture from the CMake compile command database.
+
+        We assume the target file was compiled for only a single architecture.
+
+        See also https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html.
+        """
+        with open(self.CMAKE_BINARY_DIR / 'compile_commands.json', 'r', encoding = 'utf-8') as fin:
+            commands = json.load(fin)
+        target_source = next(self.target_sources)
+        archs = get_arch_from_compile_command(cmd = next(filter(
+            lambda x: str(target_source) in x['file'],
+            commands))['command']
+        )
+        assert len(archs) == 1
+        return archs.pop()
+
+    @functools.cached_property
+    def cmake_file_api(self) -> cmake.FileAPI:
+        return cmake.FileAPI(cmake_build_directory = self.CMAKE_BINARY_DIR)
+
+    @functools.cached_property
+    def target(self) -> cmake.TargetDict:
+        """
+        Retrieve the target information from the CMake codemodel database.
+        """
+        return self.cmake_file_api.target(self.get_target_name())
+
+    @functools.cached_property
+    def target_sources(self) -> typing.Iterator[pathlib.Path]:
+        """
+        Retrieve the target source from the CMake codemodel database.
+        """
+        return map(lambda source: pathlib.Path(source['path']), self.target['sources'])
+
+    @functools.cached_property
+    def executable(self) -> pathlib.Path:
+        """
+        Retrieve the executable for the analysis from the CMake codemodel database.
+        """
+        return self.CMAKE_BINARY_DIR / self.target['paths']['build'] / self.target['nameOnDisk']
+
+    @functools.cached_property
+    def toolchains(self) -> cmake.ToolchainDict:
+        """
+        Retrieve the toolchains information from the read CMake file API.
+        """
+        return self.cmake_file_api.toolchains
+
+    @functools.cached_property
+    def demangler(self) -> typing.Type[CuppFilt | LlvmCppFilt]:
+        return get_demangler_for_compiler(self.toolchains['CUDA']['compiler']['id'])

reprospect-0.0.7/reprospect/test/environment.py

@@ -0,0 +1,97 @@
+import dataclasses
+import os
+import typing
+
+T = typing.TypeVar('T')
+"""Type variable for :py:class:`~EnvironmentField` and related generics."""
+
+@dataclasses.dataclass(slots = True)
+class EnvironmentField(typing.Generic[T]):
+    """
+    Descriptor that returns a value lazily read from an environment variable.
+
+    Based on:
+
+    * https://docs.python.org/3/howto/descriptor.html
+    * https://mypy.readthedocs.io/en/stable/generics.html#defining-generic-classes
+    """
+    env : typing.Optional[str] = None
+    """
+    Name of the environment variable.
+    """
+
+    converter : typing.Optional[typing.Callable[[str], T]] = None
+    """
+    Callable to convert the value of the environment variable to the target type.
+    """
+
+    default : typing.Optional[T] = None
+    """
+    Default value if the environment variable does not exist.
+    """
+
+    _cached : T | None = dataclasses.field(default = None, init = False, repr = False)
+    """
+    Value, cached.
+    """
+
+    _attr_name : str | None = dataclasses.field(default = None, init = False, repr = False)
+    """
+    Name of the attribute.
+    """
+
+    def __post_init__(self) -> None:
+        if self.default is not None and self.converter is None:
+            self.converter = type(self.default)
+
+    def __set_name__(self, owner : type, name: str) -> None:
+        """
+        References:
+
+        * https://docs.python.org/3/reference/datamodel.html#object.__set_name__
+        """
+        self._attr_name = name
+
+    @typing.overload
+    def __get__(self, instance: None, owner: type) -> "EnvironmentField[T]": ...
+
+    @typing.overload
+    def __get__(self, instance: object, owner: type) -> T: ...
+
+    def __get__(self, instance, owner = None):
+        """
+        References:
+
+        * https://docs.python.org/3/reference/datamodel.html#object.__get__
+        """
+        if instance is None:
+            return self
+
+        return self.read(instance = instance, owner = owner)
+
+    def read(self, instance, owner) -> T:
+        """
+        Read from the environment.
+        """
+        if self._cached is not None:
+            return self._cached
+
+        key = self.env or self._attr_name
+
+        if key is None:
+            raise AttributeError("Descriptor not initialized properly.")
+
+        if (value := os.getenv(key)) is not None and self.converter is not None:
+            self._cached = self.converter(value)
+        elif self.default is not None:
+            self._cached = self.default
+        else:
+            raise RuntimeError(f"Missing required environment variable {key!r} or converter or default value for {instance.__class__ if instance else owner}.")
+
+        return self._cached
+
+    def reset(self) -> None:
+        """
+        Reset, thus forcing a re-read from environment on next access.
+        """
+        self._cached = None