Skip to main content

Using Q-Chem on the Eagle System

Q-Chem is a comprehensive ab initio quantum chemistry package with special strengths in excited state methods, non-adiabatic coupling, solvation models, explicitly correlated wave-function methods, and cutting-edge density functional theory (DFT).

Running Q-Chem on Eagle

The q-chem module should be loaded to set up the necessary environment. The module help output can provide more detail. In particular, the modulefile does not set the needed environment variable QCSCRATCH, as this is likely unique for each run. QCLOCALSCR is set by default to /tmp/scratch, but one may wish to point to a more persistent location if files written to local scratch need to be accessed after the job completes. The user can easily do this in their Slurm scripts or at the command line via export (Bash) or setenv (csh).

The simplest means of starting a Q-Chem job is via the supplied qchem wrapper. The general syntax is:

qchem -slurm <-np number_of_MPI_ranks> <-nt number_of_OpenMP_threads> <input file> <output file> <savename>

For example, to run a hybrid job with 2 MPI ranks and 36 threads available to each:

qchem -slurm -np 2 -nt 36 example.in

Note: The Q-Chem input file must be in the same directory in which you issue the qchem command. In other words, qchem ... SOMEPATH/<input file> won't work.

Note: The installed Q-Chem build only works with the OpenMPI version that is auto-enabled when loading the q-chem module. It is not expected to work with any other MPI library.

If only -np # is specified, the job will run as purely distributed-memory MPI with 1 thread per rank. If only the -nt # option is provided, the job will run on a single node, with up to the specified number of OpenMP threads. For a full list of which types of calculation are parallelized and the types of parallelism, see the Q-Chem User's Manual.

With Slurm, "tasks" will translate roughly to threads with Q-Chem, assuming one rank per node. If you request tasks instead of nodes, you will need to request --ntasks and --ntasks-per-node accordingly.

The savename option is needed to save certain intermediate files for, e.g., restart. If not provided, all scratch files will be automatically deleted at job's end by default. If provided, a directory $QCSCRATCH/savename will be created and will hold saved files. In order to save all intermediate files, you can add the --save option.

A template Slurm script to run Q-Chem (in serial) is:

#SBATCH --job-name=my_qchem_job
#SBATCH --account=my_allocation_ID
#SBATCH --ntasks=1
#SBATCH --time=01:00:00 #SBATCH --mail-type=BEGIN,END,FAIL #SBATCH --mail-user=your_email@domain.name #SBATCH --output=std-%j.out #SBATCH --error=std-%j.err   # Load the Q-Chem environment
module load q-chem/5.2   # Go to the location of job files, presumably from where this file was submitted cd $SLURM_SUBMIT_DIR   # Set up scratch space SCRATCHY=/scratch/$USER/${SLURM_JOB_NAME:?} if [ -d $SCRATCHY ] then    rm -r $SCRATCHY fi mkdir -p $SCRATCHY export QCSCRATCH=$SCRATCHY   # Move files over cp * $SCRATCHY/. cd $SCRATCHY   # Start run qchem job.in job.out

A large number of example Q-Chem input decks are available in /nopt/nrel/apps/q-chem/5.2/samples.