Menu
询问 SPONGE 构建、编译、环境配置、构建排错时使用。 适用于 pixi 环境选择、CMake 配置、多后端编译、格式化、打包。
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
询问 SPONGE benchmark 新建 或 调整 时 使用 - comparison validation performance 分类 - benchmark 目录 组织 - benchmark 测试 编写 - utils 复用 - pixi task 接入
询问 SPONGE 代码风格、命名规范、格式化工具时使用。 适用于 C++、Python、CMake 的编码规范和格式化流程。
询问 SPONGE 输入文件（mdin.spg.toml）的参数配置时使用。 适用于模拟参数设置、模块配置、输入输出文件指定等。
询问 pixi 用法时使用。 适用于环境管理、依赖安装、任务运行、shell 交互、清理环境等。
询问为 SPONGE 安装、链接、修复或检查 skills 时使用。 适用于 AI 助手的本地或全局 skills 配置。
询问使用 SPONGE 的 PRIPS 对接机器学习/神经网络势场时使用。 适用于 Python plugin 编写、环境准备、力回填。
| name | sponge-build-guide |
| description | 询问 SPONGE 构建、编译、环境配置、构建排错时使用。 适用于 pixi 环境选择、CMake 配置、多后端编译、格式化、打包。 |
本技能适配 SPONGE 版本号：2.0.0-beta.1
用于指导 SPONGE 项目的构建流程，包括环境选择、CMake 配置、编译、格式化和打包。
所有构建通过 pixi 管理，标准流程为三步：
pixi install -e <环境名> # 安装环境依赖
pixi run -e <环境名> configure # CMake 配置
pixi run -e <环境名> compile # 编译并安装
pixi install 会根据 pixi.toml 中的 feature 定义安装对应的 conda 依赖（编译器、CUDA toolkit、数学库等）。首次使用某个环境或依赖有变更时必须执行。pixi run 会自动触发 install，但显式执行可以提前发现依赖问题。
编译产物安装到 $CONDA_PREFIX/bin/SPONGE，构建目录为 build-$PIXI_ENVIRONMENT_NAME。
根据目标硬件和用途选择环境：
| 环境 | 用途 | 并行后端 |
|---|---|---|
dev-cuda13 | CUDA 13 开发（推荐 NVIDIA GPU 开发） | CUDA |
dev-cuda12 | CUDA 12 开发 | CUDA |
dev-hip | AMD GPU / 海光 DCU 开发 | HIP |
dev-cpu | CPU 开发 | 默认 none，可手动指定 SIMD |
dev-cpu-mpi | CPU + MPI 开发 | 默认 none + MPI，可手动指定 SIMD |
cuda13 / cuda12 / hip / cpu / cpu-mpi | 不带 dev 工具的纯构建环境 | 对应后端 |
dev-* 环境额外包含：git、clang-format、cmake-format、ruff、python、pytest、numpy、xponge、ase，用于开发、测试和 benchmark。
非 dev-* 环境仅包含编译依赖，不含测试工具。benchmark 和 format 任务只在 dev-* 环境下可用。
dev-hip 和 hip 环境的 pixi 依赖中不包含 HIP/ROCm SDK，只安装了 cmake、ninja、tomlplusplus。HIP/ROCm 需要用户在系统层面预先安装好，常见方式：
apt install 安装 ROCm 包、从官方源安装、通过 module load 加载对应工具链等CMake 配置时会通过系统路径查找 hipcc / hipconfig 来检测 HIP 环境。如果系统未安装或未正确加载，configure 阶段会报错。
| 变量 | 默认值 | 说明 |
|---|---|---|
PARALLEL | auto | 并行后端选择 |
CUDA_ARCH | native | CUDA 架构（pixi task 中 CUDA 环境固定为 all-major） |
MPI | OFF | 是否启用 MPI |
TARGETS | SPONGE | 构建目标 |
PARALLEL 可选值：
auto：自动检测，优先 GPU（CUDA > HIP），其次 CPU SIMD（AVX512 > AVX2 > AVX > SSE42 > SVE2 > SVE > NEON），最后 nonecuda：CUDA 后端hip：HIP 后端avx512 / avx2 / avx / sse42：x86 SIMD 后端sve2 / sve / neon：ARM SIMD 后端none：纯 CPU 无 SIMDpixi task 中各环境的 PARALLEL 已预设好：CUDA 环境为 cuda，HIP 为 hip，CPU 环境默认为 none（可通过参数覆盖）。
CPU 环境的 configure task 支持 parallel 参数：
pixi run -e dev-cpu configure avx2
这会传入 -DPARALLEL='avx2'，覆盖默认的 none。
compile task 支持 jobs 参数，默认为 4：
pixi run -e dev-cuda13 compile # 默认 4 线程
pixi run -e dev-cuda13 compile 8 # 8 线程
pixi task args 的传参方式是按位置直接传值，不支持 --arg value 或 arg=value 的写法。
gcc/g++ 11.*，通过 CMAKE_CXX_COMPILER 指定gcc/g++ 11.*pixi run install-msvc以下设置在 cmake/utils/common.cmake 中硬编码：
-ffast-math（GCC/Clang）、/fp:fast（MSVC）、--use_fast_math（CUDA）-w / /W0）-Xcompiler 传递-g -G 调试标志177-D 未引用 kernel 警告-Xcompiler 转发给 nvccMPI 仅在 cpu-mpi / dev-cpu-mpi 环境下启用：
pixi run -e dev-cpu-mpi configure
pixi run -e dev-cpu-mpi compile
configure 会自动加 -DMPI=ON 和 -DMPI_CXX_COMPILER="$CONDA_PREFIX/bin/mpicxx"。
CUDA + MPI 场景（当前 pixi.toml 未定义此环境）需要额外链接 NCCL。
pixi run -e dev-cuda13 format # 自动修复所有文件
pixi run -e dev-cuda13 format-check # 仅检查，不修改
覆盖三类文件：
.cpp / .h / .hpp）：clang-format，要求 UTF-8 with BOM.py / .pyi / .ipynb）：ruff formatCMakeLists.txt / .cmake）：cmake-formatpixi run -e dev-cuda13 package-conda
生成 conda v2 格式（.conda）包到 packaging/outputs/。打包脚本会：
dev-cuda13 → cuda13）pixi run -e dev-cuda13 prips-build # 构建 sdist
pixi run -e dev-cuda13 pip install -e ./plugins/prips # 可编辑安装
PRIPS 是 Python 插件接口，用于对接外部机器学习势场。
确认使用了 CUDA 环境（dev-cuda12 或 dev-cuda13），pixi 会自动安装 cuda-nvcc。不要在 CPU 环境里手动指定 -DPARALLEL=cuda。
CUDA 环境在 Linux x86_64 上指定 CMAKE_CXX_COMPILER 为 conda 提供的 x86_64-conda-linux-gnu-c++（GCC 11），不要使用系统编译器。
不同后端的构建目录是隔离的（build-dev-cuda13、build-dev-cpu 等），互不影响。如果同一环境切换了 CMake 选项，需要删除旧构建目录或重新 configure。
这是 conda 环境下 nvcc 的已知警告，不影响编译结果，可以忽略。
C++ 源文件要求 UTF-8 with BOM。运行 pixi run format 会自动修复。
pixi 环境应提供完整的编译工具链，但有时 CMake 会意外找到系统自带的编译器或动态库。如果 pixi 环境内依赖已完备，可以用 pixi install -e <环境名> --clean-envs 重建干净环境来排除系统污染。
但部分场景本身就依赖 pixi 环境外部的工具链，此时不能用 --clean-envs 解决，需要自行处理好环境变量后再调用 pixi，例如：
rm -rf build-dev-cuda13 # 清理特定环境的构建
rm -rf build-* # 清理所有构建
CMakeLists.txt # 根配置，串联以下模块
cmake/
utils/
common.cmake # 编译标准、浮点优化、OpenMP
parallel.cmake # 并行后端选择与检测
checkBackend.cmake # SIMD 特性检测
mpi.cmake # MPI 配置
targets.cmake # 构建目标加载
warning.cmake # 警告压制
parallel/
cuda.cmake # CUDA 后端
hip.cmake # HIP 后端
avx512.cmake / avx2.cmake / avx.cmake / sse42.cmake # x86 SIMD
sve2.cmake / sve.cmake / neon.cmake # ARM SIMD
none.cmake # 纯 CPU（含用于即时编译的 LLVM/Clang 依赖）
math/
cuda.cmake # CUDA 数学库（cuFFT、cuBLAS 等）
hip.cmake # HIP 数学库（hipFFT、hipBLAS 等）
mkl.cmake # Intel MKL（x86 CPU）
open_source.cmake # OpenBLAS + FFTW（ARM CPU）
targets/
SPONGE.cmake # SPONGE 可执行文件的源文件列表
modules/
Findamd_comgr.cmake # AMD comgr 查找模块