从源码安装

在大多数情况下，你不需要从源码构建 CUDA-Q。为了获得最佳体验，我们建议使用容器运行时，以避免与系统上安装的其他软件工具发生冲突。请注意，Singularity 或 Docker 无根模式解决了常见的问题，这些问题通常是避免使用容器的动机。例如，Singularity 可以安装在用户文件夹中，其安装不需要管理员权限；有关如何操作的详细说明，请参见本节。我们的安装指南还包含了如何将 IDE 连接到运行中容器的说明。

如果你不想使用容器运行时，我们也提供了预构建的二进制文件（用于将 CUDA-Q 与 C++ 一起使用）和 Python wheel 包（用于将 CUDA-Q 与 Python 一起使用）。这些二进制文件和 wheel 包是按照本指南中的说明构建的，只要你的系统满足"前置要求"部分列出的兼容性要求，它们就应该能正常工作。要安装预构建的二进制文件，请遵循此处的说明。要安装 Python wheel 包，请遵循此处的说明。

如果你的系统不在我们官方包支持列表中（例如，因为你希望在使用旧版 C 标准库的操作系统上使用 CUDA-Q），请仔细遵循本指南，不要跳过任何步骤，从源码构建并安装 CUDA-Q。本指南的其余部分详细说明了构建期间和安装后的系统要求，并逐步介绍了安装步骤。

注意

CUDA-Q 包含一些仅以预构建二进制形式提供的组件，这些组件不在我们的开源仓库中。我们正在努力开源这些组件，或将其作为独立下载在未来提供。即使没有这些组件，在源码构建中，CUDA-Q 的几乎所有功能都将被启用，尽管某些部分可能性能较低。目前，如果你从源码构建 CUDA-Q，多 GPU 状态向量模拟器后端将不会被包含在内。

前置要求

以下前置要求需要同时在构建系统和主机系统上满足，主机系统是指将安装和使用构建好的 CUDA-Q 二进制文件的系统。

• Linux 操作系统。本指南中的说明已在作为 manylinux_2_28 镜像基础镜像的 AlmaLinux 8 镜像上验证通过，并且应该适用于以下操作系统：CentOS 8、Debian 11 和 12、Fedora 41、OpenSUSE/SLED/SLES 15.5 和 15.6、RHEL 8 和 9、Rocky 8 和 9、Ubuntu 24.04 和 22.04。其他操作系统可能也能工作，但尚未经过测试。

• Bash shell。CUDA-Q 的构建、安装和运行脚本期望使用 /bin/bash。

• GNU C 库。确保主机系统上的版本与构建系统上的版本相同或更新。我们自己的构建使用的是版本 2.28。

• CPU，架构为 x86-64（x86-64-v3 架构及更新）或 ARM64（ARM v8-A 架构及更新）。其他架构可能也能工作，但尚未经过测试，并且可能需要调整构建说明。

• 仅在主机系统上需要：具有 Volta、Turing、Ampere、Ada 或 Hopper 架构且计算能力 7+ 的 NVIDIA GPU。请确保为你的 GPU 安装了最新的驱动程序，并仔细检查 nvidia-smi 命令列出的驱动程序版本是否为 470.57.02 或更新。你不需要在构建系统上拥有 GPU；构建所需的 CUDA 编译器可以在没有 GPU 的情况下安装和使用。

我们强烈建议为构建使用一个虚拟环境，该环境仅包含本指南中列出的工具和依赖项。如果你安装了其他软件，你需要确保构建链接到正确的库和版本。

构建依赖项

除了上面列出的前置要求之外，你还需要在构建环境中安装以下前置要求，然后再按照后续章节所述进行构建：

• Python 版本 3.11 或更新：如果你打算构建支持 Python 的 CUDA-Q，请确保构建系统上的 Python 版本与主机系统上的版本匹配。如果你只打算构建 CUDA-Q 的 C++ 支持，则 Python 解释器仅在某些 LLVM 构建脚本中需要，并且构建所使用的 Python 版本不必与主机系统上的版本匹配。

• 常用工具：wget、git、unzip。本指南其余部分的命令假设这些工具存在于构建系统上，但它们可以被其他替代工具替换（例如，手动访问网页并下载文件/文件夹）。

一旦 CUDA-Q 构建完成，上述前置要求就不再需要，也不需要在主机系统上存在。

注意

CUDA-Q 构建脚本和本文档其余部分列出的命令假设你使用 bash 作为构建的 shell。

除了安装上述所需的构建依赖项之外，请确保在继续之前设置以下环境变量：

export CUDAQ_INSTALL_PREFIX=/usr/local/cudaq
export CUQUANTUM_INSTALL_PREFIX=/usr/local/cuquantum
export CUTENSOR_INSTALL_PREFIX=/usr/local/cutensor
export LLVM_INSTALL_PREFIX=/usr/local/llvm
export BLAS_INSTALL_PREFIX=/usr/local/blas
export ZLIB_INSTALL_PREFIX=/usr/local/zlib
export OPENSSL_INSTALL_PREFIX=/usr/local/openssl
export CURL_INSTALL_PREFIX=/usr/local/curl
export AWS_INSTALL_PREFIX=/usr/local/aws

这些环境变量必须在构建期间设置。我们强烈建议将它们的值设置为尚不存在的路径；这将确保在构建 CUDA-Q 时根据需要构建/安装这些组件。配置的路径可以自由选择，但在构建期间指定的路径也是相应库将安装到主机系统上的位置。我们正在努力使这在未来更加灵活。

注意

请不要将 LLVM_INSTALL_PREFIX 设置为已存在的目录；为了避免兼容性问题，重要的是使用相同的编译器从源码构建 LLVM/MLIR 依赖项，稍后将使用该编译器来构建 CUDA-Q 本身。

注意

如果你将 CURL_INSTALL_PREFIX 变量设置为现有的 CURL 安装（不推荐），请确保命令 curl --version 列出 HTTP 和 HTTPS 作为支持的协议。如果没有列出这些协议，请将 CURL_INSTALL_PREFIX 变量设置为一个不存在的路径。在这种情况下，将作为构建 CUDA-Q 的一部分自动从源码构建合适的库。

如果你偏离以下安装某个依赖项的说明，而是通过包管理器等方式安装它，你需要确保安装路径与你为相应环境变量设置的路径匹配。

CUDA

构建 CUDA-Q 需要完整安装 CUDA 工具包。你可以在没有 GPU 的情况下安装 CUDA 工具包并使用 CUDA 编译器。这些说明已使用版本 12.6 和 13.0 进行了测试，但其他 CUDA 12 或 13 版本应该也能工作，只要主机系统上的 CUDA 运行时版本与构建使用的 CUDA 版本匹配，并且主机系统上安装的驱动程序支持该 CUDA 版本。我们建议使用主机系统驱动程序支持的最新 CUDA 版本。

按照该页面在线文档中针对你平台的安装指南，下载合适的 CUDA 版本。

例如，在测试过的 AlmaLinux 8 环境中，以下命令安装 CUDA 12.6：

CUDA_VERSION=${CUDA_VERSION:-12.6}
CUDA_DOWNLOAD_URL=https://developer.download.nvidia.com/compute/cuda/repos
# 访问上面的 URL，为你的平台设置以下变量为合适的分发版和子文件夹，并取消注释下面一行。
# DISTRIBUTION=rhel8 CUDA_ARCH_FOLDER=x86_64

dnf config-manager --add-repo "${CUDA_DOWNLOAD_URL}/${DISTRIBUTION}/${CUDA_ARCH_FOLDER}/cuda-${DISTRIBUTION}.repo"
dnf install -y --nobest --setopt=install_weak_deps=False \
    cuda-toolkit-$(echo ${CUDA_VERSION} | tr . -)
# custatevec 现在链接到 `libnvidia-ml.so.1`，它由 NVIDIA 驱动程序提供。
# 为了在无 GPU 的系统上构建，我们还需要安装驱动程序。
dnf install -y --nobest --setopt=install_weak_deps=False nvidia-driver-libs    

工具链

用于构建的编译器工具链必须是已安装 CUDA 版本所支持的 CUDA 主机编译器。以下说明已使用 GCC-11 进行了测试。其他工具链可能受支持但尚未经过测试。

例如，在测试过的 AlmaLinux 8 环境中，以下命令安装 GCC 11：

GCC_VERSION=${GCC_VERSION:-11}
dnf install -y --nobest --setopt=install_weak_deps=False \
    gcc-toolset-${GCC_VERSION}
# 全局启用工具链仅在调试构建时需要，
# 以确保选择正确的汇编器来处理调试符号。
enable_script=`find / -path '*gcc*' -path '*'$GCC_VERSIONS'*' -name enable`
if [ -n "$enable_script" ]; then
    . "$enable_script"
fi

无论你安装的是哪个编译器工具链，请设置以下环境变量以指向你构建系统上的相应编译器：

export GCC_TOOLCHAIN=/opt/rh/gcc-toolset-11/root/usr/
export CXX="${GCC_TOOLCHAIN}/bin/g++"
export CC="${GCC_TOOLCHAIN}/bin/gcc"
export CUDACXX=/usr/local/cuda/bin/nvcc
export CUDAHOSTCXX="${GCC_TOOLCHAIN}/bin/g++"

• 变量 CC 和 CXX 必须为 CUDA-Q 构建设置。
• 要在 CUDA-Q 中使用 GPU 加速，请确保将 CUDACXX 设置为你的 CUDA 编译器，并将 CUDAHOSTCXX 设置为你正在使用的 CUDA 兼容主机编译器。如果在构建 CUDA-Q 时未找到 CUDA 编译器，某些组件和后端将在构建过程中自动省略。

构建 CUDA-Q

本安装指南是为 CUDA-Q 的特定版本/提交编写的。请确保获取该版本的源代码。克隆 CUDA-Q GitHub 仓库并 checkout 适当的分支、标签或提交。请注意，构建脚本假设它们是从 git 仓库中运行的，因此仅仅将源代码下载为 ZIP 压缩包是行不通的。

请按照相应子章节中的说明，构建使用 CUDA-Q 的 C++ 和/或 Python 所需的组件。构建完成后，通过确认 $CUDAQ_INSTALL_PREFIX/targets 文件夹中存在 nvidia.config 文件，检查 GPU 加速组件是否已构建。我们还建议检查打印到控制台的构建日志，以确认所有期望的组件都已构建。

注意

CUDA-Q 构建将根据是否在构建环境中找到必要的前置要求，自动编译或省略可选组件。如果你看到某个组件被跳过的消息，和/或 CUDA 编译器未被正确检测到，请确保你遵循了安装必要前置要求和构建依赖项的说明，并按照本文档所述设置了必要的环境变量。

Python 支持

在 CUDA-Q 中启用 Python 支持最方便的方法是构建一个 wheel 包，然后可以使用 pip 轻松安装。为了确保 wheel 包可以安装在主机系统上，请确保构建使用的 Python 版本与主机系统上安装的 Python 版本相同。要构建 CUDA-Q Python wheel 包，你需要安装以下额外的 Python 特定工具：

• Python 开发头文件：你的 Python 版本的开发头文件会按照你安装 Python 本身的方式安装。如果你通过系统的包管理器安装了 Python，你可能需要安装一个额外的包来获取开发头文件。包名称通常是你的 Python 版本，后跟 -dev 或 -devel 后缀。如果你使用的是 Conda 环境，必要的头文件应该已经安装。

• Pip 包管理器：确保为你所用的 Python 版本启用了 pip 模块，并且你的 pip 版本是 24 或更新。关于安装/启用 pip 的更多信息，请参阅 Python 文档。

• Python 模块：为你所用的 Python 版本安装额外的模块 numpy、build、auditwheel 和 patchelf，例如 python3 -m pip install numpy build auditwheel patchelf。

注意

默认情况下构建的 wheel 包配置为依赖 CUDA 13。要为 CUDA 12 构建 wheel 包，你需要将 pyproject.toml.cu12 文件复制为 pyproject.toml。

在你克隆 CUDA-Q 仓库的文件夹中，运行以下命令来构建 CUDA-Q Python wheel 包：

LLVM_PROJECTS='clang;flang;lld;mlir;python-bindings;openmp;runtimes' \
bash scripts/install_prerequisites.sh -t llvm -e qrmi && \
CC="$LLVM_INSTALL_PREFIX/bin/clang" \
CXX="$LLVM_INSTALL_PREFIX/bin/clang++" \
FC="$LLVM_INSTALL_PREFIX/bin/flang-new" \
python3 -m build --wheel && \
echo "=== ccache stats (python_build) ===" && (ccache -s 2>/dev/null || true)

注意

版本标识符将根据提交历史自动分配给 wheel 包。你可以通过设置环境变量 SETUPTOOLS_SCM_PRETEND_VERSION 为你想要的值来手动覆盖此检测，以提供更具描述性的标识符。

初始构建之后，如果需要，使用 auditwheel 将依赖项包含在 wheel 包中，并正确标记 wheel 包。我们建议不要包含 CUDA 运行时库，而是按照下一节的说明将它们单独安装在主机系统上。以下命令构建最终的 wheel 包，不包含 CUDA 依赖项：

CUDAQ_WHEEL="$(find . -name 'cuda_quantum*.whl')" && \
MANYLINUX_PLATFORM="$(echo ${CUDAQ_WHEEL} | grep -o '[a-z]*linux_[^\.]*' | sed -re 's/^linux_/manylinux_2_28_/')" && \
LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:$(pwd)/cuda-quantum/_skbuild/lib" \
python3 -m auditwheel -v repair ${CUDAQ_WHEEL} \
    --plat ${MANYLINUX_PLATFORM} \
    --exclude libcublas.so.11 \
    --exclude libcublasLt.so.11 \
    --exclude libcurand.so.10 \
    --exclude libcusolver.so.11 \
    --exclude libcusparse.so.11 \
    --exclude libcutensor.so.2 \
    --exclude libcutensornet.so.2 \
    --exclude libcustatevec.so.1 \
    --exclude libcudensitymat.so.0 \
    --exclude libcudart.so.11.0 \
    --exclude libnvToolsExt.so.1 \
    --exclude libnvidia-ml.so.1 \
    --exclude libcuda.so.1

上述命令将在 wheelhouse 文件夹中创建一个新的 wheel 包。这个 wheel 包可以安装在任何兼容的平台上。

注意

你可以通过检查 wheel 包标签（即 .whl 文件的文件名结尾）是否列在主机上运行 python3 -m pip debug --verbose 命令时的"Compatible Tags"下，来确认 wheel 包确实与你的主机平台兼容。

C++ 支持

在你克隆 CUDA-Q 仓库的文件夹中，运行以下命令来构建 CUDA-Q：

CUDAQ_ENABLE_STATIC_LINKING=TRUE \
CUDAQ_REQUIRE_OPENMP=TRUE \
CUDAQ_WERROR=TRUE \
CUDAQ_PYTHON_SUPPORT=OFF \
LLVM_PROJECTS='clang;flang;lld;mlir;openmp;runtimes' \
bash scripts/build_cudaq.sh -t llvm -v -- -DCUDAQ_ENABLE_PASQAL_QRMI_CONNECTOR=OFF && \
echo "=== ccache stats (cpp_build) ===" && (ccache -s 2>/dev/null || true) && \
(ccache --print-stats 2>/dev/null || ccache -s 2>/dev/null) > /root/.ccache/_build_stats.txt

请注意，lld 主要在构建或主机系统的路径上还没有现成的默认链接器时需要；CUDA-Q 支持与 clang 相同的链接器。

为了轻松地将构建好的二进制文件迁移到主机系统，我们建议创建一个自解压归档文件。为此，下载 makeself 脚本并将需要安装的文件移动到一个单独的文件夹中，使用以下命令：

# 将所有资源暂存到一个合并的前缀目录中。
# 所有依赖项都合并到 CUDAQ 安装目录中，以便
# 现有的相对 RPATH（$ORIGIN/../lib, @loader_path/../lib）覆盖
# 所有内容，并且不需要硬编码的绝对路径。
mkdir -p cuda_quantum_assets
cp -a "${CUDAQ_INSTALL_PREFIX}" cuda_quantum_assets/cudaq

# 从 C++ 安装程序中移除依赖于 Python 的插件。pyscf 插件
# 需要 Python 运行时，并且不用于 C++ 工作流。
rm -f cuda_quantum_assets/cudaq/lib/plugins/libcudaq-pyscf*

# 将完整的 LLVM 安装捆绑在其自己的子目录中，以便 clang 的
# 内部路径解析（资源目录、C++ 头文件、运行时库）能够工作
# 而无需自定义回退。保留完整的安装也可以使 LLVM 工具
# 不在用户的 PATH 上（只有 cudaq/bin/ 由 set_env.sh 添加）。
llvm_dest=cuda_quantum_assets/cudaq/lib/llvm
cp -a "${LLVM_INSTALL_PREFIX}" "${llvm_dest}"

# 同时将运行时库复制到 cudaq/lib/ 以实现 RPATH 兼容性——CUDAQ
# bin/ 中的二进制文件具有 RPATH $ORIGIN/../lib，需要 libc++ 等在那里。
for lib in libc++ libunwind libomp; do
  cp -a "${llvm_dest}/lib/${lib}"*.dylib* cuda_quantum_assets/cudaq/lib/ 2>/dev/null || true
  cp -a "${llvm_dest}/lib/${lib}"*.so* cuda_quantum_assets/cudaq/lib/ 2>/dev/null || true
  for f in "${llvm_dest}/lib/"*/${lib}*; do
    [ -e "$f" ] || continue
    cp -a "$f" cuda_quantum_assets/cudaq/lib/
  done
done

# 合并 cuQuantum/cuTensor 库和头文件。
# 尝试 lib64/ 和 lib/，因为不同的发行版使用不同的约定；
# || true 防止 set -e 在 glob 匹配不到任何内容时中止。
if $include_cuda_deps; then
  cp -a "${CUQUANTUM_INSTALL_PREFIX}/lib64/"* cuda_quantum_assets/cudaq/lib/ 2>/dev/null || true
  cp -a "${CUQUANTUM_INSTALL_PREFIX}/lib/"* cuda_quantum_assets/cudaq/lib/ 2>/dev/null || true
  cp -a "${CUQUANTUM_INSTALL_PREFIX}/include/"* cuda_quantum_assets/cudaq/include/ 2>/dev/null || true
  cp -a "${CUTENSOR_INSTALL_PREFIX}/lib64/"* cuda_quantum_assets/cudaq/lib/ 2>/dev/null || true
  cp -a "${CUTENSOR_INSTALL_PREFIX}/lib/"* cuda_quantum_assets/cudaq/lib/ 2>/dev/null || true
  cp -a "${CUTENSOR_INSTALL_PREFIX}/include/"* cuda_quantum_assets/cudaq/include/ 2>/dev/null || true
fi

# 生成一个空的 build_config.xml，因为所有依赖项已经合并到 cudaq/ 中。
cat > cuda_quantum_assets/build_config.xml << 'BCONFIG'
<build_config>
</build_config>
BCONFIG
# 在已安装的 cudaq/ 目录中使用相同的配置。
cp cuda_quantum_assets/build_config.xml cuda_quantum_assets/cudaq/build_config.xml

然后，你可以使用以下命令创建一个自解压归档文件：

./makeself.sh --gzip --sha256 --license cuda_quantum_assets/cudaq/LICENSE \
    cuda_quantum_assets install_cuda_quantum.$(uname -m) \
    "CUDA-Q toolkit for heterogeneous quantum-classical workflows" \
    bash install.sh

在主机上安装

确保你的主机系统满足上述"前置要求"。

• 要将 CUDA-Q 与 Python 一起使用，你应该在主机系统上有一个有效的 Python 安装，包括 pip 包管理器。
• 要将 CUDA-Q 与 C++ 一起使用，你应该确保已安装 C 标准库的必要开发头文件。你可以通过搜索 features.h 来检查，该文件通常位于 /usr/include/。你可以通过包管理器安装必要的头文件（通常包名类似于 glibc-devel 或 libc6-devel）。这些头文件也包含在任何 GCC 安装中。

如果你按照构建 CUDA-Q Python wheel 包的说明进行操作，请将构建好的 .whl 文件复制到主机系统，并使用 pip 安装它；例如：

pip install cuda_quantum*.whl

要安装某些组件所需的 CUDA 和 MPI 依赖项，你可以遵循 PyPI.org 上的说明，将 pip install cudaq 替换为上述命令，或者你可以遵循本文档剩余部分的说明，为主机系统定制并更好地优化它们。

如果你按照构建 CUDA-Q C++ 工具的说明进行操作，请将你创建的 install_cuda_quantum 文件复制到主机系统，并通过运行以下命令来安装它：

sudo bash install_cuda_quantum.$(uname -m) --accept
. /opt/nvidia/cudaq/set_env.sh

这将提取构建好的资源并将它们移动到正确的位置。/opt/nvidia/cudaq/set_env.sh 脚本定义了使用 CUDA-Q 所需的环境变量。为了避免每次打开新 shell 时都手动设置它们，我们强烈建议将以下行添加到 /etc/profile 文件中：

if [ -f /opt/nvidia/cudaq/set_env.sh ]; then
  . /opt/nvidia/cudaq/set_env.sh
fi

注意

按照上述说明构建的 CUDA-Q 包含并使用 LLVM C++ 标准库。这不会与你系统上可能存在的任何其他 C++ 标准库冲突。你可能希望与 CUDA-Q 一起使用的预构建外部库（例如特定的优化器）具有 C API，以确保跨不同版本的 C++ 标准库的兼容性，并且可以与 CUDA-Q 一起正常工作而不出问题。所有分发的 CUDA 库也是如此。要构建可以与 CUDA-Q 一起使用的你自己的 CUDA 库，请查看《在项目中使用 CUDA 和 CUDA-Q》。

本文档的其余部分列出了未包含在迁移资源中的额外运行时依赖项，这些依赖项是使用某些 CUDA-Q 功能和组件所必需的。

CUDA 运行时库

要在 CUDA-Q 中使用 GPU 加速，你需要安装必要的 CUDA 运行时库。它们的版本（至少是主要版本）需要与构建时使用的版本匹配。虽然并非必须，但我们建议像为 CUDA-Q 构建所做的那样安装完整的 CUDA 工具包。如果你只想安装最少的运行时库集，例如，以下命令为 AlmaLinux 8 环境安装必要的包：

CUDA_VERSION=${CUDA_VERSION:-12.6}
CUDA_DOWNLOAD_URL=https://developer.download.nvidia.com/compute/cuda/repos
# 访问上面的 URL，为你的平台设置以下变量为合适的分发版和子文件夹，并取消注释下面一行。
# DISTRIBUTION=rhel8 CUDA_ARCH_FOLDER=x86_64

version_suffix=$(echo ${CUDA_VERSION} | tr . -)
dnf config-manager --add-repo "${CUDA_DOWNLOAD_URL}/${DISTRIBUTION}/${CUDA_ARCH_FOLDER}/cuda-${DISTRIBUTION}.repo"
dnf install -y --nobest --setopt=install_weak_deps=False \
    cuda-cudart-${version_suffix} \
    cuda-nvrtc-${version_suffix} \
    libcusolver-${version_suffix} \
    libcusparse-${version_suffix} \
    libcublas-${version_suffix} \
    libcurand-${version_suffix}
if [ $(echo ${CUDA_VERSION} | cut -d . -f1) -gt 11 ]; then 
    dnf install -y --nobest --setopt=install_weak_deps=False \
        libnvjitlink-${version_suffix}
fi

MPI

为了与所有 CUDA-Q 后端一起工作，需要安装支持 CUDA 的 MPI。如果你没有现成的支持 CUDA 的 MPI 安装，你可以从源码构建一个。为此，除了上面列出的 CUDA 运行时库之外，你还需要安装 CUDA 运行时开发包（cuda-cudart-devel-${version_suffix} 或 cuda-cudart-dev-${version_suffix}，取决于你的发行版）。

以下命令构建一个足够使用的支持 CUDA 的 OpenMPI 安装。为了充分利用 MPI，我们建议进行更全面的安装，包括适合你主机系统的额外配置。以下命令假设你已经在构建系统上安装了 OpenMPI 构建所需的必要前置要求。例如，在测试过的 AlmaLinux 8 环境中，需要安装 autoconf、libtool、flex 和 make 包。

OPENMPI_VERSION=4.1.4
OPENMPI_DOWNLOAD_URL=https://github.com/open-mpi/ompi

wget "${OPENMPI_DOWNLOAD_URL}/archive/v${OPENMPI_VERSION}.tar.gz" -O /tmp/openmpi.tar.gz
mkdir -p ~/.openmpi-src && tar xf /tmp/openmpi.tar.gz --strip-components 1 -C ~/.openmpi-src
rm -rf /tmp/openmpi.tar.gz && cd ~/.openmpi-src
./autogen.pl 
LDFLAGS=-Wl,--as-needed ./configure \
    --prefix=/usr/local/openmpi \
    --disable-getpwuid --disable-static \
    --disable-debug --disable-mem-debug --disable-event-debug \
    --disable-mem-profile --disable-memchecker \
    --without-verbs \
    --with-cuda=/usr/local/cuda
make -j$(nproc) 
make -j$(nproc) install
cd - && rm -rf ~/.openmpi-src

确认你安装了合适的 MPI 实现。例如，对于 OpenMPI 和 MPICH，可以通过编译并运行以下程序来完成：

// 编译并运行：
// ```
// mpic++ mpi_cuda_check.cpp -o check.x && mpiexec -np 1 ./check.x
// ```

#include "mpi.h"
#if __has_include("mpi-ext.h")
#include "mpi-ext.h"
#endif
#include <stdio.h>

int main(int argc, char *argv[]) {
  MPI_Init(&argc, &argv);
  int exit_code;
  if (MPIX_Query_cuda_support()) {
    printf("CUDA-aware MPI installation.\n");
    exit_code = 0;
  } else {
    printf("Missing CUDA support.\n");
    exit_code = 1;
  }
  MPI_Finalize();
  return exit_code;
}

注意

如果你遇到类似于 “The value of the MCA parameter plm_rsh_agent was set to a path that could not be found” 的错误，请确保你安装了 SSH 客户端，或者将 MCA 参数更新为其他合适的代理。除非使用其他资源管理器（如 SLURM），否则 MPI 使用 SSH 或 RSH 与每个节点通信。

CUDA-Q 通过插件架构支持不同的 MPI 实现。一旦你在主机系统上安装了支持 CUDA 的 MPI，你可以通过激活必要的插件来配置 CUDA-Q 使用它。CUDA-Q 中包含了 OpenMPI 和 MPICH 的插件，可以通过设置环境变量 MPI_PATH 为 MPI 安装文件夹，然后运行以下命令来激活：

bash "${CUDA_QUANTUM_PATH}/distributed_interfaces/activate_custom_mpi.sh"

注意

要为 Python 支持激活 MPI 插件，请将 ${CUDA_QUANTUM_PATH} 替换为运行 pip show cuda-quantum 命令时列出的 “Location” 下的路径。

如果你使用的是 OpenMPI 或 MPICH 以外的其他 MPI 实现，你需要自己实现必要的插件接口，然后使用上述命令激活插件。