shap-cuda 0.54.1.dev0__tar.gz

shap_cuda-0.54.1.dev0/CMakeLists.txt

@@ -0,0 +1,80 @@
+cmake_minimum_required(VERSION 3.24...3.27)
+project(shap_cuda_extensions LANGUAGES CXX)
+
+if (NOT SKBUILD)
+  message(FATAL_ERROR "\
+  This CMakeLists.txt is meant to be used with scikit-build.
+  Please use 'python -m pip install .', not 'cmake'.")
+endif()
+
+if (CMAKE_VERSION VERSION_LESS 3.18)
+  set(DEV_MODULE Development)
+else()
+  set(DEV_MODULE Development.Module)
+endif()
+
+find_package(Python 3.12
+  COMPONENTS Interpreter ${DEV_MODULE} REQUIRED
+  OPTIONAL_COMPONENTS Development.SABIModule)
+
+if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "MinSizeRel" "RelWithDebInfo")
+endif()
+
+# Optional: CUDA may not be present (e.g. a docs build). In that case skip
+# _cext_gpu and install the pure-Python package only - GPUTreeExplainer's own
+# try/except around importing it degrades to a clear runtime error instead of
+# making the whole install fail.
+enable_language(CUDA OPTIONAL)
+
+if(CMAKE_CUDA_COMPILER)
+  find_package(CUDAToolkit)
+endif()
+
+if(CMAKE_CUDA_COMPILER AND CUDAToolkit_FOUND)
+  message(STATUS "CUDA toolkit found, building the _cext_gpu extension.")
+
+  if(NOT "${SKBUILD_SABI_VERSION}" STREQUAL "")
+    set(USE_SABI USE_SABI ${SKBUILD_SABI_VERSION})
+  endif()
+
+  python_add_library(
+    _cext_gpu MODULE
+
+    ${USE_SABI} WITH_SOABI
+
+    # The .cu file is compiled by nvcc, the .cc file by the host compiler
+    shap_cuda/cext/_cext_gpu.cu
+    shap_cuda/cext/_cext_gpu.cc
+  )
+
+  execute_process(
+      COMMAND "${PYTHON_EXECUTABLE}"
+      -c "import numpy; print(numpy.get_include())"
+      OUTPUT_VARIABLE NUMPY_INCLUDE_DIR
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+  )
+
+  target_include_directories(_cext_gpu PUBLIC ${NUMPY_INCLUDE_DIR})
+  target_link_libraries(_cext_gpu PRIVATE CUDA::cudart)
+
+  set_target_properties(_cext_gpu PROPERTIES
+    CUDA_ARCHITECTURES "60;70;75;80"
+    CUDA_STANDARD 14
+    CUDA_EXTENSIONS ON
+  )
+
+  target_compile_options(_cext_gpu PRIVATE
+    $<$<COMPILE_LANGUAGE:CUDA>:
+      --expt-extended-lambda
+      --expt-relaxed-constexpr
+    >
+  )
+
+  install(TARGETS _cext_gpu LIBRARY DESTINATION shap_cuda)
+else()
+  message(STATUS "CUDA toolkit not found, skipping the _cext_gpu extension. "
+                  "shap-cuda will install as Python-only; GPUTreeExplainer will "
+                  "raise a clear error when actually used.")
+endif()

shap_cuda-0.54.1.dev0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.1
+Name: shap-cuda
+Version: 0.54.1.dev0
+Summary: CUDA-accelerated GPUTreeExplainer backend for shap.
+Author-Email: Scott Lundberg <slund1@cs.washington.edu>
+License: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Project-URL: Repository, http://github.com/shap/shap
+Requires-Python: >=3.12
+Requires-Dist: shap
+Requires-Dist: numpy<2.5,>=2
+Requires-Dist: packaging>20.9
+Description-Content-Type: text/markdown
+
+# shap-cuda
+
+CUDA-accelerated `GPUTreeExplainer` backend for [shap](https://github.com/shap/shap).
+
+Installing this package registers `GPUTreeExplainer` with `shap` via the
+`shap.tree_backends` entry-point group; use it through `shap.GPUTreeExplainer`,
+not by importing `shap_cuda` directly.
+
+## Build locally from source
+
+Build both `shap` and `shap-cuda` from the same checkout: the backend uses SHAP
+internals and checks that their release versions match. The commands below are
+for Linux and run from the repository root, not this backend directory.
+
+### Prerequisites
+
+- Python 3.12 or newer; Python 3.13 is used in the examples below.
+- A C++ compiler and Python development headers (on Ubuntu/Debian, install
+  `build-essential` and the development package for your Python version).
+- The NVIDIA CUDA toolkit, including `nvcc`. CI builds with CUDA 12.8; the
+  backend currently targets GPU architectures `60`, `70`, `75`, and `80`, so
+  use a toolkit that supports those targets.
+- An NVIDIA GPU and a compatible NVIDIA driver to run explanations. Building
+  the extension does not require a physical GPU.
+
+Check that the toolkit and driver are available:
+
+```bash
+nvcc --version
+nvidia-smi
+```
+
+If the toolkit is installed outside your `PATH`, point the build at it. Adjust
+this example to your installation:
+
+```bash
+export PATH=/usr/local/cuda-12.8/bin:$PATH
+export CUDACXX=/usr/local/cuda-12.8/bin/nvcc
+```
+
+The build backend installs CMake (3.24 or newer) and its other Python build
+dependencies in an isolated environment as needed. The separate CUDA backend
+does not require the old `SHAP_ENABLE_CUDA` environment variable.
+
+### Install with uv
+
+```bash
+uv venv --python 3.13
+source .venv/bin/activate
+uv sync --extra cuda
+```
+
+The repository's uv workspace resolves the `cuda` extra to the local
+`backends/shap-cuda` package and builds both packages as editable installs.
+
+### Install with pip
+
+Alternatively, create and activate a virtual environment, then explicitly
+install both local packages:
+
+```bash
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -v -e . -e ./backends/shap-cuda
+```
+
+Using `pip install -e '.[cuda]'` alone can resolve `shap-cuda` from a package
+index instead of this checkout; pip does not use uv's workspace configuration.
+
+### Verify and use the backend
+
+Confirm that the compiled extension loads and that SHAP discovers the backend:
+
+```bash
+python -c "import shap; import shap_cuda._cext_gpu; print(shap.GPUTreeExplainer)"
+```
+
+Importing the extension directly here is a build check. For explanations, use
+the public SHAP API:
+
+```python
+import numpy as np
+import shap
+from sklearn.tree import DecisionTreeRegressor
+
+X = np.array([[0., 0.], [0., 1.], [1., 0.], [1., 1.]])
+model = DecisionTreeRegressor(max_depth=2).fit(X, X[:, 0] + X[:, 1])
+explainer = shap.GPUTreeExplainer(model)
+values = explainer.shap_values(X)
+print(values)
+```
+
+This example also checks that GPU execution works. Importing the package alone
+does not prove that the CUDA extension was built. In verbose build output,
+look for `CUDA toolkit found, building the _cext_gpu extension.` If the
+extension is missing or the build cannot find `nvcc`, check `CUDACXX` and the
+toolkit installation, then rebuild:
+
+```bash
+# uv
+uv sync --extra cuda --reinstall-package shap-cuda
+
+# Or pip; --no-deps keeps the existing local SHAP installation.
+python -m pip install -v --no-cache-dir --force-reinstall --no-deps -e ./backends/shap-cuda
+```

shap_cuda-0.54.1.dev0/README.md

@@ -0,0 +1,106 @@
+# shap-cuda
+
+CUDA-accelerated `GPUTreeExplainer` backend for [shap](https://github.com/shap/shap).
+
+Installing this package registers `GPUTreeExplainer` with `shap` via the
+`shap.tree_backends` entry-point group; use it through `shap.GPUTreeExplainer`,
+not by importing `shap_cuda` directly.
+
+## Build locally from source
+
+Build both `shap` and `shap-cuda` from the same checkout: the backend uses SHAP
+internals and checks that their release versions match. The commands below are
+for Linux and run from the repository root, not this backend directory.
+
+### Prerequisites
+
+- Python 3.12 or newer; Python 3.13 is used in the examples below.
+- A C++ compiler and Python development headers (on Ubuntu/Debian, install
+  `build-essential` and the development package for your Python version).
+- The NVIDIA CUDA toolkit, including `nvcc`. CI builds with CUDA 12.8; the
+  backend currently targets GPU architectures `60`, `70`, `75`, and `80`, so
+  use a toolkit that supports those targets.
+- An NVIDIA GPU and a compatible NVIDIA driver to run explanations. Building
+  the extension does not require a physical GPU.
+
+Check that the toolkit and driver are available:
+
+```bash
+nvcc --version
+nvidia-smi
+```
+
+If the toolkit is installed outside your `PATH`, point the build at it. Adjust
+this example to your installation:
+
+```bash
+export PATH=/usr/local/cuda-12.8/bin:$PATH
+export CUDACXX=/usr/local/cuda-12.8/bin/nvcc
+```
+
+The build backend installs CMake (3.24 or newer) and its other Python build
+dependencies in an isolated environment as needed. The separate CUDA backend
+does not require the old `SHAP_ENABLE_CUDA` environment variable.
+
+### Install with uv
+
+```bash
+uv venv --python 3.13
+source .venv/bin/activate
+uv sync --extra cuda
+```
+
+The repository's uv workspace resolves the `cuda` extra to the local
+`backends/shap-cuda` package and builds both packages as editable installs.
+
+### Install with pip
+
+Alternatively, create and activate a virtual environment, then explicitly
+install both local packages:
+
+```bash
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -v -e . -e ./backends/shap-cuda
+```
+
+Using `pip install -e '.[cuda]'` alone can resolve `shap-cuda` from a package
+index instead of this checkout; pip does not use uv's workspace configuration.
+
+### Verify and use the backend
+
+Confirm that the compiled extension loads and that SHAP discovers the backend:
+
+```bash
+python -c "import shap; import shap_cuda._cext_gpu; print(shap.GPUTreeExplainer)"
+```
+
+Importing the extension directly here is a build check. For explanations, use
+the public SHAP API:
+
+```python
+import numpy as np
+import shap
+from sklearn.tree import DecisionTreeRegressor
+
+X = np.array([[0., 0.], [0., 1.], [1., 0.], [1., 1.]])
+model = DecisionTreeRegressor(max_depth=2).fit(X, X[:, 0] + X[:, 1])
+explainer = shap.GPUTreeExplainer(model)
+values = explainer.shap_values(X)
+print(values)
+```
+
+This example also checks that GPU execution works. Importing the package alone
+does not prove that the CUDA extension was built. In verbose build output,
+look for `CUDA toolkit found, building the _cext_gpu extension.` If the
+extension is missing or the build cannot find `nvcc`, check `CUDACXX` and the
+toolkit installation, then rebuild:
+
+```bash
+# uv
+uv sync --extra cuda --reinstall-package shap-cuda
+
+# Or pip; --no-deps keeps the existing local SHAP installation.
+python -m pip install -v --no-cache-dir --force-reinstall --no-deps -e ./backends/shap-cuda
+```

shap_cuda-0.54.1.dev0/_build_backend.py

@@ -0,0 +1,38 @@
+"""PEP 517 build backend wrapping scikit-build-core.
+
+shap_cuda/cext/tree_shap.h is a symlink into the sibling shap/cext/ dir (the
+CPU and GPU extensions compile against the same header). scikit-build-core's
+sdist packaging preserves symlinks as-is, which produces a tarball that's
+broken once extracted outside this monorepo. build_sdist here swaps the
+symlink for its resolved file content before delegating, then restores it.
+"""
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from scikit_build_core import build as _skbuild
+
+_SYMLINKED_HEADERS: list[Path] = [Path(__file__).parent / "shap_cuda" / "cext" / "tree_shap.h"]
+
+
+def __getattr__(name: str) -> Any:
+    # Every PEP 517 hook other than build_sdist delegates to scikit-build-core unmodified.
+    return getattr(_skbuild, name)
+
+
+def build_sdist(sdist_directory: str, config_settings: dict[str, Any] | None = None) -> str:
+    materialized: list[tuple[Path, Path]] = []
+    try:
+        for header in _SYMLINKED_HEADERS:
+            if header.is_symlink():
+                resolved = header.resolve()
+                relative_target = Path("../../../../shap/cext") / header.name
+                header.unlink()
+                shutil.copyfile(resolved, header)
+                materialized.append((header, relative_target))
+        return _skbuild.build_sdist(sdist_directory, config_settings)
+    finally:
+        for header, relative_target in materialized:
+            header.unlink()
+            header.symlink_to(relative_target)

shap_cuda-0.54.1.dev0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = [
+  "scikit-build-core>=0.10.0",
+  "setuptools-scm>=8.0",
+  "numpy>=2.0",
+  "packaging>20.9",
+]
+build-backend = "_build_backend"
+backend-path = ["."]
+
+[project]
+name = "shap-cuda"
+description = "CUDA-accelerated GPUTreeExplainer backend for shap."
+readme = "README.md"
+license = {text = "MIT License"}
+authors = [
+  {name = "Scott Lundberg", email = "slund1@cs.washington.edu"},
+]
+requires-python = ">=3.12"
+dependencies = [
+  "shap",
+  "numpy>=2,<2.5",
+  "packaging>20.9",
+]
+classifiers = [
+  "Operating System :: POSIX",
+  "Operating System :: Unix",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Intended Audience :: Information Technology",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+]
+dynamic = ["version"]
+
+[project.entry-points."shap.tree_backends"]
+cuda = "shap_cuda:GPUTreeExplainer"
+
+[project.urls]
+Repository = 'http://github.com/shap/shap'
+
+[dependency-groups]
+test = ["pytest", "pytest-mpl", "pytest-cov", "xgboost", "lightgbm", "matplotlib", "ipython"]
+
+[tool.uv.sources]
+shap = {workspace = true}
+
+[tool.uv]
+cache-keys = [
+  { file = "shap_cuda/cext/*.cc" },
+  { file = "shap_cuda/cext/*.cu" },
+  { file = "shap_cuda/cext/*.h" },
+  { file = "CMakeLists.txt" },
+]
+
+[tool.setuptools_scm]
+root = "../.."
+version_file = "shap_cuda/_version.py"
+local_scheme = "no-local-version"
+
+[tool.scikit-build]
+wheel.packages = ["shap_cuda"]
+
+metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
+sdist.include = ["shap_cuda/_version.py"]
+
+minimum-version = "build-system.requires"
+build-dir = "build/{wheel_tag}"
+
+# Exclude C/C++/CUDA source files from the wheel (compiled .so is sufficient)
+wheel.exclude = ["**/*.cc", "**/*.cpp", "**/*.h", "**/*.cu"]
+
+wheel.py-api = "cp312"
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.pytest.ini_options]
+addopts = "--mpl -m 'not xslow'"
+mpl-default-style = "default"
+testpaths = ["tests"]
+markers = ["xslow: mark test as extremely slow (not run unless explicitly requested)"]

shap_cuda-0.54.1.dev0/shap_cuda/__init__.py

@@ -0,0 +1,8 @@
+from ._gpu_tree import GPUTreeExplainer
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0-not-built"
+
+__all__ = ["GPUTreeExplainer"]

shap_cuda-0.54.1.dev0/shap_cuda/_gpu_tree.py

@@ -0,0 +1,201 @@
+"""GPU accelerated tree explanations"""
+
+import numpy as np
+import shap
+from packaging.version import parse as _parse_version
+from shap.explainers._tree import (
+    TreeExplainer,
+    _xgboost_cat_unsupported,
+    feature_perturbation_codes,
+    output_transform_codes,
+)
+from shap.utils import assert_import, record_import_error
+
+try:
+    from ._version import version as _shap_cuda_version
+except ImportError:
+    _shap_cuda_version = "0.0.0-not-built"
+
+try:
+    from . import _cext_gpu  # type: ignore
+except ImportError as e:
+    record_import_error("cext_gpu", "cuda extension was not built during install!", e)
+
+
+def _check_versions_match() -> None:
+    shap_release = _parse_version(shap.__version__).release
+    shap_cuda_release = _parse_version(_shap_cuda_version).release
+    if shap_release != shap_cuda_release:
+        raise RuntimeError(
+            f"shap=={shap.__version__} and shap-cuda=={_shap_cuda_version} are from different "
+            "releases and are not guaranteed to be compatible. Reinstall matching versions, "
+            f"e.g. `pip install shap=={shap.__version__} shap-cuda=={shap.__version__}`."
+        )
+
+
+class GPUTreeExplainer(TreeExplainer):
+    """Experimental GPU accelerated version of TreeExplainer. Currently requires source build with
+    cuda available and 'CUDA_PATH' environment variable defined.
+
+    Examples
+    --------
+    See `GPUTree explainer examples <https://shap.readthedocs.io/en/latest/example_notebooks/api_examples/explainers/GPUTree.html>`_
+
+    """
+
+    def __init__(self, *args, **kwargs):
+        _check_versions_match()
+        super().__init__(*args, **kwargs)
+
+    def shap_values(self, X, y=None, tree_limit=None, approximate=False, check_additivity=True, from_call=False):
+        """Estimate the SHAP values for a set of samples.
+
+        Parameters
+        ----------
+        X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
+            A matrix of samples (# samples x # features) on which to explain the model's output.
+
+        y : numpy.array
+            An array of label values for each sample. Used when explaining loss functions.
+
+        tree_limit : None (default) or int
+            Limit the number of trees used by the model. By default None means no use the limit
+            of the
+            original model, and -1 means no limit.
+
+        approximate : bool
+            Not supported.
+
+        check_additivity : bool
+            Run a validation check that the sum of the SHAP values equals the output of the
+            model. This
+            check takes only a small amount of time, and will catch potential unforeseen errors.
+            Note that this check only runs right now when explaining the margin of the model.
+
+        Returns
+        -------
+        array or list
+            For models with a single output this returns a matrix of SHAP values
+            (# samples x # features). Each row sums to the difference between the model output
+            for that
+            sample and the expected value of the model output (which is stored in the expected_value
+            attribute of the explainer when it is constant). For models with vector outputs this
+            returns
+            a list of such matrices, one for each output.
+
+        """
+        assert not approximate, "approximate not supported"
+
+        X, y, X_missing, flat_output, tree_limit, check_additivity = self._validate_inputs(
+            X, y, tree_limit, check_additivity
+        )
+
+        model = self.model
+        _xgboost_cat_unsupported(model)
+        transform = model.get_transform()
+
+        # run the core algorithm using the C extension
+        assert_import("cext_gpu")
+        phi = np.zeros((X.shape[0], X.shape[1] + 1, self.model.num_outputs))
+        _cext_gpu.dense_tree_shap(
+            self.model.children_left,
+            self.model.children_right,
+            self.model.children_default,
+            self.model.features,
+            self.model.thresholds,
+            self.model.threshold_types,
+            self.model.values,
+            self.model.node_sample_weight,
+            self.model.max_depth,
+            X,
+            X_missing,
+            y,
+            self.data,
+            self.data_missing,
+            tree_limit,
+            self.model.base_offset,
+            phi,
+            feature_perturbation_codes[self.feature_perturbation],
+            output_transform_codes[transform],
+            False,
+        )
+
+        out = self._get_shap_output(phi, flat_output)
+        if check_additivity and self.model.model_output == "raw":
+            self.assert_additivity(out, self.model.predict(X))  # type: ignore[arg-type]
+
+        return out
+
+    def shap_interaction_values(self, X, y=None, tree_limit=None):
+        """Estimate the SHAP interaction values for a set of samples.
+
+        Parameters
+        ----------
+        X : numpy.array, pandas.DataFrame or catboost.Pool (for catboost)
+            A matrix of samples (# samples x # features) on which to explain the model's output.
+
+        y : numpy.array
+            An array of label values for each sample. Used when explaining loss functions (not
+            yet supported).
+
+        tree_limit : None (default) or int
+            Limit the number of trees used by the model. By default None means no use the limit
+            of the
+            original model, and -1 means no limit.
+
+        Returns
+        -------
+        array or list
+            For models with a single output this returns a tensor of SHAP values
+            (# samples x # features x # features). The matrix (# features x # features) for each
+            sample sums
+            to the difference between the model output for that sample and the expected value of
+            the model output
+            (which is stored in the expected_value attribute of the explainer). Each row of this
+            matrix sums to the
+            SHAP value for that feature for that sample. The diagonal entries of the matrix
+            represent the
+            "main effect" of that feature on the prediction and the symmetric off-diagonal
+            entries represent the
+            interaction effects between all pairs of features for that sample. For models with
+            vector outputs
+            this returns a list of tensors, one for each output.
+
+        """
+        if self.model.model_output != "raw":
+            raise ValueError('Only model_output = "raw" is supported for SHAP interaction values right now!')
+        if self.feature_perturbation == "interventional":
+            raise ValueError(
+                'feature_perturbation="interventional" is not yet supported for interaction values. '
+                'Use feature_perturbation="tree_path_dependent" instead.'
+            )
+        transform = "identity"
+
+        X, y, X_missing, flat_output, tree_limit, _ = self._validate_inputs(X, y, tree_limit, False)
+        # run the core algorithm using the C extension
+        assert_import("cext_gpu")
+        phi = np.zeros((X.shape[0], X.shape[1] + 1, X.shape[1] + 1, self.model.num_outputs))
+        _cext_gpu.dense_tree_shap(
+            self.model.children_left,
+            self.model.children_right,
+            self.model.children_default,
+            self.model.features,
+            self.model.thresholds,
+            self.model.threshold_types,
+            self.model.values,
+            self.model.node_sample_weight,
+            self.model.max_depth,
+            X,
+            X_missing,
+            y,
+            self.data,
+            self.data_missing,
+            tree_limit,
+            self.model.base_offset,
+            phi,
+            feature_perturbation_codes[self.feature_perturbation],
+            output_transform_codes[transform],
+            True,
+        )
+
+        return self._get_shap_interactions_output(phi, flat_output)

shap_cuda-0.54.1.dev0/shap_cuda/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.54.1.dev0'
+__version_tuple__ = version_tuple = (0, 54, 1, 'dev0')
+
+__commit_id__ = commit_id = 'g7d48b3044'