View source for HowTo:nwchem

= NWChem =

This is a short "Frequently Asked Questions" file on using the parallel electronic-structure code "NWChem" on systems at the Centre for Advanced Computing. This software uses MPI as a message-passing system and is (in principle) able to run on an arbitrary number of processors. Its ability to perform a very broad spectrum of molecular-structure calculations, ranging from CI to ab-initio molecular dynamics, makes it an interesting alternative to the standard electronic structure code Gaussian. 
{|  style="border-spacing: 8px;"
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#e1eaf1; border-radius:7px" | 
== Features ==

NWChem is an electronic-structure code that is suitable to perform complex calculations on molecular structure. It was specifically designed to perform well on high-performance parallel computers. The installation on the SunFire cluster of HPCVL employs the MPI message passing package for parallel execution.

NWChem allows, among others, the following calculations to be performed:
* Hartree-Fock (e.g. RHF, UHF, ROHF etc.)
* DFT including spin-orbit DFT, with many exchange and correlation functionals.
* Complete Active Space SCF (CAS-SCF)
* Coupled-Cluster (CCSD, CCSD+T, etc.)
* limited CI (eg, CISD) with perturbative corrections
* MP2 (2nd-order Mollar-Plesset Perturbation Theory)
* In general: single-point calculations, geometry optimizations, vibrational analysis.
* Static one-electron properties, densities, electrostatic potentials.
* ONIOM model for multi-level calculations on larger systems
* Relativistic corrections (Douglas-Kroll, Dyall-Dirac, spin-orbit)
* Ab-initio molecular dynamics (Carr-Parinello)
* Extended (solid-state) systems DFT
* Classical force-fields (Molecular Mechanics: AMBER, CHARMM, etc.)
For a more complete list, see the official NWChem homepage and click on "capabilities".

== Location of the program and setup ==

The NWChem program is located in the directory /opt/nwchem/bin. To access it, you have to use the usepackage command
<pre>use nwchem</pre>
which will set you up automatically.

== Scratch files ==

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

<pre>export GAUSS_SCRDIR=/scratch/hpcXXXX</pre>

where hpcXXXX stands for your username. If for some reason Gaussian 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

<pre>ls -lt /scratch/hpcXXXX</pre>

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

<pre>rm /scratch/hpcxxxx/Gau-*</pre> 

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.
|}
{|  style="border-spacing: 8px;"
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#f7f7f7; border-radius:7px" | 
== Running Gaussian from a command line==

To run Gaussian on our systems, you have to belong to a '''user group g98''' (it's called that for historical reason, but it applies to all versions of Gaussian). You need to read our license agreement and [http://www.hpcvl.org/sites/default/files/gaussian-statement.pdf signed a statement] to be included in this user group. Once you are, you can access the executables.

A computation is performed by preparing an input file and pipe it to standard input of the program '''g09'''. Standard output should be caught in a log-file. We suggest you use the '''extensions''' ''.g09 for input'' files and ''.log for results''.

Interactively, the command line to invoke Gaussian is thus:

<pre> g09 < test.g09 >test.gout </pre>

This will only work if you are a member of the g98 group and have set the environment correctly. Note that the '''interactive execution of Gaussian is only meant for test runs'''.

Gaussian input files are explained in the "User's Reference". It is impossible to give an outline here. Sample files can be found in 

<pre>/opt/gaussian/g09/bsd/logs</pre>

'''Note:''' It is absolutely essential to have a good idea about the size and complexity of your calculations before you start a Gaussian job. Many of the methods mentioned above 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) Gaussian jobs ==

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

<pre>%nproc=8</pre>

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 [[HowTo:Scheduler|Scheduler Help File]] for details). 

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

<pre>
#! /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
</pre>

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

<pre>qsub g09.sh</pre>

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.
|}
{|  style="border-spacing: 8px;"
| valign="top" width="50%" style="padding:1em; border:1px solid #aaaaaa; background-color:#e1eaf1; border-radius:7px" | 
== 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 [http://www.hpcvl.org/sites/default/files/gaussian-statement.pdf sign a statement] in which they state that they are informed about the [http://www.hpcvl.org/sites/default/files/g09-licence.pdf 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 [mailto:cac.admin@queensu.ca cac.admin@queensu.ca].

== Where can I get more detailed information ? ==

* To learn the basics about Gaussian input and output, refer to the [http://www.gaussian.com/g_tech/g_ur/g09help.htm Gaussian 09 User's Reference]. 
* For templates, and to get many examples, check out /opt/gaussian/g09/bsd/examples.
* The [http://www.gaussian.com Gaussian web page] contains a lot of information. 
* For hardcore computational chemists, there is the [http://www.gaussian.com/g_tech/g09iop.htm Gaussian IOPs Reference], useful if you want to tinker with default settings and internal parameters. 
* These [http://www.gaussian.com/g_prod/books.htm can be purchased from Gaussian Inc.].
* '''Send [mailto:cac.help@queensu.ca|email to cac.help@queensu.ca]'''. We're happy to help.
|}