## page was renamed from AJMGrpOnly/teaching/electronic-structure/getting-started
## page was renamed from ajm/teaching/electronic-structure/getting-started

<<TableOfContents()>>

= Getting started with NWChem =

== First things : setting up your machine ==

{{{#!wiki  important
Important

You may have done some of these steps before. If so, skip to the ones you have not done...
}}}

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):

[[attachment: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
}}}

{{{#!wiki  important
Important

''' Defining your scracth directory'''

Make a scratch directory in your HOME directory:
  $ cd
  $ mkdir scratch
  
'''Note''': This applies only to those of you with accounts on comanche:
If you have an '''ESM''' account (it will be of the form ''esm_xxxx_x'') then you need to define the '''SCRATCH''' variable differently:
  export SCRATCH=/scratch/HDD_2T/esm/${USER}
Put the above in your .bashrc file.
}}}

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
}}}

{{{#!wiki  warning
Warning

For this to work you will need to have the ''H2O_HF.nw'' file present. We will see how to create an NWChem command file below. For now, read on and be patient.
}}}
  
{{{#!wiki  important
Important

'''What are the ''>&'' and ''&'' for?'''

On a Linux/Unix system, we will often run commands using
  code < IN.file >& OUT.file &
Here's what is all means:
  * ''code'': This is the name of the executable.
  * ''< IN.file'': This says pass the contents of the file IN.file to the executable. Sometimes it is not needed. We do not use this for NWChem.
  * ''>& OUT.file'': The ''>'' says send the output to the file OUT.file. Sometimes things go wrong and we get an error message. To send this error message to the output file too we use ''>&''. 
  * ''&'': Finally, we often end a command with a terminal ''&''. This tells the system to run the process in the background. 
}}}
  

== 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 ==

{{{#!wiki  important
Important

This doe not apply to MPI jobs!
}}}

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 [[http://www.nwchem-sw.org/index.php/Main_Page|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. 
{{{#!wiki  important
Important

What is the g.s. energy of the H-atom in atomic units (a.u. or Hartree)?
}}}

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

[[attachment: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''

[[attachment: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.

{{{#!wiki  important
Important

'''Clean-up'''
NWChem will create files you will usually not need. In the above example all you need to retain at the *.nw and *.out files. The rest can be deleted. So, from the files created:
  h-sto3g.db  h-sto3g.movecs  h-sto3g.nw  h-sto3g.out
we remove the first two.
}}}

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.

{{{#!wiki  important
Important

What is '''SCF'''?

We will discuss this in the lectures, but SCF stands for //self-consistent field//. In short, the Hartree--Fock equations need to be solved self-consistently as in this model, the Hamiltonian depends on the solution, so we make a guess for the solution, construct the Hamiltonian (called the Fock operator), solve it, get a new solution, from this calculate a new Fock operator, and so on till we achieve convergence. 
}}}  

{{{#!wiki  important
Important

Question:

Next use a larger basis: ''aug-cc-pVTZ''. what does this basis look like? Have a look at [[https://bse.pnl.gov/bse/portal|the basis set site and search for this basis.]] 

Copy the above file to h-avtz.nw. Do this using the command
  $ cp h-sto3g.nw h-avtz.nw
Do not type '$': the dollar symbol is the sign for the Linux prompt.

Now edit the file using pico or vim:
  $ pico h-avtz.nw
Find and replace 'STO-3G' with 'aug-cc-pVTZ'. Save the file.

Now run NWChem on this file:
  $ mpirun.mpich -np 1 nwchem h-avtz.nw >& h-avtz.out
Have a look at the output. What is the final Hartree-Fock energy? How does it compare with that you obtained using the much smaller STO-3G basis. 

Locate the basis set in the output file. How large is it?
}}}

=== Water ===
{{{#!wiki  important
Important

When you have done the above question successfully, perform the following calculations. 
  * Save these input files.
  * Run them.
  * Look at the outputs.
  * Get a feel for the kind of things NWChem writes in the output files.
}}}

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

[[attachment: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.

[[attachment: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.

[[attachment: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                 
}}}