Q-Chem 4 Installation Guide

(last edited on 08/03/2016, email support@q-chem.com for questions)


1. Q-Chem Runtime Environemnt Variables

QC
  Q-Chem top directory
QCAUX
  QCAUX is the environment variable pointing to the auxillary files required to run Q-Chem, which includes basis set specification, initial SAD guesss, integral computing driver and etc. It should be noted the Q-Chem license file qchem.license.dat is place in $QCAUX/license directory.
QCSCRATCH
 

Q-Chem uses QCSCRATCH directory to store the temperary files in the calculation, as well as the saved scratch directory if you use the '-save' option when invoking 'qchem'. In parallel environment QCSCRATCH must be a network shared directory, e.g., a mounted NFS drive. The path to QCSCRATCH should be the same on each node.

The specification of QCSCRATCH is always required. User is expected to overwrite this variable with his/her own scratch directory in shell startup file, or set it on command line before invoking 'qchem' command.

QCLOCALSCR
 

QCLOCALSCR is the scratch directory on the local disk of each node. When QCLOCALSCR is specified Q-Chem will use local disks to store temporary files.

Specification QCLOCALSCR only if it is needed. When specified it should be a directory different from QCSCRATCH, since QCSCRATCH is network mounted while QCLOCALSCR should be completely local.

2. Requirement for Parallel Execution

Passwordless ssh
 

Passwordless ssh/rsh between computing nodes is required by MPI to launch parallel processes. If you are using the 'remote license' passwordless ssh/rsh from computing nodes to server nodes must also be enabled.

Normally in a cluster environemnt the passwordless ssh between computing nodes is already configured.

Ephemeral ports
 

Q-Chem uses ephemeral port (also called dynamic ports) for cross node communication.

Normally no action is required. These ports should be open and accessible to applications by default. In case your firewall rule disables the access to ephemeral ports you need to ask administrators to change the firewall policy, allowing incoming and outgoing access to these ports on computing nodes.

QCMACHINEFILE
 

MPI uses machine file to specify the nodes on which the parallel processes will be launched. Q-Chem uses environment variable QCMACHINEFILE to point to the location of machine file.

Specify QCMACHINEFILE if you use a dynamically generated host file. By default QCMACHINFILE points to $QC/bin/mpi/machines, which is generated during installation.

3. Q-Chem Package Installation

a) download the universal installer below

wget http://www.q-chem.com/download/qcinstall/qcinstall.sh
chmod +x qcinstall.sh

b) run the installation and follow the onscreen instruction

./qcinstall.sh

c) after a successful installation you wait to receive your license file and save it as $QC/qcaux/license/qchem.license.dat

4. Q-Chem Package Update and Maintainance

a) to update the installed Q-Chem to the latest distribution, run

$QC/qcupdate.sh

e) to re-generate and sumit license data, run

$QC/qcinstall.sh --update-lic

5. Running Q-Chem Calculations

a) setup Q-Chem runtime environment variables (QC,QCAUX,QCMPI and etc.)

[tcsh/csh]
source $QC/qcenv.csh (in Csh and Tcsh)
[bash]
. $QC/qcenv.sh (in Bash)
[specify scratch directory if not set in your shell startup script]
setenv QCSCRATCH /path_to_your_scratch_directory

b) for parallel run using dynamic node file, specify QCMACHINELIST environment variable

set hfile = $QCSCRATCH/hfile.$$
echo -e " node1 \n node2" > $hfile
setenv QCMACHINEFILE $hfile

c) qchem command options

qchem [-pbs] [-save] [-np $nproc] input [output] [savedir]

-pbs : flag used for submitting a parallel run under batch system.

-save: used with [savedir], save temporary files in $QCSCRATCH/savedir for restarting purpose.

-np $nproc : specify the number of MPI processes in a parallel run.

-nt $nthreads: specify the number of OpenMP threads used in a single process.

[Notes 1: currently Q-Chem does not support MPI+OpenMP parallelization. Using more than 1 MPI processes automatically disables OpenMP threading. This will change in our later releases.]

[Notes 2: Availalbe jobs for MPI parallelization: HF/DFT energy, gradient, hessian.]

[Notes 3: Availalbe jobs for OpenMP parallelization: CC/EOM, RI-MP2]

Examples:

[to run job interactively on the screen]
qchem input

[to run job using 4 MPI processes -- requires Q-Chem parallel version]
qchem -np 4 input


[to run jobs with 4 OpenMP thread on a single node]
qchem -nt 4 input

[to run job on the backgroud with an output file]
qchem input output &
tail -f output

[to save scratch directory/files for a restart job later]
qchem -save input output savedir

[to run a parallel job with saved scratch directory]
qchem -save -np 4 input output savedir

d) running q-chem under job scheduler

PBS sample scripts

#PBS -l nodes=4
#!/bin/csh
# The nodes allocated must be in file $PBS_NODEFILE
cat $PBS_NODEFILE
set NN = `cat $PBS_NODEFILE | wc -l`
setenv QC /home/user/qchem
source $QC/qcenv.csh
setenv QCSCRATCH /scratch/qchem
#
qchem -pbs -np $NN DFT_glutamine.in DFT_glutamine.out

SGE sample scripts

#!/bin/csh
#$ -S /bin/csh
#$ -N TEST
#$ -o test.out
#$ -e test.out
#$ -pe mpich 2
#$ -cwd
#
setenv PBS_NODEFILE $TMPDIR/machines
setenv P4_RSHCOMMAND /usr/bin/rsh
module load mpich1
#
setenv QC /usr/local/qchem4
source $QC/qcenv.csh
setenv QCSCRATCH /scratch/qchem
qchem -pbs -np 2 DFT_glutamine.in DFT_glutamine.out

5. Step-by-Step Tutorials and Manual

Tutorial for Linux/Mac/AIX installation

Tutorial for Windows installation

Q-Chem 4 manual


Is this online guide helpful? Want more online tutorials? Let us know your suggestions.