WarpX 26.03 编译安装（CUDA + Python）指南

本文介绍在 CentOS Stream 9 + CUDA 12.8 + OpenMPI 环境下，编译 WarpX 26.03 release / debug 两种构建到共享目录或用户目录的完整流程。

一、目标与版本

项	值
WarpX	26.03
GPU 加速	CUDA 12.8（compute capability 由 GPU 决定）
MPI	OpenMPI（x86_64）
Python 支持	ON
维度	1D / 2D / 3D / RZ
安装位置（共享）	/shared/apps/warpx/26.03/release、/shared/apps/warpx/26.03/debug
安装位置（用户）	$HOME/.local/warpx

源码位置：<your-workspace>/WarpX

二、前提条件

1. 模块环境（已配好 modulecmd）

module purge
module load cuda/12.8
module load miniconda3/3.13 mpi/openmpi-x86_64

2. Conda 环境

按用途分别建环境：

• warpx_release：release 版
• warpx_cuda：共享版（也可复用 release）
• warpx_debug：debug 版

三、共享目录版（多用户使用，需要 sudo）

适合多用户共享同一份 WarpX 安装，目录对所有用户可读：

#!/bin/bash

module purge
module load cuda/12.8
module load miniconda3/3.13 mpi/openmpi-x86_64
source activate warpx_cuda

cd /home/caijie/local/WarpX

INSTALL_DIR="/shared/apps/warpx/26.03/release"

cmake -S . -B build \
  -DWarpX_DIMS="1;2;3;RZ" \
  -DWarpX_COMPUTE=CUDA \
  -DWarpX_PYTHON=ON \
  -DCMAKE_INSTALL_PREFIX="$INSTALL_DIR"

# Build the project
cmake --build build -j 16

# Install the project (requires sudo)
sudo cmake --build build --target install -j 16

# Build and install the Python package system-wide
sudo cmake --build build --target pip_install -j 16

要点：

• cmake -B build：在源码同目录新建 build/，避免污染源码
• -DWarpX_COMPUTE=CUDA：启用 GPU 加速
• -DWarpX_PYTHON=ON：同时构建 Python 绑定（pywarpx）
• cmake --build -j 16：用 16 核并行编译；改成你机器核心数

四、Debug 版（带 FPE/Assertion）

适合开发与 bug 排查，启用 AMReX 的浮点异常检查与断言：

#!/bin/bash

module purge
module load cuda/12.8
module load miniconda3/3.13 mpi/openmpi-x86_64
source activate warpx_debug

cd /home/caijie/local/WarpX

INSTALL_DIR="/shared/apps/warpx/26.03/debug"

cmake -S . -B build_debug \
  -DAMReX_FPE=ON \
  -DAMReX_ASSERTIONS=ON \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DWarpX_DIMS="1;2;3;RZ" \
  -DWarpX_PYTHON=ON \
  -DCMAKE_INSTALL_PREFIX="$INSTALL_DIR"

# Build the project
cmake --build build_debug -j 16

# Install the project (requires sudo)
sudo cmake --build build_debug --target install -j 16

# Build and install the Python package system-wide
sudo cmake --build build_debug --target pip_install -j 16

选项	作用
-DAMReX_FPE=ON	启用浮点异常（除零、NaN/Inf 即 abort）
-DAMReX_ASSERTIONS=ON	启用 AMReX 内部断言
-DCMAKE_BUILD_TYPE=RelWithDebInfo	带调试符号的优化构建（既能跑又能 gdb）

注意：AMReX_FPE=ON 在 GPU 上会让 CUDA 浮点异常触发 abort，但不会捕获数值 NaN/Inf（CUDA 内核默认屏蔽这些）。若需要完整数值检查，配合 compute-sanitizer 使用。

五、用户目录版（免 sudo）

适合单机开发或不想污染系统目录：

#!/bin/bash

module purge
module load cuda/12.8
module load miniconda3/3.13 mpi/openmpi-x86_64
source activate warpx_release

cd /home/caijie/local/WarpX

# 安装到用户目录
INSTALL_DIR="$HOME/.local/warpx"
cmake -S . -B build \
  -DWarpX_DIMS="1;2;3;RZ" \
  -DWarpX_COMPUTE=CUDA \
  -DWarpX_PYTHON=ON \
  -DCMAKE_INSTALL_PREFIX="$INSTALL_DIR"

# Build the project
cmake --build build -j 16

# Install the project (no sudo needed)
cmake --build build --target install -j 16

# Build and install the Python package to user directory
PIP_INSTALL_USER=yes cmake --build build --target pip_install -j 16

PIP_INSTALL_USER=yes：Python 包安装到 ~/.local/，免 sudo。

六、配套使用：与 Slurm 集成

装好 WarpX 后，配合 Slurm 提交作业的写法：

#!/bin/bash

module load warpx/latest
source activate warpx

# 假设 WarpX 已经安装好了，并且 input.py 在当前目录
srun --mpi=pmix --gres=gpu:V100:1 -c 1 --mem=1G python input.py

• module load warpx/latest：把 WarpX 安装目录加到环境
• --mpi=pmix：与 slurm.conf 中 MpiDefault=pmix 一致
• --gres=gpu:V100:1 -c 1 --mem=1G：每节点 1 卡 / 1 核 / 1GB

七、常见问题

❌ Could NOT find MPI_CXX / MPI not found

OpenMPI 模块没加载。检查：

module list | grep mpi
# 应该有 mpi/openmpi-x86_64

❌ nvcc: command not found

CUDA 模块没加载：

module load cuda/12.8
which nvcc
# /path/to/cuda/12.8/bin/nvcc

❌ Python 包装不上 / pywarpx 找不到

• 检查环境是否激活：which python 应当指向 conda 环境内的 python
• 用户版检查 PIP_INSTALL_USER=yes 是否设置
• 共享版需要 sudo 写入系统 site-packages

❌ 编译卡死 / 内存爆

减少并行度：

cmake --build build -j 8  # 不要超过物理核数

❌ 链接时报 libcudart.so not found

安装目标机器上 CUDA 库版本不一致。把 LD_LIBRARY_PATH 指到编译期使用的 CUDA：

export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

八、清理与重建

# 清理 build 目录
rm -rf build build_debug

# 清理已安装文件
rm -rf /shared/apps/warpx/26.03/release/*
rm -rf $HOME/.local/warpx

总结

WarpX 26.03 的安装核心是：

1. 模块环境一致：cuda/12.8 + mpi/openmpi-x86_64 + conda 环境
2. 构建选项：WarpX_DIMS="1;2;3;RZ" + WarpX_COMPUTE=CUDA + WarpX_PYTHON=ON
3. 目录选择：多用户走 /shared/apps/，单用户走 $HOME/.local/
4. debug 版额外开 AMReX_FPE=ON + AMReX_ASSERTIONS=ON + RelWithDebInfo

配合 Slurm 单节点部署指南 即可投入生产使用。