“The underlying physical laws necessary for the mathematical theory of a large part of physics and the whole of chemistry are thus completely known, and the difficulty is only that the exact application of these laws leads to equations much too complicated to be soluble. It therefore becomes desirable that approximate practical methods of applying quantum mechanics should be developed, which can lead to an explanation of the main features of complex atomic systems without too much computation.” –狄拉克（Paul Dirac）

eMD用户手册–快速上手

编译与运行

eMD编译需要使用CMake 3.11+和支持C++11的编译器，另外Python模块使用Python3和Swig包装工具。详见安装说明。eMD使用MPI接口实现分布式计算，但是还支持多线程式的MPI实现和串行版本，可以通过CMake的USE_MPI选项来设置。这里以eMD标准MPI并行版本为例说明。
设置EMD_ROOT环境变量指向eMD安装路径（对应CMake中的CMAKE_INSTALL_PREFIX选项值）。也可配置module来加载eMD安装环境，如

module add emd/2.1/mpi_cpu

测试emdrun是否能够成功运行，添加-c选项显示编译时的配置参数。

emdrun -c

正式运行时，首先进入eMD模拟配置目录，以example/bench/ljmelt为例：

cd example/bench/ljmelt
mpirun -n 2 emdrun -i lj_nve.json

emdrun使用-i选项指定JSON格式的模拟配置文件。
如果是使用SLURM环境，可通过srun提交，如

srun --mpi=pmix -p app --exclusive -N 2 -c 10 emdrun -i lj_nve.json

使用emdlog.py脚本可以提取log中statis数据:

python3 ${EMD_ROOT}/bin/emdlog.py -h
python3 ${EMD_ROOT}/bin/emdlog.py example.log
python3 ${EMD_ROOT}/bin/emdlog.py example.log -s force:Step,Epot

简单实例

模拟配置文件lj_nve.json的内容如下：

data-linenos=" 1 ">{ "particles" : { "position" : { "dim" : 3, "boundary" : ["p","p","p" ], "create_atoms" : { "region" : { "type" : "block", "args" : [0,4,0,4,0,4 ] } , "lattice" : { "units" : "lj", "type" : "fcc", "scale" : 0.8442 } , "basis_types" : [ 1,1,1,1 ] } } , "topology" : { "atom_type" : [ { "type" : "Kr", "mass" : 1.0 } ] } , "velocity" : { "type" : "create", "rndseed" : 87287, "temp" : 1.44, "dist" : "uniform", "loop" : "geom" } } , "force_field" : { "units" : "lj", "type" : "lammps", "pair" : { "type" : "lj_cut", "cutoff" : 2.5, "shift" : 0, "tail" : 0, "coeff" : [ { "itype" : 1, "jtype" : 1, "epsilon" : 1, "sigma" : 1 } ] } , "newton" : true, "ghost_vel" : false, "neighbor" : { "every_step" : 6, "skin" : 0.3, "pair_search" : "bin" } } , "mechanics" : { "run_steps" : 100, "timestep" : 0.005, "type" : "mdvv" } , "sample" : { "statis" : [ { "type" : "force", "every_step" : 5, "fields" : [ "temp", "epot", "ekin", "etotal", "press" ] } ] } }

执行以上配置的模拟，其log默认为标准输出，log内容有如

eMD - A Molecular Dynamics Parallel Simulator
  Version: eMD-2.1.2
  Git version: 60b4764
  Build Timestamp: 2020-09-27 10:13:13
  Build type: RELEASE
  Build C Compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/cc AppleClang 11.0.3.11030032
  Build CXX Compiler: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++ AppleClang 11.0.3.11030032
  Build GPU: NO
  Install Prefix: /Users/alwin/local/emd-2.1
  Source Dir: /Users/alwin/resdev/mdsim/eMD/emd.git
  Work Dir: /Users/alwin/resdev/mdsim/eMD/emd.git/example/bench/ljmelt
  Share Dir: /Users/alwin/local/emd-2.1/share
  real precision: float64
  natom_t precision: int32
  nbpair_t precision: int32
  nstep_t precision: int64
  nimg_t precision: int8
Load parameters from file: lj_nve.json
Here is log file stdout
Platform information of master node(xs-mbp.local) in the world of 1 node(s) / 2 rank(s):
  Kernel type: Darwin
  Kernel release: 19.6.0
  CPU vendor: GenuineIntel
  CPU features: SSE2 AVX2 FMA3 
  # CPU: 4
  # Core: 2
  # Numa: 0
  Memory size: 0K / 8.00G
  Loadavg: 14.8428, 15.2637, 15.249
  Boottime: Sep23
  Uptime: 3-14:41:15
  Launch time: 20-09-27 11:39:20
Note: the information given here may be different to the REAL one.
Prepare Particles ...
Particles:
{
   "position" : {
      "boundary" : [ "p", "p", "p" ],
      "create_atoms" : {
         "basis_types" : [ 1, 1, 1, 1 ],
         "lattice" : {
            "scale" : 0.84419999999999995,
            "type" : "fcc",
            "units" : "lj"
         },
         "region" : {
            "args" : [ 0, 4, 0, 4, 0, 4 ],
            "type" : "block"
         }
      },
      "dim" : 3
   },
   "topology" : {
      "atom" : {
         "type" : "atomic"
      },
      "atom_type" : [
         {
            "mass" : 1.0,
            "type" : "Kr"
         }
      ]
   },
   "velocity" : {
      "dist" : "uniform",
      "loop" : "geom",
      "rndseed" : 87287,
      "temp" : 1.4399999999999999,
      "type" : "create"
   }
}

Create fcc lattice with id 1
  lattice spacing in x, y, z = 1.6796, 1.6796, 1.6796 with lj units
Create block region with id 1
Set block region(1) to fcc lattice(1) with units lj
Set box dimension=3
Set box boundary=[(p,p),(p,p),(p,p)]; periodic=(1, 1, 1), nonperiodic=0
Orthogonal global box: (0, 0, 0) to (6.71838, 6.71838, 6.71838)
Boundary box: (0, 0, 0) to (6.71838, 6.71838, 6.71838),  gbox size = (6.71838, 6.71838, 6.71838)
Grid 3 dims: 1 x 1 x 2
Rank 0: grid pos=(0,0,0), x-neighbor=(0,0), y-neighbor=(0,0), z-neighbor=(1,1)
Orthogonal local box(0): (0, 0, 0) to (6.71838, 6.71838, 3.35919) = (6.71838, 6.71838, 3.35919)
Get relax local box(0): (-6.71838e-06, -6.71838e-06, -6.71838e-06) to (6.71837, 6.71837, 3.35919), efactor=-2
Create atom vector: atomic
Load atom types ...
id, name, mass
  0, Kr, 1
Create 128 atoms with fcc lattice(1) and block region(1)
Atom vector(atomic): atom-tag range [0, 255]
Creates 256 atoms, with 1 atom types

Create force field: lammps
ForceField:
{
   "ghost_vel" : false,
   "neighbor" : {
      "every_step" : 6,
      "pair_search" : "bin",
      "skin" : 0.29999999999999999
   },
   "newton" : true,
   "pair" : {
      "coeff" : [
         {
            "epsilon" : 1,
            "itype" : 1,
            "jtype" : 1,
            "sigma" : 1
         }
      ],
      "cutoff" : 2.5,
      "shift" : 0,
      "tail" : 0,
      "type" : "lj_cut"
   },
   "type" : "lammps",
   "units" : "lj"
}

Init Pair(lj_cut): coeff-size=1, shift=0, tail=0, mix-type=geometric, ghost_neigh=0, full_neigh=0
  cutoff=2.5
ForceField summary:
  Newton: 1 (pair = 1, bond = 1)
  Neighbor: neigh_pair=bin, skin=0.3, start_step=0, every_step=6, dist_check=1, page_size=32
  Special pair: lj=0, 0, 0; coul=0, 0, 0; angle-only=0, dihedral-only=0
  Pair types: lj_cut
 Units type: lj
  boltz: 1
  hplanck: 0.18292
  nktv2p: 1
  ftm2v: 1
 Molecule type: 0
  newton: 1
  ghost_vel: 0
Create Mechanics:
{
   "run_steps" : 100,
   "timestep" : 0.0050000000000000001,
   "type" : "mdvv"
}

Create mechanics: mdvv
Create thermo: base
Mechanics(mdvv): timestep=0.005, init-steps=0, run-steps=100, extra-dof=3, external-force-clear=0
Init Sample:
{
   "statis" : [
      {
         "every_step" : 5,
         "fields" : [ "temp", "epot", "ekin", "etotal", "press" ],
         "type" : "force"
      }
   ]
}

Create statis: force
Setup topology ...
Group 'all': 256 atoms, total mass 256, total charge 0
Zero linear momentum of group 'all' when setting temperature
Create velocity for 256 atoms with temperature 1.44 and loop-flag 1
Setup Pair(lj_cut): atom-types=1/1, max-cutoff=2.5, neighbor req-id=0
Neighbor build:
  # of pair-request: 1
  # of neigh-pair: 1
  # of bonded-request: 0
  # of neigh-bonded: 0
  cutoff+skin: min=2.8, max=2.8
Node         hostname  memfree  memtotal  CPULoad@Avg1   Avg5  Avg15  datetime
master : xs-mbp.local  0K       8.00G           14.843  15.264  15.249  20-09-27 11:39:20
Mechanics(mdvv): box-change=0, ghost cutoff=2.8, max_bond_cutskin=0, max_pair_cutskin=2.8
MDVV slot layout
  pre_mech_setup:
  initial_integrate:
  post_integrate:
  if neighbor build:
    pre_fit_local:
    pre_neighbor:
  pre_force:
  post_force:
  final_integrate:
  end_of_step:
#-force (0 % 5 @ -1):            Temp             Epot             Ekin           Etotal            Press  
$-force (0 % 5 @ 0):            1.44       -1733.9822            550.8       -1183.1822       -5.0244179  
MD velocity verlet running ...
$-force (0 % 5 @ 5):       1.3778561       -1710.2936        527.02996       -1183.2636       -4.4753934  
$-force (0 % 5 @ 10):       1.1298532       -1615.2448        432.16886        -1183.076       -2.6058175  
$-force (0 % 5 @ 15):      0.73615119       -1464.9574        281.57783       -1183.3796      0.047247514  
$-force (0 % 5 @ 20):       0.6239063       -1422.7569        238.64416       -1184.1127       0.97451173  
$-force (0 % 5 @ 25):      0.71151671       -1456.9477        272.15514       -1184.7925       0.58435925  
$-force (0 % 5 @ 30):      0.74156074       -1468.4068        283.64698       -1184.7598       0.39337583  
$-force (0 % 5 @ 35):      0.73239625       -1464.9792        280.14157       -1184.8376       0.40957679  
$-force (0 % 5 @ 40):      0.75047309       -1471.8688        287.05596       -1184.8129       0.30085576  
$-force (0 % 5 @ 45):      0.73163552        -1464.927        279.85059       -1185.0764       0.38269534  
$-force (0 % 5 @ 50):      0.70303849       -1453.9818        268.91222       -1185.0696       0.50453907  
$-force (0 % 5 @ 55):      0.74169526       -1468.6735        283.69844        -1184.975       0.25818702  
$-force (0 % 5 @ 60):      0.77733499       -1482.3232        297.33064       -1184.9926      0.032439634  
$-force (0 % 5 @ 65):      0.75259965       -1473.2783        287.86937       -1185.4089       0.16102043  
$-force (0 % 5 @ 70):      0.72493293       -1462.8438        277.28685       -1185.5569       0.33829359  
$-force (0 % 5 @ 75):      0.72571309        -1463.005        277.58526       -1185.4198       0.34740771  
$-force (0 % 5 @ 80):      0.75554724       -1474.1382        288.99682       -1185.1413       0.16379837  
$-force (0 % 5 @ 85):      0.78904962       -1486.9199        301.81148       -1185.1084     -0.048538146  
$-force (0 % 5 @ 90):      0.76776187       -1478.7975        293.66891       -1185.1286      0.053118706  
$-force (0 % 5 @ 95):      0.72641502       -1462.9985        277.85374       -1185.1448       0.28556212  
$-force (0 % 5 @ 100):      0.72628044       -1463.0598        277.80227       -1185.2575       0.29765862  
Node         hostname  memfree  memtotal  CPULoad@Avg1   Avg5  Avg15  datetime
master : xs-mbp.local  0K       8.00G           14.843  15.264  15.249  20-09-27 11:39:20

256 atoms run 100 steps on 2 processors in 0.02216 sec. with 87.4% CPU usage
Performance: 1949766.434 tau/day, 4513.348 timesteps/s
Neighbor list built 7 times 0 dangerous times

Task walltime (sec.): Min          Max          Ave     %Std   %Total     Min rank@node       Max rank@node
--------------------------------------------------------------------- - --------------------------------------
Total time        0.02215      0.02216      0.02216    0.227      100       0@xs-mbp.local      1@xs-mbp.local
CPU time          0.01895      0.01979      0.01937     13.6     87.4       0@xs-mbp.local      1@xs-mbp.local
--------------------------------------------------------------------- - --------------------------------------
Pair force         0.0104      0.01062      0.01051     4.71     47.4       1@xs-mbp.local      0@xs-mbp.local
Neighbor         0.002774     0.003321     0.003047     22.4     13.8       0@xs-mbp.local      1@xs-mbp.local
Communi.         0.005811     0.006641     0.006226     23.7     28.1       0@xs-mbp.local      1@xs-mbp.local
Mechanics        0.000234     0.000238     0.000236    0.588     1.07       0@xs-mbp.local      1@xs-mbp.local
Output           0.000654     0.001402     0.001028     52.6     4.64       1@xs-mbp.local      0@xs-mbp.local
Other           0.0008825      0.00131     0.001096     29.1     4.95       1@xs-mbp.local      0@xs-mbp.local
--------------------------------------------------------------------- - --------------------------------------
Count (total 256 atoms):
--------------------------------------------------------------------- - --------------------------------------
Atom local            124          132          128    0.138       50       1@xs-mbp.local      0@xs-mbp.local
Atom ghost           1087         1098         1092    0.065      427       0@xs-mbp.local      1@xs-mbp.local
Neigh bin              59           62         60.5   0.0753     23.6       0@xs-mbp.local      1@xs-mbp.local
--------------------------------------------------------------------- - --------------------------------------

从log大致看出eMD的执行顺序： 1. 首先显示编译配置信息，包括编译时间、版本号、浮点数精度（real），原子tag整型字长（natom_t）等信息。 2. 之后显示当前输出log所在节点的配置信息，如CPU核数，主机负载情况。 3. 然后就是依次加载配置文件中的particles、force_field、mechanics和sample等字段，分别执行Init和Setup过程。 4. 进入正式MD主循环，期间通常会输出统计量和采集样本。 5. 退出MD主循环，打印计算性能数据。

emdrun的配置文件实质含有7个字段，除了上面的四个字段之外，还有comm并行通讯、context上下文和variable变量替换三个字段。这些字段不是在每个实例配置中必须的，省略时使用默认值。

context字段

有时我们需要控制log的输出形式，就需要用到context字段。在配置的顶层添加context字段如下，用于选择输出log的rank和对应的log文件名。如以下配置输出log到emd_ljmelt.log文件。

"context" : {
    "logfile" : "emd_ljmelt.log",
    "logrank":[0] }

eMD支持同时多个rank输出log，由context中的logrank数组给出多个rank元素即可，这时logfile应该使用通配符号。比如启动4个MPI rank的运行中，选择1,3两个rank输出log信息，相关的配置可为

"context" : {
    "logfile" : "emd_ljmelt%r.log",
    "logrank":[1,3] }

这样rank 1会产生emd_ljmelt1.log文件，rank 3会产生emd_ljmelt3.log文件。其中”%r”为通配符代表rank值，详见参数配置中的“context 上下文配置”。

paritcles字段

particles字段用于配置体系的坐标position、拓扑topology和初始速度velocity。该实例为基于Lattice自动生成体系结构。若这三个子段使用import其他类型的配置时，会自动生成，如导入LAMMPS data时，见example/chain/chain_ext.json的particles字段：

"particles" : {
        "import" : "data.chain_ext",
        "import_type" : "lammps.bond" 
        }

通过import文件，导入position、topology和velocity等属性（如果import文件中存在）。

force_field字段

force_field字段可以通过include导入json格式的力场子文件，也可以使用import导入其他格式的力场文件信息。

参数type最关键，当前可选择lammps、xcharmm、gromacs和moly，不同的类型对应不同的力场匹配。类型不同力场集不同。
参数units设置体系的单位制，单位制名称类似LAMMPS，eMD还提供charmm单位制。
参数pair、bond、angle、dihedral和improper等用于力场参数的设置，其中coeff子参数设置不同类型下的参数因子。
参数neighbor用于设置构建邻居列表方法，其中参数pair_search提供bin和nsq两种构建方式。在以上的例子中，修改配置参数force_field->neighbor->pair_search为“nsq”，可以看到Warnning输出，指示当前的邻居列表构建方式不合适（计算效率低），应该使用bin方式。
参数newton设置作用力计算时，是否使用反作用力形式，默认为true。
参数ghost_vel控制区域划分中本地proc上的ghost atom除了带上位置pos是否还需速度vel属性，有些作用力计算需要速度信息，因此需要边界原子（ghost原子）具有速度信息，如DPD pair作用力计算时。
对于分子体系还有参数special_pair的设置。

mechanics字段

参数”type”:”mdvv”表示模拟采用velocity verlet的动力学积分方式，而timestep给定积分步长，其单位和force_field中units指定的单位制吻合。run_steps表示执行的MD步数，也即主循环步数。eMD在进入主循环之前，会计算一次体系初始力（和能量），在log中显示为step=0时的信息。

sample字段

sample字段包括两个输出相关的子字段statis和trajectory。前者大多关联统计相关的量如热力学量，后者和轨迹输出相关。statis当前包括force、domain、mechanics、articles和node等分类。statis可以为对象的数组形式参数，以支持多个statis子类输出。这里仅使用了force这个子类，其包括通常需要输出的能量和压强等信息。每个子类在log输出时会显示其包含域的名称，此例中以“#-force”开始的行；并在每个输出步时，显示各个域的输出值，此例中以“$-force”开始。其中(a % b % c)表示从第a步开始，每隔b步，当前为c步。
trajectory也可以是一个数组形式，以实现多个轨迹文件输出，支持轨迹文件格式为xyz,pdb,xtc,dcd,gro,psf和LAMMPS data等，默认通过后缀识别轨迹文件格式。可见例子example/bench/ljmelt_extra/lj_nvt.json。
在sample输出之后，还给出一些性能分析数据，包括CPU使用率、力场计算开销分析，和体系原子划分情况。如果使用了GPU加速，还会给出GPU模块的计算时间开销分析。

example说明

更多的例子参考eMD源代码中的example目录，可以拷贝到用户目录来测试，如

cp -r ${EMD_ROOT}/example emd_example
cd emd_example/bench/ljmelt
mpirun -n 2 emdrun -i lj_nve.json

有些实例提供了批量测试的shell脚本和对应的LAMMPS、NAMD等配置文件，可以作为对比参考。源代码中提供example目录，其中包含emdrun各种配置输入文件。Python模块的实例见python/emd目录。

当前提供实例的说明

ljmelt
lj_nve.json Lennard Jones体系的NVE模拟
lj_nve_gpu.json 对lj_nve.json配置体系的GPU加速版
lj_nvt.json 构建NVT系综和Sample轨迹输出的配置实例
lj_press.json 使用压强耦合的配置实例
lj_min.json 随机位置的原子体系的势能最小化过程的配置实例
lj_conf.json 初始坐标从文件导入的配置实例
lj_bound.json 非周期性边界条件的配置实例
lj_group.json 使用多个group的配置实例
lj_region.json 使用多个region的配置实例
lj_bitreg.json 构建基于位图region原子体系的配置实例（bitreg.tcl为VMD绘图脚本）
lj_setforce.json 实现region区域原子力修改的配置实例（setforce.tcl为VMD绘图脚本）
benethy
benethy.json 苯和乙烯的有机小分子体系，使用OPLS-AA力场
benethy_reset.json 苯和乙烯的有机小分子体系，使用reset修改原子属性。
alanin
alanin_nvt.json 丙氨酸（alanine）体系
chain
chain_nve.json FENE 珠-簧模型的NVE系综模拟
chain_nve_lmp.json 从LAMMPS data文件导入体系和力场数据的FENE珠-簧模型的NVE系综模拟
chain_gpu.json 对chain_nve.json配置体系的GPU加速版
chain_ext.json 大体系的FENE模型的配置实例
dpd
dpd.json 模拟耗时粒子动力学（DPD）体系
dpd_gpu.json 使用GPU加速模拟DPD体系的配置实例
dpd_mix.json 模拟二元DPD体系
dpd_mix_gpu.json 使用GPU加速模拟二元DPD体系
gce
lj_gce_nvt.json 基于NVT的广义正则系综（GCE）模拟Lennard Jones体系
lj_gce_npt.json 基于NPT的广义正则系综（GCE）模拟Lennard Jones体系
martini/DPPC
run.json 使用Martini力场模型，模拟DPPC双层磷脂体系
run_gpu.json 使用GPU加速模拟DPPC双层磷脂体系。
min.json DPPC双层磷脂体系的最小化过程配置文件。
phosphate
phosphate.json 磷酸盐体系模拟
phosphate_gpu.json 使用GPU加速模拟磷酸盐体系
water_ice
iceih.json TIP4P模型的水成冰体系模拟
purewater.json 纯水体系采用GROMACS输入配置格式的模拟
remd
lj_nvt_remd.json 副本交换模拟配置实例
rhodopsin
rhodo_nve.json 视紫红质（rhodopsin）蛋白体系模拟
rhodo_fsw_nve.json 使用力switch方式的力场模拟视紫红质蛋白体系
ubq_ws
ubq_ws.json 泛素多肽水溶液体系模拟

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