“Essentially all models are wrong, but some are useful.” – 乔治·博克斯(George E. P. Box)

eMD用户手册–安装说明

eMD软件主框架使用C++编写，通过Swig工具构建C++类库的Python包装模块；支持CUDA或HIP异构计算加速；依赖统一异构计算编程库hup和JSON格式处理库jsoncpp等外部库。 eMD代码需要编译器支持C++11，GCC 4.6及以上才支持C++11，但是CUDA 8.0需要GCC 4.x作为host端编译器。推荐使用最新的CUDA 10环境，GCC 5以上。eMD采用CMake作为编译管理器，需要CMake最低版本为3.11。 这里主要说明编译主代码程序，进入源代码根目录，编译后的可执行文件为emdrun。关于Python模块的编译和使用见Python扩展，关于Tcl模块的编译和使用见Tcl/VMD扩展。

CMake编译选项说明

  • -DUSE_MPI=STD|THREAD|STUB 设置MPI的实现形式，默认为STD，即标准MPI；THREAD为多线程版本的MPI实现；STUB为串行版本（兼容MPI接口）。推荐使用STD，而THREAD和STUB未做完整测试。

  • -DUSE_CUDA=ON|OFF 选择CUDA编译异构加速模块，开启时会编译源代码中的.cu文件。推荐CUDA 8.0以上。 使用CUDA早期版本编译时，CMake可能需要添加额外选项，通过CUDA_NVCC_FLAGS选项传入。如-DCUDA_NVCC_FLAGS="-std=c++11;-Wno-deprecated-gpu-targets"。 在未安装CUDA节点编译时（如集群登录节点），因找不到libcuda.so报CUDA_CUDA_LIBRARY相关错误，需要设置选项-DCMAKE_LIBRARY_PATH=/usr/local/cuda/lib64/stubs，指向一个stubs（虚拟的）CUDA接口，具体路径名依赖CUDA安装路径。

  • -DUSE_HIP=ON|OFF 选择HIP编译异构加速模块，开启时会编译源代码中的.cu文件，接受HIP_HCC_FLAGS、HIP_HIPCC_FLAGS和HIP_NVCC_FLAGS选项（用分号隔开多个值）。仅测试过HIP的HCC后端配置，而CUDA后端未测试。如果使用CUDA编译，建议直接使用USE_CUDA的方式。注意如果开启了USE_CUDA或者USE_HIP选项，则编译时会自动定义USE_GPU宏变量。

  • -DUSE_SINGLE_REAL=ON|OFF 选择编译单精度浮点版本，默认双精度浮点版本，此值为OFF。eMD的浮点数精度表示在CPU和GPU上是相同的，要么都为单精度，要么都为双精度。但是无论单精度还是双精度版本，像energy和virial等热力学累加变量内部都是使用高精度表示（默认为双精度）。

  • -DUSE_PYTHON=ON|OFF 选择编译Python模块。在源代码根目录下编译主代码时（emdrun），该选项开启后，会自动进入源代码中的python目录进行编译；也可以不设置该选项，直接进入python目录编译。在python目录通过CMake编译之后会生成emd/_emd.so动态库，再使用python setup.py install进行安装。详见Python扩展。

  • -DUSE_TCL=ON|OFF 选择编译Tcl模块。将eMD代码编译为动态库，作为Tcl的一个package存在，进一步也可以作为VMD的一个插件包。在tcl目录通过CMake编译之后会生成emd/emd.so动态库。详见Tcl/VMD扩展。

  • -DUSE_GPROF=ON|OFF 选择GCC开启gprof编译，会在编译标志中添加-g和-pg选项，用于代码的性能分析（用户可选）。默认为OFF。

  • -DSUNWAY=ON|OFF 是否面向申威处理器编译，默认为OFF。

  • -DUSE_CMD_NODE_INFO=ON|OFF 在eMD的sample->statis->node配置中，是否通过直接调用命令输出作为log，在Apple的OSX上建议启用，默认为Linux平台该值为OFF，对应使用字符串解析方式作为log。Windows操作系统该选项无效。

以上为eMD项目定义的一些选项，另外也可以设置CMake提供的默认选项，如

  • -DCMAKE_BUILD_TYPE=Release|Debug 设置编译Release或者Debug版本,在编译Debug版本时，会定义C/C++的DEBUG宏变量。在编译Release版本时，会定义C/C++的NDEBUG宏变量。默认情况下，如果源代码含有git控制（存在.git目录）则编译Debug版本；非git控制下编译Release版本。

  • -DCMAKE_INSTALL_PREFIX=安装路径 设置eMD编译安装目录。

  • -DCMAKE_BUILD_TESTING=ON|OFF 选择编译test目录中的测试模块。默认为OFF。

注意

eMD在通过CMake编译时，会生成src/build_info.h，其中定义了该编译所使用的选项取值。如其中的BUILD_TIMESTAMP宏变量为CMake执行的时间戳，也即对应编译时间。这些编译选项在生成emdrun之后，通过执行emdrun -c可显示出来。
在源代码根目录下的Makefile文件提供了一些常见的CMake编译配置，可以参考其中的选项配置；也可以直接调用make来编译其中预制的版本。如编译单精度浮点版本make single，编译CUDA版本make cuda。

在Linux上安装

在Linux操作系统中，主要使用GCC编译器。因为需要支持C++11，故需要GCC 4.6版本及以上。 为了安装方面，在源代码目录，提供了Makefile文件，其中集成很多make target。 默认all为编译Rlease版本，同时开启了编译test模块。 

all:
    cmake -E make_directory build && cd build && cmake -E rm -rf * && \
        cmake -L -DCMAKE_BUILD_TYPE=Release -DCMAKE_BUILD_TESTING=ON -DCMAKE_INSTALL_PREFIX=$(EMD_ROOT) ..
    cmake --build build  --config Release --verbose
    cd build && ctest -V -N

在ROCm上安装

AMD ROCm平台提供GPU异构计算编程和运行环境。ROCm提供HIP编译器使得同一套代码能够编译运行在NVIDIA或AMD的GPU设备上。HIP的GPU编程模式类似CUDA，提供大部分的兼容的API。eMD能够在Rocm平台上安装，支持Rocm2.9和Rocm3.x版本，能够使用HIP编译运行GPU加速计算模块。eMD实现了CUDA和HIP共有一套GPU加速代码。默认情况下.cu文件使用hipcc编译host和device端代码（HCC模式），而其他.cpp文件为host端代码使用C++编译。C++编译器应选择高版本，需和hipcc的host端能够兼容。如选用dev toolset工具： 

/opt/rh/devtoolset-7/root/usr/bin/cc --version
 c++ (GCC) 7.3.1 20180303 (Red Hat 7.3.1-5)
不要使用系统自动的老版本，有些语法和HIP不兼容。 
/usr/bin/c++ --version
c++ (GCC) 4.8.5 20150623 (Red Hat 4.8.5-39)
编译运行时，使用的HIPCC和HCC运行库的版本要一致。

eMD首选自带的cmake/FindHIP.cmake来识别Rocm/HIP编译平台，这个FindHIP.cmake修正了HIP官方版本中的几个bug，而且识别能力更强。假设相关环境已经使用module配置好，安装步骤如： 

module purge
module add compiler/devtoolset/7.3.1  mpi/hpcx/2.4.1/gcc-7.3.1 
module add compiler/rocm/3.3  compiler/cmake/3.16.2
mkdir -p build && cd build && rm -rf * 
cmake -L -DCMAKE_BUILD_TYPE=Release -DUSE_HIP=ON -DHIPCC_OPTIONS="-fno-gpu-rdc" -DCMAKE_BUILD_TESTING=ON -DCMAKE_INSTALL_PREFIX=${HOME}/local/emd-2.1 ..
make -j 4 VERBOSE=1
ctest -V
cmake --build . --config Release --target install
其中可以传入HIPCC_OPTIONS选项，用于设置hipcc在编译时的选项。比较重要的选项有-fno-gpu-rdc。

注意：对于CUDA环境下，推荐eMD直接使用CUDA编译模式，即定义USE_CUDA选项；而不是HIP下的NVCC模式。

在神威超算上安装

eMD支持在“神威”超级计算机（Sunway TaihuLight）上编译安装，目的在于使用其申威处理器（SW26010 processor）从核加速计算。神威超算的登陆节点为x86处理器，计算节点（主要）为国产申威处理器SW26010，它为主从核结构；在登陆节点一般通过C和CXX编译器进行交叉编译，得到申威处理器上可执行文件。
eMD需要cmake编译环境，需要打开SUNWAY宏变量，即在cmake配置时传入选项-DSUNWAY=ON，推荐使用神威超算最新的cmake版本。默认的sw5CC不支持C++11语法，需要使用其提供的sw5g++的5.3或7.1版本。虽然神威超算提供的cmake是基于x86的环境，但我们指定了C和CXX编译器分别为sw5gcc和sw5g++（最新版本符号链接为swgcc和swg++），并不影响为申威处理器编译出可执行的程序。安装步骤如：

module purge
module add x86/cmake/3.16.7
module add sw/compiler/gcc710
rm -rf build && cmake -E make_directory build && cd build
cmake -L -DCMAKE_C_COMPILER=mpicc -DCMAKE_CXX_COMPILER=mpicxx -DCMAKE_BUILD_TYPE=Release -DCMAKE_BUILD_TESTING=ON -DSUNWAY=ON -DCMAKE_INSTALL_PREFIX=${HOME}/local/emd-2.1 ..
cmake --build .  --config Release --verbose
ctest -V -N
cmake --build . --config Release --target install
也可以使用Makefile提供的sunway目标来编译 
make sunway HOME=/home/export/online3/$USER
make install
sw5gcc/sw5g++ 7.1.0版本的MPI包装命令为mpicc和mpicxx。module加载命令为 
module rm sw/compiler && module add sw/compiler/gcc710
另外神威超算还提供一个sw5gcc/sw5g++的5.3版本，对应的MPI包装命令为mpiswgcc和mpiswg++，它也支持C++11标准，能够用来编译eMD，只是版本相对7.1较旧。 module加载命令为 
module rm sw/compiler && module add sw/compiler/gcc530

在使用sw5gcc 5.3.0版本编译后的可执行文件，提交命令行如： 

bsub -I -q q_sw_share -n 2 /home/export/online3/alwintsui/local/emd-2.1/bin/test_timer
使用sw5gcc 710版本提交脚本时，需要添加-sw3run swrun-5a选项。如 
bsub -I -q q_sw_share -n 2 -sw3run swrun-5a /home/export/online3/alwintsui/local/emd-2.1/bin/test_timer
使用从核需要添加额外参数 
bsub -I -q q_sw_share -sw3run swrun-5a -n 10 -cgsp 64 -share_size 4096 -host_stack 128 /home/export/online3/alwintsui/local/emd-2.1/bin/test_mpi_com

需要注意神威超算编译系统当前还不支持动态库编译方式。因此默认情况下，即SUNWAY选项打开时，eMD会自动选择编译emd和hup的静态库，即libemd.a和libhup.a库。 cmake/3.16.7的cmake -E remove命令不支持循环删除命令-r，因此在Sunway上Makefile中直接使用rm -rf代替。

神威超算使用文档：http://www.nsccwx.cn/guide/5d301c0724364f0351459268

在MacOS上安装

MacOS X操作系统提供Xcode编译环境，原生C/C++编译器为AppleClang，但Xcode环境不支持Fortran编译（需要通过安装GCC来支持Fortran编译器）。eMD代码依赖C++而不依赖Fortran，只需安装OpenMPI来提供mpi编译和运行环境，如果从源代码安装eMD，需要再安装CMake来构建编译系统。

在CMake官方网站下载CMake 最新版本 设置安装目录，开始编译 

./configure --prefix=$HOME/local/cmake/3.18.1
make
make intstall
在OpenMPI官方网站下载OpenMPI最新版本 解压后，设置安装目录，禁用mpi支持fortran（因为MacOS X上没有fortran编译器），开始编译

 ./configure --prefix=$HOME/local/openmpi/4.0.4  --disable-mpi-fortran
make
make install

设置环境变量 

export PATH=$HOME/local/openmpi/4.0.4/bin:$HOME/local/cmake/3.18.1/bin:$PATH
export LD_LIBRARY_PATH=$HOME/local/openmpi/4.0.4/lib:$LD_LIBRARY_PATH
之后就可以借助CMake来编译eMD了。 如果已经安装OpenMPI 4.0+环境，可以直接下载eMD预编译二进制版本运行。

在Windows上安装

在Windows操作系统中，eMD的CMake编译支持Microsoft Visual Studio(MVS)和MS MPI编译环境。在MSV 2019中默认带有CMake 3.18，如是MSV更低版本，需要下载最新的CMake安装。最新版本Microsoft Visual Studio和MS MPI也需要先安装好。eMD提供了一个自动编译安装的BAT脚本 tools/vcbuild.bat,先确认其中的VCVARS_BAT和HOME定义的路径与当前系统适配，之后双击运行该文件执行编译。编译成功之后会自动安装。运行时可以将MS MPI的mpiexec.exe所在的路径和emdrun所在的路径添加到PATH中，这样方便运行。

最后修改: 2024年9月7日, Shun Xu