ADF

Introduction

Amsterdam Density Functional (ADF), now called Software for Chemistry & Materials (SCM) https://www.scm.com/, has become a popular computational chemistry software package used in the industrial and academic research. It is an accurate, parallelized, powerful computational chemistry program to understand and predict chemical structure and reactivity with density functional theory. Heavy elements and transition metals are accurately modeled with ADF's reliable relativistic ZORA approach and all-electron basis sets for the whole periodic table (H-Uuo). A vast range of spectroscopic properties and comprehensive analysis tools yield invaluable insight in chemical structure and reactivity. DFT calculations are easily prepared and analyzed with our GUI.The ADF Modeling Suite has a GUI which contains several modules: BAND is available to study bulk crystals, polymers, nanotubes and surfaces; a Stewart's semi-empirical MOPAC code; a Quantum ESPRESSO plane wave code; a density-functional based tight binding (DFTB) module for modeling molecules; a reactive force field module ReaxFF for molecular dynamics; and an implementation of Klamt's COSMO-RS method.

Particularly in mendoza-cortes group, ADF.2016 is used mainly for ReaxFF molecular dynamics simulations.

For new users is highly recommendable to read -and play with- the GUI overview tutorials in order to explore the software; here the link: https://www.scm.com/doc/Tutorials/GUI_overview/GUI_overview_tutorials.html

The section "The first examples" is about how the input file and submission scripts look when ADF was installed for the first time. Now a graphic user interface (GUI) help to write the input file as well as the submission script (SLURM).

The second section is written for new users in ADF. This section give some information and useful tips that come from the experience in how to use ReaxFF module for molecular dynamics of periodic structures.

The first examples.

Input example

The input data file HCN_4P.inp is

Title HCN Linear Transit, first part

NoPrint SFO, Frag, Functions, Computation

Atoms Internal

1 C 0 0 0 0 0 0

2 N 1 0 0 1.3 0 0

3 H 1 2 0 1.0 th 0

End

Basis

Type DZP

End

Symmetry NOSYM

Integration 6.0 6.0

Geometry

Branch Old

LinearTransit 10

Iterations 30 4

Converge Grad=3e-2, Rad=3e-2, Angle=2

END

Geovar

th 180 0

End

End Input

Submission script example

The following is a simple example SLURM job submission script (asking for 3 cores):

#Change JOBNAME variable by the name of your job

#Rememer to use NSCM equal to the number of task (export NSCM=$SLURM_NTASKS) otherwise your job will run in serial*

#!/bin/bash

#SBATCH -J JOBNAME

#SBATCH -n 3

#SBATCH -N 1

#SBATCH -o test-%J.o

#SBATCH -e test-%J.e

#SBATCH -p mendoza_q

#SBATCH --mail-type=ALL

#SBATCH -t 500:00:00

cd $SLURM_SUBMIT_DIR

export JOB=JOBNAME

module purge

module load adf

#export NSCM=3 # Where ncpus and NSCM must be equal.

export NSCM=$SLURM_NTASKS #This is a shortcut to define automatically NSCM=number of tasks

echo $NSCM

which adf

mkdir -p ${SCM_TMPDIR}/${JOB}

export SCM_TMPDIR=${SCM_TMPDIR}/${JOB}

adf -n 3 < ${JOB}.inp > ${JOB}.out

Remember to check if you are using the default temporary directory. In other words check your .bashrc file (vi ~/.bashrc).

#export SCM_TMPDIR='/panfs/storage.local/engineering/mendozagroup/scratch/adf/${USER}/2016'

*"NSCM" the simplest form of the mpirun command is used for single-node jobs when the calculation is performed on the localhost. In this case the NSCM environment variable determines how many parallel processes will be started. Please note that if “$NSCM” is not equal to “1” (digit one) then the exact value of the NSCM variable has no effect when the job is started under any of the batch systems or with a hostfile. In this case the number of parallel processes to start is determined by the contents of the hostfile.

Submission script example for ADF using GPU/CPU combinationl.

#!/bin/bash

#SBATCH -J JOBNAME

#SBATCH -n 8

#SBATCH -N 1

#SBATCH -o test-%J.o

#SBATCH -e test-%J.e

#SBATCH -p gpu_q

#SBATCH --mail-type=ALL

#SBATCH -t 500:00:00

#SBATCH --gres=gpu:2 #To reserve a node with 2 free GPUs

cd $SLURM_SUBMIT_DIR

export JOB=JOBNAME

module purge

#module load adf2016/adfcuda #adfcuda should the executable that has CUDA built-in.

module load cuda/5.5

module load adf_gpu/2016.01

export NSCM=$SLURM_NTASKS #This is a shortcut to define automatically NSCM=number of tasks

echo $NSCM

which adf

mkdir -p ${SCM_TMPDIR}/${JOB}

export SCM_TMPDIR=${SCM_TMPDIR}/${JOB}

adf -n 8 < ${JOB}.inp > ${JOB}.out

In the ADF input file you need to enable GPU support :

GPUENABLED

SETVALIDDEVS 0,1

END

ReaxFF module for beginners.

by Carlos I. Aguirre-Velez

Building models

Open a terminal and type adfjobs &, and a window will appear (I'll call this window as “first window”) where the jobs that are summited, waiting for resources or running are recorded. Click on the logo of ADF in the extreme left of top menu and select New Input, then a window will pop up. The new window is a work area where you find a dark window on the left side (where visualize the models) and on the right , there is an area with command fields which you can select for the different options according with your job. In the top of each work area there is a menu. The ADF input module should start as default, then click on it and select ReaxFF, this change the command window.

Firstly a periodic system must be drawn, it can be made manually using the ADF GUI tools or be made using other software, for example Materials Studio. You can use several molecular and periodic crystal structures from predetermined data base of ADF.

You can access to data base clicking on the magnifying glass icon on the extreme right side of the command menu. A field of search will appear, write the name – or a part of the name - of the compound or crystal structure that you are looking for. Let's say for example a perovskite. Several structures will be shown, select one -for example BaTiO3- then in the dark window a unit cell will be drawn.

You can build a slab from this unit cell. Go to Edit → Crystal → Generate Super Cell... A dialog window with a matrix of 9 spaces will pop up, you can choose different enter numbers in the diagonal; for example if you take 5, 5, 2 and click OK, a slab of 5 x 5 x 2 unit cell will be generated.

You can save the structure for working with later, then go to File → Export coordinates. The coordinates will be saved in .xyz format. If you open this file, at the end of all values, three rows begin with VEC will be written, that indicate dimensions of the cell. If you delete these last three rows in the file, the simulation will run inside a default cell without periodic conditions.

For getting the structures go to File → Import coordinates and the structure will be drawn in wireframe view, if you want change the view go to left side menu View → Molecule → Balls and sticks. It is possible to zoom in or zoom out in the structures with the mouse middle bottom. You can change of point of view for a better visualization clicking on the structure, mouse right bottom change angle of view and mouse left bottom move the structure.

ADF can read several kind of data, but the structures in CIF file format are more useful to work with. Then if you have a structure in this kind of format just go to File → Import coordinates, select the file and build the super cell.

You can add or delete atoms to the structure. Continue with the perovskite example: import file, change of view to balls and sticks and select in the bottom menu (where there are a little triangle, the letters C O N H Cl X and other symbols) the X menu, then the periodic table appear, select the atom that you want to add (for example lithium). Go to structure, put the cursor in the place where the atom should be add and click, an atom will be drawn which will have an “elastic link” that indicates that you can continue forming a molecule, but in this case, if you just need a single atom, make double click on the atom and the elastic linker will disappear. You can repeat this process for single atoms also you can delete the atoms for generating structure with defects, just select the atom and delete it by keyboard.

You can combine different structures. Import a structure, once it is open, import a second structure and it will appear in the same window, by the mouse right bottom move the second structure to the place that you need it. When you select one part of the structure, it changes to dark green color, that indicates that you can move it. You can change the plane of view (XY, YZ, XZ), go to left menu View → View direction → Along X-axis. This view is useful to align structures in reference to determined plane.

At his moment just you have coordinates, now it is necessary to give the conditions for the simulation.

Setting parameters for molecular dynamics

In ReaxFF menu there are three sub-menus that are aligned (Main, Model, Details). Here just the common commands will be commented.

In Main menu the first field is Task, there are four kind of tasks; I just used Molecular Dynamics task.

The second row is for selecting the reactive force field (ReaxFF). A ReaxFF is a sample of parameters that model the interactions among atoms according with the model of reactive atom (atoms with bonds capable to break down and form other bonds with other atoms). Usually each kind of force field just works for specific systems and most of them don't have transferability to other systems.

You can click on folder icon and automatically ADF gives the force field options according with the atoms in the structure. If you don't sure which force field could be more suitable for your job, click on i icon in the extreme left of the force field row, and documentation for the different available force fields will be displayed.

Warning: It is possible that your system have specific kind of atoms and you select a force field with the atoms defined in the documentation, but when you try to save the job, an error message appear because one atom is missing or because in that force field there are interactions not defined. One limitation of ReaxFF is the lack of transferability among the parameters of force fields, you can not just copy-paste the information from different force fields to build a new one. If there is not a suitable force field for your project, you can not use ReaxFF module in ADF.

Once that you can use a suitable force field for your job, the next important information is the number of iterations and time step. The time step is measured in femto seconds (fs), total simulation time will be the number iterations multiply by the time steps. By default values are 40,000 and 0.25 fs, this represent just 10 pico second. Usually simulations should be around 1 ns then, the number on these fields must be adjusted in order to reach 1 ns; for example, you can put 1 fs and 1,000,000 iterations if the system runs well, no problem, but if it doesn't work, the values must be modified.

The next information is about Method. The options are: NVE, VPT, velocity Verlet + Berendsen. Choose one. The temperature by default is 298 K, and pressure 0.0 MPa; you can change the pressure to one atmosphere, remember 1 atm is equal to 0.101 MPa.

The next menu is Model. There are several options, but I'll just comment two of them: Geometry Restraints and Lattice. In Geometry Restraints you can freeze some part of the structure and let other atoms free to move. For using this option, just SHIFT + mouse left bottom, drag the window to select the area and click in + icon. In Lattice you can check the size of cell, mainly for increase vacuum space in the z-axis, here you just type the amount.

Finally in Details → Restart, it is possible to modify the number in which the information is saved in one running; the default number is 2000, it means that if a job has 40,000 iterations, just 20 frames of the trajectory will be saved using this default value.

Your model is build and parameters are given, but there are some details to be taking into account.

Regularly when you build a structure or import coordinates, that values are positive and negative. You must move all the structure to positive space in order that all coordinates have positive numbers. Go to Edit → Crystal → Map Atoms to Cell, ADF calculate the new coordinates; this process takes time which depends of the number of atoms in a structure, for an structure around 14,000 atoms the process to move all coordinates takes approximately 15 minutes. You can check if your structure is in the positive space viewing it respected to the axes. Go to View → Periodic → Show Lattice Vectors and visualize both axis and structure. This action is very important because, if you don't move the structure, it collapses during the first steps in the running.

When you save your input file, ADF generates three input files and several output file when job finish successfully, all these files must be in the same directory. Then go File → Save As , in the window “Save as” open a new folder (folder with a little star) with the name of your job.

Submitting jobs

Before submit a job to RCC you must be sure that the workstation where you are working can connect to RCC without asking login and password.

Go to this link https://www.scm.com/doc/Installation/Installation.html and read the Configure ADFjobs queues and 3rd party software (optional) section.

To manage remote jobs, you need automatic authentication with an ssh-agent via an ssh key pair. This is most easily set up on MacOS or Linux, but is a bit more involved for Windows. If you don’t have an ssh key pair already, you can generate one in a terminal: ssh-keygen -t rsa Put your pass-word protected public key on the compute cluster(s) in ~/.ssh/authorized_keys. Next, you should establish a connection via an ssh-agent. On MacOS an ssh-agent runs by default, and with keychain you just have to type your password once when you make the first connection.

You can test the ssh key works just typing a ssh command to connect the RCC. If it works you can configure your own SLURM.

How do write the SLURM to submit a job in a queue system using ADF GUI? When you save your job, the correspond input files are generated and the name of your job is displayed in the first window. Mendoza-Cortes group can use different partitions in RCC, the first one is mendoza_q, but engineering_q and engineering_long are available; also you can run ADF jobs in the local workstations.

Go to top menu in the first window and click on Queue menu, then several options of actions and SLURM's will be displayed. You can go Queue → Edit → SLURM, a window will pop up with the indications of that SLURM: host, user, partition, nodes, job directory, run commands, etc. Each SLURM option have the same format and they are different just in number of nodes for running a job and partition used. As a new user, in order to use the different options of SLURM in Queue menu, you must edited the remote user field in each SLURM according with your user name registered previously in RCC.

It is possible set up a default option, (the current default option is SLURM4, it means 4 nodes on mendoza_q) or explicitly other option. Highlight the job, go to Queue menu and select the option. If you select Sequential, the job will run in the local workstation. Although it is possible running ADF jobs in 16 nodes (SLURM16) in RCC, you can not save much time. A kind way to share resources with other partners for this kind of jobs is using just four.

Once that your job has been displayed in the fist window, you can submit it for running. Go to Job → Run. If you don't select a different queue, ADF GUI takes the default option. The queue system can wait for resources, this status is indicated by a magnifier glass at extreme right of the row. If the job immediately runs, a little engine will be displayed and two rows with numbers are displayed while the job is running. When a job finishes well, a filled circle will indicated it. If the job abort, a prohibition sign will be displayed.

If you click in the job while is running or if the job has finished, all the files generated are displayed.

Useful tips

The next section is about my experience with this software. You are free to explore or to try different alternatives, but some details due to bugs are not easy to find, and for this reason the tips are in some sense warnings.

How do you check if the job is running well at the beginning of the simulation? You don't need to wait until the job finish to see if the job begun well. When a job is running, in the first window, you can see two rows of number that are changing. The most important parameter for checking the beginning of one simulations is temperature, pay attention in the corresponding column. If your job run initially at 298 K, the temperature can increase until 3000 or 4000 K in the first iterations, but after that the temperature should decreases to values near to the initial one. If at the beginning the temperature reaches to million, the structure collapsed. You can see check it by the movie.

You build the structure o import the coordinates, make the supercell, move the structure to positive space, select the parameter for the simulations, save the job, all it is right but the structure in the first steps of running, the job crash. You can checking several times the job and don't find the error. I found a bug in the lattice options. Go to right menu in Model → Lattice, change the parameter of z-coordinate of the cell and save the job with a dump name, after that put the right value of z-coordinate of the cell and save the job with its right name. And it works!

It has been mentioned that a molecular dynamics simulations should be at least during a one nano second. I tried a time step of 1 fs but it didn't work then I used 0.5 fs, probably for my system 1 fs step was so long. You can try with different time steps and iterations in order to reach the 1 ns. Take into account the computational cost.

The size of a periodic structure should be at least of 50 Å in each direction, a little size of structure will have problems due to periodic conditions of the simulation.

The output files are related to the algorithm of ReaFF proposed by van Duin, the files with extension .rxkf and .rxxmol are the most heavy files, they are written in binary for display the movie. If you are not interested in the movie, please delete at least these files because they occupy a lot space and it is a critical situations mainly in RCC.

About the movies of a molecular dynamic simulation. For viewing the movie go to the first window, highlight the job that you want to watch, click on the logo of ADF (SCM) and then Movie. A new window will pop up and the movie will be running, you can control the display with the controls and change the view with the cursor or by View menu. In principle, you can save the movie File → Save Movie, or File → Save ADF Movie (xyz) but a bug don't let save directly in both cases. The only way that I could make a movie was using Files → Save frames, several snapshots are saved and after that, with a video editor, you can make the movie; I have used Kdenlive.

I made molecular dynamics simulations because I was interested in diffusion coefficient of graphene systems. Each running for the same structure will have different behavior. For this reason, it is convenient taking the same system and run it at least five times in order to have a mean behavior. It suppose that you can analyze the trajectory by a library called TRAVIS that can be downloaded, however, for the version ADF.2016 is not available. You can export the trajectory for GROMACS format (but I didn't try). For this reason I used a homemade script written in bash (smd100.sh) to analyze the trajectories and calculate the Mean Squared Deviation (MSD) for diffusion coefficient using the molsav output files and other codes written in python.

You can ask for helping through Support SCM by e-mail to support@scm.com

Any comments or questions, be free to write c.aguirre.velez@gmail.com