容器使用指南
概述
本指南介绍如何获取并启动科学计算套件容器镜像、验证容器运行环境，以及运行镜像中预集成的应用。
适用场景为基于 MTT S5000 开展环境部署、首次验证和科学计算任务运行。
前置条件
使用本镜像前，请确认宿主机满足以下条件：
- 已安装 Linux Driver 5.2.0。驱动安装包已包含配套固件，无需单独安装。
- 已按 KUAE 云原生套件安装指南 完成容器运行时配置，确保容器能够正常使用 GPU。
- 执行
mthreads-gmi时能够正常识别 GPU
进入容器后，默认工作目录为 /opt/scs；镜像内置数据统一通过 /workspace/dataset 访问。容器内提供了中文与英文说明文件，分别位于 /opt/scs/README.md 和 /opt/scs/README_EN.md。
预集成软件
| 名称 | 类型 | 说明 | 路径 |
|---|---|---|---|
| MUSA Toolkit | 软件 | 摩尔线程 GPU 应用开发、编译和运行所需的基础软件栈。 | /usr/local/musa |
| GROMACS | 软件 | 面向生物分子和软物质体系的高性能分子动力学软件。 | /opt/gromacs/2023.3、/opt/gromacs/2026.1 |
| LAMMPS | 软件 | 面向原子、分子和材料体系的并行分子动力学模拟软件。 | /opt/lammps |
| Amber | 软件 | 面向生物分子结构、动力学和相互作用分析的软件套件，当前版本为 Alpha 版本。 | /opt/amber24、/opt/amber24_mpi |
| SPONGE | 软件 | 面向分子模拟任务的高性能分子动力学软件。 | /opt/sponge |
| 内置数据入口 | 目录 | 容器内统一数据入口，用于访问镜像内置数据。 | /workspace/dataset |
快速开始
首次验证建议按以下步骤执行：
步骤 1：检查宿主机环境
在启动容器前，先确认宿主机 GPU 与 Docker 服务状态正常：
mthreads-gmi
docker info
步骤 2：拉取镜像
镜像可通过容器镜像下载入口获取。首次使用时，建议先设置镜像地址并执行 docker pull 拉取镜像：
export SCS_IMAGE=registry.mthreads.com/mcconline/scientific_computing_suite:1.1.0-musa5.2.0
docker pull ${SCS_IMAGE}
当前版本中，latest 标签对应 1.1.0-musa5.2.0。如需使用 latest 标签，可执行以下命令：
export SCS_IMAGE=registry.mthreads.com/mcconline/scientific_computing_suite:latest
docker pull ${SCS_IMAGE}
步骤 3：启动容器
推荐以交互式方式完成首次验证。以下命令默认沿用步骤 2 中定义的 SCS_IMAGE 变量。
docker run -it --rm --privileged \
--network host \
-v /etc/resolv.conf:/etc/resolv.conf:ro \
${SCS_IMAGE} bash
如宿主机 DNS 配置正常，可省略 -v /etc/resolv.conf:/etc/resolv.conf:ro。
如需关闭登录欢迎提示，可在 docker run 中增加 -e SCS_NO_WELCOME=1。
如需后台运行
docker run -d --privileged \
--name scientific-suite-runtime \
--network host \
-v /etc/resolv.conf:/etc/resolv.conf:ro \
${SCS_IMAGE} tail -f /dev/null
docker exec -it scientific-suite-runtime bash
步骤 4：验证容器运行时
容器启动后，应先验证 MUSA 运行时和编译器：
/usr/local/musa/bin/musa_runtime_version
/usr/local/musa/bin/mcc --version
验证成功时，输出中应包含 5.2.0 版本信息。示例如下：
MUSA Runtime Version: 5.2.0
...
mcc version 5.2.0
如果以上命令失败，请参见下方常见问题。
环境准备
MUSA Toolkit
安装路径：
/usr/local/musa
如需手动补充环境变量，可执行：
export MUSA_HOME=/usr/local/musa
export PATH=/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}
检查运行时：
/usr/local/musa/bin/musa_runtime_version
/usr/local/musa/bin/mcc --version
应用验证
在运行目标应用前，请先加载对应环境变量。首次验证建议优先执行内置测试或示例命令，再切换到您自己的输入数据。
GROMACS 2023.3
GROMACS 是面向生物分子、软物质和相关复杂体系的高性能分子动力学软件，广泛用于蛋白质、膜体系、溶液体系和小分子体系的模拟与分析。它具备成熟的并行能力和较完整的前后处理工具链，适合用于环境可用性验证、基准测试和实际分子动力学任务运行。
安装路径：
/opt/gromacs/2023.3
加载环境：
source /opt/gromacs/2023.3/bin/GMXRC
export LD_LIBRARY_PATH=/opt/gromacs/2023.3/lib:/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}
运行内置测试：
cd /opt/gromacs/2023.3/unittest/build
ctest --output-on-failure
运行示例：
gmx mdrun -ntmpi 1 -ntomp 24 -s /path/to/input.tpr -deffnm md \
-noconfout -pin on -nb gpu -bonded gpu -pme gpu -gpu_id 0
GROMACS 2026.1
GROMACS 2026.1 是镜像中提供的较新版本，适合用于验证新版本软件栈在摩尔线程 GPU 平台上的编译、运行与功能兼容性。相较旧版本，它更适合作为后续应用迁移、版本对比和新算例验证的基础环境。
安装路径：
/opt/gromacs/2026.1
加载环境：
source /opt/gromacs/2026.1/bin/GMXRC
export LD_LIBRARY_PATH=/opt/gromacs/2026.1/lib:/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}
运行内置测试：
cd /opt/gromacs/2026.1/unittest/build
ctest --output-on-failure
运行示例：
gmx mdrun -ntmpi 1 -ntomp 24 -s /path/to/input.tpr -deffnm md \
-noconfout -pin on -nb gpu -bonded gpu -pme gpu -pmefft gpu \
-update gpu -gpu_id 0
LAMMPS
LAMMPS 是面向原子、分子和材料体系的大规模并行分子动力学模拟软件，常用于材料科学、化学、能源和力学等场景。它支持多种势函数、边界条件和计算模型，适合用于验证 GPU 加速环境是否可用，以及开展典型材料模拟任务。
安装路径：
/opt/lammps
环境变量：
export PATH=/opt/lammps/bin:/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/opt/lammps/lib:/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}
运行内置测试：
cd /opt/lammps/unittest/build
ctest --output-on-failure
运行示例：
mpirun -np 1 /opt/lammps/bin/lmp -sf gpu -pk gpu 1 -in /path/to/input.in
Amber
Amber 是面向生物分子结构建模、分子动力学模拟和相互作用分析的软件套件，常用于蛋白质、核酸和配体体系研究。镜像中的 Amber 24 当前为 Alpha 版本。首次验证建议优先使用单卡 pmemd.cuda 命令；如需多卡运行，可进一步参考 pmemd.cuda.MPI 的 8 卡启动方式。
安装路径：
/opt/amber24
/opt/amber24_mpi
串行环境：
export AMBERHOME=/opt/amber24
export PATH=/opt/amber24/bin:/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/opt/amber24/lib:/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}
串行运行示例：
pmemd.cuda -O -o mdout.txt -i input.in -p topology.top -c restart.rst
MPI 环境：
export AMBERHOME=/opt/amber24
export PATH=/opt/amber24/bin:/opt/amber24_mpi/bin:/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/opt/amber24/lib:/opt/amber24_mpi/lib:/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}
MPI 运行示例（8 卡）：
mpirun -np 8 pmemd.cuda.MPI -O -o mdout.txt -i input.in -p topology.top -c restart.rst
可选测试命令：
cd /opt/amber24/test
make -k -f Makefile test.pmemd.cuda PREC_MODEL=SPFP
SPONGE
SPONGE 是面向分子模拟与相关计算任务的高性能分子动力学软件，适用于在 GPU 平台上开展典型分子体系的计算验证与任务运行。可直接使用镜像内置示例快速确认环境、数据路径和应用是否可正常运行。
安装路径：
/opt/sponge
环境变量：
export SPONGE_HOME=/opt/sponge
export PATH=/opt/sponge/bin:/usr/local/musa/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}
内置示例输入：
cd /workspace/dataset/sponge/sponge
SPONGE -mdin mdin.txt
运行示例：
SPONGE -mdin /path/to/mdin.txt
最小验证路径
如需快速完成一轮可用性验证，可按下表执行：
| 软件 | 环境准备 | 首次验证 |
|---|---|---|
| GROMACS 2026.1 | source /opt/gromacs/2026.1/bin/GMXRC | cd /opt/gromacs/2026.1/unittest/build && ctest --output-on-failure |
| LAMMPS | export PATH=/opt/lammps/bin:/usr/local/musa/bin:$PATH | cd /opt/lammps/unittest/build && ctest --output-on-failure |
| Amber | export AMBERHOME=/opt/amber24 | pmemd.cuda -O -o mdout.txt -i input.in -p topology.top -c restart.rst |
| SPONGE | export PATH=/opt/sponge/bin:/usr/local/musa/bin:$PATH | cd /workspace/dataset/sponge/sponge && SPONGE -mdin mdin.txt |
常见问题
容器内无法识别 GPU
请检查：
- 是否使用了
--privileged或等效权限配置 - 容器运行时是否透传了 GPU 设备节点
- 宿主机驱动是否正常工作
- 是否已按 KUAE 云原生套件 完成容器运行时配置
musa_runtime_version 无法执行
- 宿主机 Linux Driver 版本是否为 5.2.0
/usr/lib/x86_64-linux-gnu/libmusa.so*是否由容器运行时正确提供- 是否误将其他版本的 MUSA 路径加入
LD_LIBRARY_PATH
应用启动时报找不到共享库
- 是否已加载对应软件的环境变量
LD_LIBRARY_PATH是否包含目标软件库目录LD_LIBRARY_PATH是否包含/usr/local/musa/lib和/usr/local/musa/lib64
