安装#

安装 nvmath-python#

nvmath-python，像大多数现代 Python 包一样，为最终用户提供了预构建的二进制文件（wheels 和后续的 conda 包）。完整的源代码托管在 NVIDIA/nvmath-python 仓库中。

在 CUDA 工具包 (CTK) 选择方面，nvmath-python 的设计和实现允许针对以下环境进行构建和运行：1. pip-wheel，2. conda，或 3. CTK 的系统安装。在构建时或运行时不必安装完整的 CTK；如下所述，只需一小部分就足够了。

主机和设备 API（请参阅概述）具有不同的运行时依赖项和要求。即使在主机 API 中，所需的底层库也不同（例如，GPU 上的 fft() 只需要 cuFFT 而不需要 cuBLAS）。库仅在需要时加载。因此，nvmath-python 被设计为使其大多数依赖项都是可选的，但为用户提供了方便的安装命令，以便快速启动一个可用的 Python 环境。

下面的速查表捕捉了 nvmath-python 的必需/可选、构建/运行时依赖项。使用下面章节中的安装命令应能满足您的大部分需求。

从 PyPI 安装#

预构建的 wheels 可以通过 pip 从公共 PyPI 安装。有几个可选的依赖项可以使用标准的“extras”括号表示法来表示。以下假设 CTK 组件也通过 pip 安装（因此用户无需额外的步骤；依赖项通过 extras 拉取）。

命令	描述
`pip install nvmath-python[cu11]`	安装 nvmath-python 以及所有 CUDA 11 可选依赖项（cuBLAS/cuFFT/… 和 CuPy 的 wheels）以支持 nvmath 主机 API。
`pip install nvmath-python[cu12]`	安装 nvmath-python 以及所有 CUDA 12 可选依赖项（cuBLAS/cuFFT/… 和 CuPy 的 wheels）以支持 nvmath 主机 API。
`pip install nvmath-python[cu12,dx]`	安装 nvmath-python 以及所有 CUDA 12 可选依赖项（cuBLAS/cuFFT/…、CuPy、Numba、pynvjitlink、… 的 wheels）以支持 nvmath 主机和设备 API（仅支持 CUDA 12） [8]。
`pip install nvmath-python[cpu]`	安装 nvmath-python 以及所有 CPU 可选依赖项（NVPL 或 MKL 的 wheels）以支持优化的 CPU FFT API。 [1] 注意: NVPL 仅适用于 ARM 架构。MKL 或另一个 FFTW3 [9] 兼容库可以替代 x86 架构。环境变量 `NVMATH_FFT_CPU_LIBRARY` 可用于提供实现了 FFTW3（非 guru）API 的备用共享对象的路径。`LD_LIBRARY_PATH` 应正确设置以包含此库（如果它尚未在 PATH 中）。

以下选项适用于希望自行管理大多数依赖项的冒险用户。以下假设 系统 CTK 已安装。

命令	描述
`pip install nvmath-python[sysctk11]`	安装 nvmath-python 以及 CUDA 11 的 CuPy 以支持 nvmath 主机 API。注意： `LD_LIBRARY_PATH` 应正确设置以包含 CUDA 库。
`pip install nvmath-python[sysctk12]`	安装 nvmath-python 以及 CUDA 12 的 CuPy 以支持 nvmath 主机 API。注意： `LD_LIBRARY_PATH` 应正确设置以包含 CUDA 库。
`pip install nvmath-python[sysctk12-dx]`	安装 nvmath-python 以及 CUDA 12 的 CuPy 以支持 nvmath 主机和设备 API。注意: `LD_LIBRARY_PATH` 应正确设置以包含 CUDA 库。对于使用 `nvmath.device` API，应将 `CUDA_HOME`（或 `CUDA_PATH`）设置为指向系统 CTK。

命令

描述

pip install nvmath-python[sysctk11]

安装 nvmath-python 以及 CUDA 11 的 CuPy 以支持 nvmath 主机 API。

注意： LD_LIBRARY_PATH 应正确设置以包含 CUDA 库。

pip install nvmath-python[sysctk12]

安装 nvmath-python 以及 CUDA 12 的 CuPy 以支持 nvmath 主机 API。

注意： LD_LIBRARY_PATH 应正确设置以包含 CUDA 库。

pip install nvmath-python[sysctk12-dx]

安装 nvmath-python 以及 CUDA 12 的 CuPy 以支持 nvmath 主机和设备 API。

注意:

LD_LIBRARY_PATH 应正确设置以包含 CUDA 库。
对于使用 nvmath.device API，应将 CUDA_HOME（或 CUDA_PATH）设置为指向系统 CTK。

对于系统管理员或专家用户，pip install nvmath-python 将是一个最 минимальный 安装（非常轻量级）。这允许完全显式地控制所有依赖项。

从 conda 安装#

Conda 包可以从 conda-forge 频道安装。

命令	描述
`conda install -c conda-forge nvmath-python cuda-version=11`	安装 nvmath-python 以及所有 CUDA 11 可选依赖项（cuBLAS/cuFFT/… 和 CuPy 的 wheels）以支持 nvmath 主机 API。
`conda install -c conda-forge nvmath-python cuda-version=12`	安装 nvmath-python 以及所有 CUDA 12 可选依赖项（cuBLAS/cuFFT/… 和 CuPy 的 wheels）以支持 nvmath 主机 API。
`conda install -c conda-forge -c rapidsai nvmath-python-dx "pynvjitlink>=0.2" cuda-version=12`	安装 nvmath-python 以及所有 CUDA 12 可选依赖项（用于 cuBLAS/cuFFT/… 的 wheels、CuPy、Numba、pynvjitlink、…），以支持 nvmath 主机和设备 API（仅支持 CUDA 12）。注意: `nvmath-python-dx` 是一个元包，方便安装 `nvmath-python` 和其他依赖项。 `pynvjitlink` 目前仅存在于 rapidsai 频道，而不是 conda-forge 频道。
`conda install -c conda-forge nvmath-python-cpu`	安装 nvmath-python 以及所有 CPU 可选依赖项（NVPL 或其他），以支持优化的 CPU FFT API。[1] 注意: `nvmath-python-cpu` 是一个元包，方便安装 `nvmath-python` 和其他依赖项。 NVPL 仅适用于 ARM 架构。MKL 或另一个 FFTW3 [9] 兼容库可以替代 x86 架构。环境变量 `NVMATH_FFT_CPU_LIBRARY` 可用于提供实现了 FFTW3（非 guru）API 的备用共享对象的路径。`LD_LIBRARY_PATH` 应正确设置以包含此库（如果它尚未在 PATH 中）。

注意:

对于专家用户，conda install -c conda-forge nvmath-python=*=core* 将是一个最简安装（非常轻量级）。这允许完全显式地控制所有依赖项。
如果您从 miniforge 安装了 conda，则很可能 conda-forge 频道已设置为默认频道，那么可以省略上述指令中的 -c conda-forge 部分。

从源代码构建#

克隆存储库并进入根目录后，您可以从源代码构建项目。由于我们在构建时需要一些 CUDA 头文件，因此有几种构建方法。

命令	描述
`pip install -v .`	设置构建隔离（按照 PEP 517），将 CUDA wheels 和其他构建时依赖项安装到构建环境，构建项目，并将其与运行时依赖项一起安装到当前用户环境。注意：在这种情况下，我们通过将 pip wheels 安装到隔离的构建环境来获取 CUDA 头文件。
`CUDA_PATH=/path/to/your/cuda/installation pip install --no-build-isolation -v .`	跳过创建构建隔离（它将使用来自 `$CUDA_PATH/include` 的 CUDA 头文件），构建项目，并将其与运行时依赖项一起安装到当前用户环境。可以使用 conda：安装 CUDA 12 conda 包后，设置环境变量 `CUDA_PATH` linux-64：`CUDA_PATH=$CONDA_PREFIX/targets/x86_64-linux/` linux-aarch64：`CUDA_PATH=$CONDA_PREFIX/targets/sbsa-linux/` win-64：`CUDA_PATH=$CONDA_PREFIX\Library` 系统 CTK：只需将 `CUDA_PATH` 设置为系统 CTK 位置。

命令

描述

pip install -v .

设置构建隔离（按照 PEP 517），将 CUDA wheels 和其他构建时依赖项安装到构建环境，构建项目，并将其与运行时依赖项一起安装到当前用户环境。

注意：在这种情况下，我们通过将 pip wheels 安装到隔离的构建环境来获取 CUDA 头文件。

CUDA_PATH=/path/to/your/cuda/installation pip install --no-build-isolation -v .

跳过创建构建隔离（它将使用来自 $CUDA_PATH/include 的 CUDA 头文件），构建项目，并将其与运行时依赖项一起安装到当前用户环境。可以使用

conda：安装 CUDA 12 conda 包后，设置环境变量 CUDA_PATH
- linux-64：CUDA_PATH=$CONDA_PREFIX/targets/x86_64-linux/
- linux-aarch64：CUDA_PATH=$CONDA_PREFIX/targets/sbsa-linux/
- win-64：CUDA_PATH=$CONDA_PREFIX\Library
系统 CTK：只需将 CUDA_PATH 设置为系统 CTK 位置。

注意:

如果在点 . 之后添加“extras”符号（例如 .[cu11]、.[cu12,dx]、…），则其含义与上一节中解释的相同。
如果您不希望自动处理运行时依赖项，请在上面的 pip install 命令后添加 --no-deps；但是，在这种情况下，您有责任确保满足所有运行时要求。
通过将 install 替换为 wheel，可以构建针对当前 OS 和 CPython 版本的 wheel。
如果您想要就地/可编辑安装，请将 -e 标志添加到上述命令（在点 . 之前）。这适用于使用系统安装的 CTK 进行本地开发。但是，我们的 wheels 依赖于不可编辑的构建，以便 RPATH hack 可以生效。构建 wheels 时，请勿传递 -e 标志！
下面列出的所有可选运行时依赖项都需要手动安装。

速查表#

下面我们提供了支持所有 nvmath-python 功能的要求摘要。除非另有说明，否则依赖项为必需。

	构建时	运行时 - 主机 API	运行时 - 设备 API	运行时 - 主机 API 回调
CPU 架构和操作系统	linux-64、linux-aarch64、win-64	linux-64、linux-aarch64、win-64	linux-64、linux-aarch64 [1]	linux-64、linux-aarch64
GPU 硬件		底层 CUDA 工具包支持的所有硬件 [5] 可选：如果执行空间为 GPU，则需要。	计算能力 7.0+（Volta 及以上）	计算能力 7.0+（Volta 及以上）
CUDA 驱动程序 [2]		450.80.02+ (Linux) / 450.39+ (Windows)，适用于 CUDA >=11.2 525.60.13+ (Linux) / 527.41+ (Windows)，适用于 CUDA >=12.0 可选：如果执行空间为 GPU 或用于加载任何 CUDA 库，则需要。	525.60.13+ (Linux)，适用于 CUDA 12.x	525.60.13+ (Linux)，适用于 CUDA 12.x
Python	3.10-3.12	3.10-3.12	3.10-3.12	3.10-3.12
pip	22.3.1+
setuptools	>=61.0.0
wheel	>=0.34.0
Cython	>=0.29.22,<3
CUDA	CUDA >=11.2 （仅需要来自 NVCC 和 CUDART 的头文件 [6]）	CUDA >=11.2 可选：取决于使用的数学运算	CUDA >=12.0,!=12.4.*,!=12.5.0 [7] （NVRTC、NVVM、CCCL [8]、CUDART）	CUDA 12.x
NumPy		>=1.24	>=1.24	>=1.24
CuPy （请参阅 CuPy 安装指南）		>=10.0.0 [4]		>=10.0.0 [4]
PyTorch （请参阅 PyTorch 安装指南）		>=1.10 (可选)		>=1.10 (可选)
MathDx (cuBLASDx、cuFFTDx、…)			24.04
Numba			0.60	0.60
pynvjitlink			>=0.2
Math Kernel Library (MKL)		2024.4 (可选)
NVIDIA Performance Libraries (NVPL)		24.7 (可选)

测试配置#

nvmath-python 在以下环境中进行测试

CUDA	11.x（最新版）、12.x（最新版）
驱动程序	R450、R520、R525、R560
GPU 型号	A100、H100、RTX 4090、CG1 (Grace-Hopper)
Python	3.10, 3.11, 3.12
CPU 架构	x86_64、aarch64
操作系统	Ubuntu 22.04、Ubuntu 20.04、RHEL 9、Windows 11

运行 nvmath-python#

如前所述，nvmath-python 可以通过所有 CUDA 安装方法运行，包括 wheels、conda 包和系统 CTK。因此，有检测逻辑来发现共享库（对于主机 API）和头文件（对于设备 API 以进行 JIT 编译）。

共享库#

pip wheels：如果已安装，将自动发现
conda 包：如果已安装，将在 wheel 之后自动发现
系统 CTK：在 Linux 上，用户需要确保动态链接器可以发现共享库，例如通过设置 LD_LIBRARY_PATH 或更新系统搜索路径以包含 DSO 位置。

头文件#

这包括诸如 CCCL 和 MathDx 之类的库。

pip wheels：如果已安装，将自动发现
conda 包：如果已安装，将在 wheel 之后自动发现
系统 CTK：需要设置 CUDA_HOME （或 CUDA_PATH）和 MATHDX_HOME （对于 MathDx 头文件）

主机 API#

此术语在主机 API 中进行了解释。

示例#

请参阅 repo 中的 examples 目录。目前我们有

examples/fft
examples/linalg

测试#

requirements/pip/tests.txt 文件列出了 pip 控制的环境运行测试所需的依赖项。这些要求通过主要的 requirements/pip-dev-<name>.txt 文件安装。

运行功能测试#

pytest tests/example_tests tests/nvmath_tests/fft tests/nvmath_tests/linalg

运行性能测试#

这将目前运行两个 fft 测试和一个 linalg 测试

pytest -v -s -k 'perf' tests/nvmath_tests/fft/
pytest -v -s -k 'perf' tests/nvmath_tests/linalg/

设备 API#

此术语在设备 API 中进行了解释。

示例#

请参阅 repo 中的 examples/device 目录。

测试#

运行功能测试#

pytest tests/nvmath_tests/device examples/device

运行性能测试#

pytest -v -s -k 'perf' tests/nvmath_tests/device/

故障排除#

对于 pip 用户，存在已知限制（其中许多限制在 pypackaging 社区项目中得到了很好的体现），在 Python 打包工具中。对于像 nvmath-python 这样与许多本地库交互的复杂库，存在用户可见的注意事项。

请确保您的 Python 环境中没有同时存在带有 -cu11 （用于 CUDA 11）和 -cu12 （用于 CUDA 12）后缀的软件包。例如，这是一个损坏的环境
```
$ pip list
Package            Version
------------------ ---------
nvidia-cublas-cu11 11.11.3.6
nvidia-cublas-cu12 12.5.2.13
pip                24.0
setuptools         70.0.0
wheel              0.43.0
```
有时，此类冲突可能来自您使用的库的依赖项，因此请格外注意已安装的内容。
pip 不会尝试检查已安装的软件包是否真的可以针对已安装的 GPU 驱动程序运行（CUDA GPU 驱动程序无法通过 pip 安装），因此请确保您的 GPU 驱动程序足够新，可以支持已安装的 -cuXX 软件包 [2]。驱动程序版本可以通过执行 nvidia-smi 并检查输出表上的 Driver Version 字段来检查。
从 pip 安装的 CuPy 当前（截至 v13.3.0）仅支持 conda 和系统 CTK，而不支持 pip 安装的 CUDA wheels。如果导入 nvmath，nvmath-python 可以帮助 CuPy 使用安装到 site-packages （wheels 安装到的位置）的 CUDA 库。从 beta 2 (v0.2.0) 开始，库在 import nvmath 发生时被“软加载”（如果未安装库，则不会引发错误）。此行为可能会在未来的版本中更改。
从 pip 安装的 Numba 当前（截至 v0.60.0）仅支持 conda 和系统 CTK，而不支持 pip 安装的 CUDA wheels。如果导入 nvmath，nvmath-python 还可以帮助 Numba 使用安装到 site-packages 的 CUDA 编译器。与上面相同，此行为可能会在未来的版本中更改。

一般来说，混合搭配来自 pip、conda 和系统的 CTK 包是可能的，但可能非常脆弱，因此了解您在做什么非常重要。nvmath-python 内部结构旨在与通过 pip、conda 或本地系统（系统 CTK，包括 tarball 提取，是检测逻辑中的后备解决方案）安装的所有内容一起工作，但混合搭配使检测逻辑无法正确实现。

为了帮助您执行完整性检查，经验法则是每个软件包都应该仅来自一个位置（pip、conda 或本地系统）。例如，如果 conda list 的输出中同时出现 nvidia-cufft-cu11 （来自 pip）和 libcufft （来自 conda），则几乎肯定存在问题。以下是 pip 和 conda 之间的软件包名称映射，其中 XX={11,12} 表示 CUDA 的主要版本

pip	conda (`cuda-version>=12`)	conda (`cuda-version<12`)
`nvidia-cuda-nvcc-cuXX`	`cuda-nvcc`	n/a
`nvidia-cuda-nvrtc-cuXX`	`cuda-nvrtc`	`cudatoolkit`
`nvidia-cuda-runtime-cuXX`	`cuda-cudart-dev`	`cudatoolkit`
`nvidia-cuda-cccl-cuXX`	`cuda-cccl`	n/a
`pynvjitlink-cuXX`	`pynvjitlink`	n/a
`nvidia-cublas-cuXX`	`libcublas`	`cudatoolkit`
`nvidia-cusolver-cuXX`	`libcusolver`	`cudatoolkit`
`nvidia-cusparse-cuXX`	`libcusparse`	`cudatoolkit`
`nvidia-cufft-cuXX`	`libcufft`	`cudatoolkit`
`nvidia-curand-cuXX`	`libcurand`	`cudatoolkit`

请注意，系统软件包（按设计）不会显示在 conda list 或 pip list 的输出中。Linux 用户应检查您的发行版软件包管理器（apt、yum、dnf、…）的安装列表。另请参阅 Linux 软件包管理器安装指南以获取更多信息。

有关 conda-forge 上新的 CUDA 12+ 软件包布局的更多信息，请参阅 CUDA recipe README。

脚注