QChem

Last updated October 08, 2026

Q-Chem is a comprehensive package for quantum chemistry calculations in molecules and materials, which comes already installed on CARC systems.

To get started, request an allocation on the Discovery cluster. Check if your group already has an allocation and ask the PI to add you to the list of users. If you do not have one, the PI of the research group can request an allocation via the User Portal.

Once you have an allocation, you should be able to run Q-Chem; as of fall 2026, USC has a site license. The current version is Q-Chem 7, but older versions are also available for troubleshooting.

You can submit jobs by connecting to CARC with SSH and using a Slurm script (this requires a basic knowledge of Unix). You can also access Discovery and submit jobs via the CARC OnDemand service, which provides browser-based access to the shell command line as well as graphical applications, including IQmol.

Because of the dual authentication requirement, jobs can no longer be submitted to Discovery via IQmol installed locally on your device, but you can use IQmol installed on Discovery via a browser using CARC OnDemand (see instructions here).

Do not use MPI unless you are already familiar with it! Currently, MPI is enabled for finite difference calculations and for fragmentation methods.

Clean up temporary (scratch) directories regularly! When finished normally, Q-Chem scripts wipe out the temporary directories (called qchemXXXX), but if the job was killed or if the node crashed, there will be bulky leftovers on the disk. The default setup on Discovery uses /scratch1/<username> as the QCSCRATCH directory, so check this directory regularly and clean up all stale qchemXXXX directories.

1 How to submit jobs on Discovery via command line using Slurm

  1. Log in to Discovery using your USC credentials.

  2. Create your Q-Chem input file: my_input.inp

  3. Create a Slurm run script, qc.run, with the following content, making necessary adjustments to Q-Chem version, queue, walltime, etc.

The current version of Q-Chem is 7.0.0. Note that there are two executables: OpenMP (use this for most jobs) and MPI (for select job types only). You need to load the correct one in the Slurm run script:

module load qchem/7.0.0-openmp

or

module load qchem/7.0.0-mpi

Adjust the number of cores or Q-Chem version as needed. By default, it will use only 1 node, which is recommended for most jobs and should always be the case for the OpenMP version. If the user wants to run an MPI job over several nodes, the following variables should be adjusted. The example below uses 8 nodes and 12 threads on each node:

#SBATCH --nodes=8
#SBATCH --ntasks-per-node=12

Please be consistent in #SBATCH variables and qchem arguments or input—do not forget to put the same number of threads, nodes, and amount of memory in both #SBATCH and Q-Chem. The script below is a minimal example useful for small jobs.

#!/bin/bash
# Set the number of threads (in this example it is 4)
#SBATCH --ntasks=4
# The amount of memory should be consistent with mem_total from the input
# mem=0 means use all the available memory in the node
#SBATCH --mem=4000MB
# Mention time limit of job, default time limit is 30 minutes
#SBATCH --time=01:00:00

module purge
module load usc
module load qchem-openmp

cd $SLURM_SUBMIT_DIR
hostname

# DO NOT FORGET TO CHANGE THE NUMBER OF THREADS HERE!
# Set the number of threads (-nt the_number_you_need)
qchem -nt 4 -save input.inp output.out
  1. Submit your Slurm job:
sbatch qc.run

To run Q-Chem in parallel, change -nt 1 to -nt N in the above script (N is the number of CPU cores; typical values are 4-32). This option should be used only for jobs that take more than 15 minutes. Consult the Q-Chem manual for more information.

For optimal performance, use adequate memory, set up both in the script and in the input.

Note the -save option in the above script: it means that additional files will be saved to your scratch directory. This option is needed for debugging.

To run parallel calculations with MPI, use -mpi and -np to specify the number of MPI processes (the number of processes is 8 in this example):

qchem -mpi -np 8 input_file output_file

2 Additional resources

2.1 USC CARC resources

2.2 Getting started with IQmol

2.3 Q-Chem resources

  • Q-Chem manual (HTML and PDF): Everything you need to know about Q-Chem. Includes theoretical background and examples of sample jobs.
  • Q-Chem user forum: Place to ask support questions, learn from others, and find detailed instructions on different types of calculations.
  • Q-Chem YouTube channel: Collection of webinars on basic and advanced topics.

Adapted from How to run Q-Chem on USC CARC by the iOpenShell lab.