HowTo:adf

ADF

This is a short help file on how to use the computational Quantum Chemistry code "ADF" on our clusters. We require all users of this software to sign a statement. The software can only be accessed by persons who belong to a specific Unix group. See details below.

Features

ADF stands for "Amsterdam Density Functional" and denotes a package of programs that uses Density Functional Theory (DFT) for electronic and molecular structure calculations. The package is geared towards chemists and physicists with an interest in the structure of molecules and solids.

The ADF package consists of two main components:

• ADF for molecular calculations
• BAND for calculations on solids

Unlike most other molecular/solid/electronic structure codes, ADF employs "Slater-type" basis sets, ie, functions that have an exponential behaviour, which are more suitable for the description of chemical systems than the more commonly employed "Gaussian type" ones. The downside of this are computational difficulties that may be circumvented by numerical integration. Since DFT depends largely on numerical integration anyhow, the "Slater approach" is particularly well-suited for DFT code.

ADF is arguably the best DFT code available at this time for transition metal compounds and solids.

ADF handles geometry optimizations, transition states, reaction paths, and infrared frequencies. It allows the calculation of a variety of properties, ranging from UV spectra (requiring the treatment of excited states) to NMR chemical shifts and spin-spin couplings (where the use of Slater-type bases is of great use). The BAND code can be used for calculations on polymers, surfaces and bulk solids.

Location of the program and setup

The present version of ADF is 2016.101. The programs in the ADF package reside in /opt/adf. To use ADF on our machines, it is required that you read our licensing agreement and sign a statement. You will then be made a member of a Unix group adf, which enables you to run the software.

ADF requires the sourcing of a setup script to function properly:

source /opt/adf/adf2016.101/adfrc.sh

This script sets environment variables that are necessary for proper program execution and are used for the system to find executables and data files such as basis sets. Among others, SCMLICENSE is used by the license manager of the program to find a machine specific license file.

The above settings is best applied through a call to usepackage on our system. Issuing the command

use adf

will take care of this, as well as including the $ADFBIN directory in the $PATH. This command may also be placed into a login shell setup file (.bash_profile).

Scratch files

One of the settings is the environment variable SCM_TMPDIR which is required to redirect the temporary files that ADF uses to the proper scratch space, presently

/scratch/hpcXXXX

where hpcXXXX stands for your username. If for some reason ADF does not terminate normally (e.g. a job gets cancelled), it leaves behind large scratch files which you may have to delete manually. To check if such files exist, type

ls -lt /scratch/hpcXXXX

Usually the scratch files are in sub-directories that start with kid_. Once you have determined that the scratch files are no longer needed (because the program that used them is not running any more), you can delete them by typing

rm -r /scratch/hpcXXXX/kid_*

Cleaning up the scratch space is the user's responsibility. If it is not done regularly, it can cause jobs to terminate, and much work to be lost.

Running ADF from a command line

The following instructions assume that you are a member of the Unix group "adf". The instructions in this section are only useful if you need to run test jobs of a short duration. If you want to run a production job, please refer to to instructions on how to start a ADF batch job.

Once program usage is set up through the "use" command, the program(s) can be run:

adf <in >out 

Instructions about the job are read from standard input, which has been redirected from a file in in the above command lines. Commonly an input file will be constructed to specify what calculation is to be run. The output of the program(s) goes to "standard output" and has been redirected to an output file out above. Note that the output of these programs is commonly thousands of lines long and should therefore be redirected in any case.

The construction of a proper input file for ADF is an involved process, and is outside the scope of this help file. Detailed instructions can be found in the ADF User's Guide, which should be studied before the program can be used properly. As an initial hint, here is a sample input file:

title benzene BP/SZ bondorders tol=0.05

define
 cc=1.38476576
 ccc=120.0
 dih=0.0
 hc=1.07212846
 hcc= 120.0
 dih2=180.0
end

atoms Z-matrix
 C  0 0 0
 C  1 0 0  cc
 C  2 1 0  cc ccc
 C  3 2 1  cc ccc dih
 C  4 3 2  cc ccc dih
 C  5 4 3  cc ccc dih
 H  2 1 3  hc hcc dih2
 H  3 2 4  hc hcc dih2
 H  4 3 5  hc hcc dih2
 H  5 4 3  hc hcc dih2
 H  6 5 4  hc hcc dih2
 H  1 2 3  hc hcc dih2
end

basis
 Type SZ
 Core None
end

symmetry NOSYM

xc
  gga becke perdew
end

bondorder tol=0.05 printall

noprint sfo

The input consists of several units, separated by blank lines, starting with a keyword, and ending with the statement END. For instance, the atoms in a molecules may be specified by issuing the keyword atoms, followed by one line with the atom name and "Z-matrix" relative coordinates for each atom, and closing with end (case insensitive).

Note: It is absolutely essential to have a good idea about the size and complexity of your calculations before you start a ADF job. Many of the methods have terrible scaling properties, i.e. the computational cost grows very quickly with the number of electrons, degrees of freedom, or number of basis functions used. We suggest you start with a small basis set and a cheap method, and then slowly increase those parameters.

Submitting (parallel) ADF jobs

If you want to run Gaussian on several processors on our machines, you have to include a line in your input file:

%nproc=8

where we assume that you want to use 8 processors (cores, threads).

It is mandatory to submit a Gaussian job script through our scheduling software (see our Scheduler Help File for details).

Here is a "bare bones" sample of a Gaussian submission script:

#! /bin/bash
#$ -S /bin/bash
#$ -q abaqus.q
#$ -l qname=abaqus.q
#$ -cwd
#$ -V
#$ -M hpcXXXX@localhost
#$ -m be
#$ -o STD.out
#$ -e STD.err
#$ -pe shm.pe 8
g09 < sample.g09 > sample.log

• The first 6 lines of the script make sure the right shell is used, the program executes on the correct cluster, and all necessary setup is done.
• An email address for notifications is specified in the #$ -M line. We suggest "hpcXXXX@localhost" (hpcXXXX stands for the username). Place a file .forward containing your actual email address into your home directory.
• The -o and -e lines are used to tell the system where to write "standard output" and "standard error", i.e. the screen output.
• The #$ -pe gaussian.pe 8 line specifies the number of processors the scheduler will allocate (8 in this example). It is crucial to choose the same number as specified in the %nrocs= line of the input file.

The script (let's call it g09.sh) is submitted by the qsub command:

qsub g09.sh

This must be done from the working directory, i.e. the directory that contains the input file and is supposed to contain the output. Also make sure that you have set up gaussian (use g09) before you submit a job.

Licensing

Gaussian is a licensed program. The license held by the Centre for Advanced Computing is limited to our computers at our main site. That means that any of our users can use the program on our machines (but nowhere else), whether they are located at Queen's or not.

We require users of Gaussian to sign a statement in which they state that they are informed about the terms of the license to be included in the Gaussian user group named "g98". Please fax the completed statement to (613) 533-2015 or scan/email to cac.admin@queensu.ca.

Where can I get more detailed information ?

• To learn the basics about Gaussian input and output, refer to the Gaussian 09 User's Reference.
• For templates, and to get many examples, check out /opt/gaussian/g09/bsd/examples.
• The Gaussian web page contains a lot of information.
• For hardcore computational chemists, there is the Gaussian IOPs Reference, useful if you want to tinker with default settings and internal parameters.
• These can be purchased from Gaussian Inc..
• Send to cac.help@queensu.ca. We're happy to help.