Getting started with NWChem

First things : setting up your machine

On your first login you will need to change your password using the

passwd command:

  $ passwd <enter>

and follow the instructions.

Next, set up a few environment variables and commands. Linux allows you to customize your shell using commands/definitions placed in the .bashrc (it starts with a '.' - this type of file is usually hidden from view) and, sometimes, the .bash_profile file. Both of these are located in your $HOME'' directory. ''$HOME is itself an environment variable that contains the location of your home directory:

  $ echo $HOME
  /home/alston

That's my home directory. The echo command echos to the contents of the environment variable (all these begin with a $ and contain uppercase letters only! $ echo $home will not work. Try it!) to the screen.

Another useful variable is $USER. Figure out what it contains.

We need to define a few more commands/variables as follows: First go to your $HOME directory:

  $ cd              <--- 'cd' without an argument will take us home.
  $ vi .bashrc      <--- or use emacs. Try not to use pico!

Now edit the .bashrc file to include the following (do not erase anything that might already exist in the file):

bashrc_fragment

# your .bashrc file will contain commands. Add these to the end of the file.
#
# User commands

AJMHOME=/home/apw185

#NWChem
export NWCHEM_TOP=${HOME}/NWChem/nwchem-6.6/
export NWCHEM_TARGET=LINUX64
export NWCHEM_INSTALL=${AJMHOME}/install/nwchem-6.6
export NWCHEM_BASIS_LIBRARY=${NWCHEM_INSTALL}/data/libraries/


# Define the system PATH:
export PATH=${AJMHOME}/bin:${AJMHOME}/install/bin/:${NWCHEM_INSTALL}/bin/:${PATH}

# Make a scratch directory in your home dir:
export SCRATCH=${HOME}/scratch/

# Other commands:
export QUEUE='batch'
export CORES=4
export OMP_NUM_THREADS=1

Once all these commands are in the .bashrc file you need to either log out and log back on (this file is executed only on login) or force execution using

  $ source .bashrc

Check if this has worked using the <TAB> auto-completion. This is cool. You type in the first few letters of the command you want and hit <TAB> which then attempts to complete the command for you. So if nwchem is now correctly on our $PATH then

  $ nw<TAB>

should result in

  $ nwchem

If not, then something is wrong. Either the $PATH is not correctly defined or the binary file nwchem is not where it is.

To see where commands are located (where the files actually reside) use

  $ which nwchem
  /home/apw185/install/nwchem-6.6/bin//nwchem

The which command tells you which binary you are using and where it is.

Running NWChem

First, make sure the NWChem environment variables are defined in your .bashrc file. Note that the commands you may have recently introduced in the .bashrc file may not be available. This file is executed only on login. To force the shell to execute the commands in this file use

  $ source .bashrc

Our NWChem code has been compiled using the MPICH2 version of the message passing interface (MPI). This library allows the program to run in parallel on many processors. To run the MPI code the usual usage is:

  mpirun.mpich -np <num_proc> nwchem input.nw >& output.out

Here, <num_proc> is the number of processors, input.nw is the file containing the NWChem commands and output.out is the output file.

We will normally use only one processor and label our input and output files to reflect the type of calculation being performed. For example, for a calculation of the Hartree-Fock energy of water we might use file names with H2O_HF as a prefix: }}}

  mpirun.mpich -np 1 nwchem H2O_HF.nw >& H2O_HF.out

Monitoring

To see what's going on use the top command:

  $ top

This will give you a screen with the most significant processes, usually ranked by CPU usage. See if your job is included. It will be difficult to see this if there are a lot of NWChem jobs running as all will have the same name, i.e., nwchem. The thing to look for is the JOB_ID.

One way of obtaining your job ID is to use the process command ps. For example, I would use the following

  $ ps -ef | grep 'alston'

There are two commands here. The first is ps -ef which on its own results in way too much information. All I need are the processes associated with me, i.e. user alston. To view only these I have *piped* the output of ps -ef into a search command grep alston which prints out only processes that have the word 'alston' in them, like so

  $ ps -ef | grep 'alston'
  501   584   211   0  2:53pm ??         0:13.10 /Users/alston/Downloads/SparkleShare.app/Contents/MacOS/SparkleShare -psn_0_147492
    0   252   225   0  2:52pm ttys000    0:00.02 login -pfq alston /bin/bash
    0   256   225   0  2:52pm ttys001    0:00.01 login -pfq alston /bin/bash
    0   260   225   0  2:52pm ttys002    0:00.02 login -pfq alston /bin/bash
    0  2820   225   0  8:59am ttys003    0:00.02 login -pfq alston /bin/bash
  501  2826  2821   0  9:00am ttys003    0:00.00 grep alston

The pipe command is |. You could use many pipes. For example, to search for NWChem jobs I have initiated I would use:

  $ ps -ef | grep 'alston' | grep 'nwchem'

Once you have found your JOB_ID using, you can now locate it in the output of top and make sure it is running (remember that short jobs could finish before you have a chance to type all these commands).

Stopping and killing a job

Sometimes you've made a mistake and need to stop a job, or kill it, or perhaps you've forgotten to put it in the background and would like to do so. I you have the JOB_ID, then you could do the following:

• Kill the job:

    $ kill JOB_ID
  This will send a kill signal to the JOB_ID and terminate it.
  Use ''top'' to monitor the progress of the *kill* command.
  * To kill all 'nwchem' jobs you have initiated:
    $ killall nwchem
  Use with caution as this will kill all your 'nwchem' jobs.
  * Stop a job:
    $ kill -STOP JOB_ID
  This will stop the job. You can re-start it using
    $ kill -CONT JOB_ID

If you've forgotten to run a job in the background and wish to logoff and go for a coffee you could do the following:

  $ nwchem  IN_FILE > OUT_FILE

Opps, forgot the &. You won't be given a $ prompt till this job finishes. But you can stop it using

  <Control-z>

This will result in

  [1]+  Stopped       nwchem
  $

Now you've got the prompt back and can re-start the job in the background using

  $ bg <enter>
  $ [1]+ nwchem &

And check to see if it is running using top.

NWChem Jobs

Now let's see how to run some simple jobs with NWChem. If you'd like to see what these commands mean, have a look at the NWChem manual which can be found under the Documentation tab on the main NWChem page.

Hydrogen Atom

Let's start with the hydrogen atom as you already know what the correct ground-state energy of this system should be.

First we use a small basis. This one is a STO-3G basis and looks like this:

H-sto3g-basis

BASIS "ao basis" PRINT
#BASIS SET: (3s) -> [1s]
H    S
      3.42525091             0.15432897       
      0.62391373             0.53532814       
      0.16885540             0.44463454       
END

It consists of one basis function only. This function, in turn, is a linear combination of 3 s-type Gaussians. In mathematical form this basis function would look like (using $x$ rather than $\bf{r}$): $$ \phi(x) = 0.15432897 \exp{(-3.42525091 x^{2)} + 0.53532814 \exp{(-0.62391373 x}2)} + 0.44463454 \exp{(-0.16885540 x^2)}. $$ Plot this function in Gnuplot and compare it with the $1s$ hydrogenic wavefunction.

Here are the NWChem commands to find the energy of the H-atom in this basis. Put this in file called h-sto3g.nw

h-sto3g.nw

Memory 500 mb

charge 0
Geometry units bohr
  H     0.0  0.0  0.0 
End

Basis "ao basis" spherical
  H  library  STO-3G
End

Title "H STO-3G "

SCF
  UHF
  Doublet
End

Task SCF energy

To run this job use

  mpirun.mpich -np 1 nwchem h-sto3g.nw >& h-sto3g.out

This job will finish very quickly (a second). Have a look at the output in file h-sto3g.out. Find the total SCF energy (search for the string "Total SCF energy"). Is it what you expected? it should have been $-0.5$ a.u., but it will be something like $-0.46$ a.u. This is because of the basis set. We used a fairly small basis set and this means we will never get a good enough answer. To improve matters we can increase the basis set size. This is described in the next task.

But first, let's dissect this command file:

• Memory 500 mb : this sets the memory we have allocated to NWChem in megabytes. For a larger job give it more memory.

• charge 0: the system is neutral. This is the default. If you wish, try a calculation with charge $+1$ and one with charge $-1$. What do you get for the energy?

• Geometry...End: Here is where we have defined the molecular (atomic) geometry.

• Basis...End: Then we define the basis set. The first line is usually exactly what I have used in this example. The second line H library STO-3G is where we specify that the hydrogen atoms in the system will use the STO-3G basis set from the NWChem library.

• Title allows us to set a title for this job. This is optional, but is good practice.

• SCF..End is where we define settings for the energy calculation. Here we have used the unrestricted Hartree--Fock (UHF) method and have stated that this is a system with doublet spin multiplicity. Why? Because hydrogen has only one electron so it has $s_z = 1/2$, so multplicity is $2s_z+1 = 2$, i.e., it is a doublet state. For closed-shell systems (rare gases, H$_2$O, etc.) $s_z = 0$, so the multiplicity is $1$ and we then specify Singlet.

• Task SCF Energy tells NWChem to perform a task. This task is to compute the SCF energy for the system.

Water

Here's a simple energy calculation with the STO-3G basis set:

h2o-sto3g.nw

Memory 500 mb

charge 0
Geometry units bohr
  O     0.0000000000    0.0000000000    0.0000000000
  H1   -1.4536519600    0.0000000000   -1.1216873200
  H2    1.4536519600    0.0000000000   -1.1216873200
End

Basis "ao basis" spherical
  H  library  STO-3G
  O  library  STO-3G
End

Title "H2O STO-3G "

scf
  Singlet
end

task scf energy

Let's try an optimization using the same basis set. Here the positions of the atoms will be changed till the energy of the system is a minimum.

h2o-sto3g-opt.nw

Memory 500 mb

charge 0
Geometry units bohr
  O     0.0000000000    0.0000000000    0.0000000000
  H1   -1.4536519600    0.0000000000   -1.1216873200
  H2    1.4536519600    0.0000000000   -1.1216873200
End

Basis "ao basis" spherical
  H  library  STO-3G
  O  library  STO-3G
End

Title "H2O STO-3G Geometry Optimization"

scf
  Singlet
end

task scf optimize

And here's a properties calculation. Here you will calculate the dipole moment and quadrupole moment of the water molecule.

h2o-sto3g-moments.nw

Memory 500 mb

charge 0
Geometry units bohr
  O     0.0000000000    0.0000000000    0.0000000000
  H1   -1.4536519600    0.0000000000   -1.1216873200
  H2    1.4536519600    0.0000000000   -1.1216873200
End

Basis "ao basis" spherical
  H  library  STO-3G
  O  library  STO-3G
End

Title "H2O STO-3G Multipoles "

scf
  Singlet
end
property
  dipole
  quadrupole
end

task scf property