search

USCCACS / RXMD

RXMD : Linear-Scaling Parallel Reactive Molecular Dynamics Simulation Engine
https://magics.usc.edu/rxmd/
GNU General Public License v3.0
23 stars 14 forks source link
materials-genome molecular-dynamics parallel-computing rmd

readme

rxmd : Linear Scalable Parallel ReaxFF Molecular Dynamics Simulator

rxmd has been developed to simulate large-scale Reactive Force Field molecular dynamics (MD) simulations on from commodity laptops to high-end supercomputing platforms. rxmd has been used in a various class of material studies, such as shock-induced chemical reactions, stress corrosion cracking, underwater bubble collapse, fracture of self-healing ceramics and oxidation of nanoparticles.

0. Prerequisites

rxmd is designed to be simple, portable and minimally dependent on 3rd party library. You will need 1) a Fortran compiler that supports OpenMP, and 2) MPI (Message Passing Interface) library for parallel and distributed simulation. Modern Fortran compilers natively support OpenMP, and you can find many freely available MPI libraries online. Please refer to MPI library developer website about how to install their library.

rxmd has been tested on following environments.

- Fortan Compiler:

GNU Fortran (GCC) 6.1.0
Intel Fortran (IFORT) 17.0.4
IBM XL Fortran V14.1

- MPI library:

OpenMPI 1.8.8
MPICH2
MVAPICH2 
Cray Mpich 7.6.0

1. Getting Started

To get started, clone this repository to your computer. 

~$ git clone https://github.com/USCCACS/rxmd.git rxmd

2. How to build RXMD

2.1 Working Directory

Frist, change working directory to rxmd/

~$ cd rxmd

you will see following files and directories.

rxmd $ ls
DAT/        Makefile    conf/       docs/       ffield      regtests/   src/        util/
LICENSE.md  README.md   config/     examples/   init/       rxmd.in     unittests/

Here, two directories, src/ and init/, are especially important for you. src/ contains all rxmd source codes and init/ has a program and input files to generate an initial configurations for simulation.

2.2 Configure Makefiles

There is an important file called make.inc that you might need to modify according to your computing environment.

Example 1) Linux Computer with Intel Compiler

Many HPC centers have Intel Fortran compiler and its MPI binding installed. If this is the case, copy the make_hpc.inc from config/ as make.inc. It should look as shown below

2.3 Prepare Initial Geometry

Next step is to generate initial MD geometry. Type the make command shown below. 

rxmd $ make -C init/

This compiles the standalone application geninit, read a geometry file (init.xyz by default) in init/ directory, replicate the geometry and save the entire initial MD geometry into rxff.bin file, and then place rxff.bin file in DAT/ directory.

2.4 Build RXMD

Type the command below to build the rxmd executable.

rxmd $ make -C src/

Check to see if you the rxmd executable and the initial geomerty input DAT/rxff.bin in place, then you are ready to start a simulation.

rxmd $ ls
DAT/        Makefile    conf/       docs/       ffield      make.inc    rxmd*       src/        util/
LICENSE.md  README.md   config/     examples/   init/       regtests/   rxmd.in     unittests/

rxmd $ ls DAT/
rxff.bin

3. How to run

Default input parameters are set to run a single process job. In rxmd.in, the parameter vprocs defines how many MPI ranks in x, y, and z directions. Make sure you have 1 1 1 here. 

rxmd $ grep vprocs rxmd.in 
processors   1 1 1                  <vprocs>

To run single MPI rank job on a typical Linux computer, you can simply type

rxmd $ ./rxmd

How to run a multi process job depends on which MPI library you use, but most likely mpirun just works for you. 

rxmd $ mpirun -np nprocessors ./rxmd

If you see following outputs, congratulations! You have everything working.

rxmd $ ./rxmd 
              rxmd has started
----------------------------------------------------------------
         req/alloc # of procs:        1  /        1
         req proc arrengement:        1        1        1
                parameter set:Reactive MD-force field: nitramines (RDX/HMX/TATB/PETN)               
                time step[fs]:    2.50E-01
 MDMODE CURRENTSTEP NTIMESTPE:  1         0       100
  isQEq,QEq_tol,NMAXQEq,qstep:     1   1.0E-07   500     1
                Lex_fqs,Lex_k:   1.000   2.000
            treq,vsfact,sstep:     300.000   1.000      100
                  fstep,pstep:   100    10
               NATOMS GNATOMS:                     168                     168
                         LBOX:       1.000       1.000       1.000
                  Hmatrix [A]:         13.180          0.000          0.000
                  Hmatrix [A]:          0.000         11.570          0.000
                  Hmatrix [A]:          0.000          0.000         10.710
               lata,latb,latc:      13.180      11.570      10.710
          lalpha,lbeta,lgamma:      90.000      90.000      90.000
               density [g/cc]:    1.8061
         # of linkedlist cell:     4     3     3
            maxrc, lcsize [A]:     3.160        3.29      3.86      3.57
    # of linkedlist cell (NB):     4     3     3
              lcsize [A] (NB):      3.29      3.86      3.57
     MAXNEIGHBS, MAXNEIGHBS10:    30   700
            NMINCELL, NBUFFER:     3    30000
    FFPath, DataDir, ParmPath:      ffield          DAT      rxmd.in
          # of atoms per type:          24 - 1          48 - 2          48 - 3          48 - 4
----------------------------------------------------------------
nstep  TE  PE  KE: 1-Ebond 2-(Elnpr,Eover,Eunder) 3-(Eval,Epen,Ecoa) 4-(Etors,Econj) 5-Ehbond 6-(Evdw,EClmb,Echarge)
        0 -9.82464E+01 -9.82464E+01  0.00000E+00 -1.369E+02  1.287E+00 -1.362E+00  5.208E-01 -1.398E-03  3.821E+01     0.00    0.00    0.00  41    0.36    0.23
       10 -9.82465E+01 -9.82467E+01  2.32025E-04 -1.369E+02  1.290E+00 -1.364E+00  5.214E-01 -1.397E-03  3.821E+01     0.08    0.00   -0.00  32    0.36    0.27
       20 -9.82466E+01 -9.82471E+01  4.80178E-04 -1.369E+02  1.287E+00 -1.366E+00  5.202E-01 -1.408E-03  3.821E+01     0.16    0.00   -0.00   4    0.36    0.25

...

       total (sec):       2.9980         2.9980
----------------------------------------------
    rxmd successfully finished

4. License

This project is licensed under the GPL v3.0 license - see the LICENSE.md file for details

5. Selected Publications