Getting Started with GAMESS | Bryce M. Westheimer

GAMESS (General Atomic and Molecular Electronic Structure System) is one of the major quantum chemistry packages in active use today. It has been developed continuously since the 1980s by the Gordon group at Iowa State University and a worldwide network of contributors. GAMESS supports Hartree-Fock, DFT, MP2, coupled cluster, CI, MCSCF, TDDFT, and the fragment molecular orbital method (FMO), among others. It runs on everything from laptops to supercomputers and is free for academic use.

This tutorial covers the basics: obtaining and compiling GAMESS, understanding input file structure, running calculations, and reading the output. By the end you will have run Hartree-Fock, DFT, and geometry optimization calculations on water and know where to look in the output for the numbers that matter.

Obtaining GAMESS

GAMESS source code is available from the Gordon Group at Iowa State. The license is free for academic and government users. You will need to:

Fill out the license request form on the GAMESS website
Receive a download link by email (usually within a day or two)
Download the source tarball

Pre-compiled binaries are available for some platforms, but compiling from source gives you control over compiler flags, math libraries, and parallel configuration.

Compiling GAMESS

GAMESS uses its own config script rather than CMake or autotools. The process is interactive: you answer a series of questions about your system, and the script generates the appropriate makefiles.

Prerequisites

A Fortran compiler (gfortran 9+ or Intel Fortran)
A C compiler (gcc or icc)
A math library (OpenBLAS, MKL, or the bundled ATLAS)
For parallel execution: MPI (OpenMPI or MPICH) or the sockets-based DDI layer

Configuration and build

tar xzf gamess-current.tar.gz
cd gamess

# Interactive configuration
./config

# The config script will ask about:
#   - Machine type (linux64)
#   - Fortran compiler (gfortran or ifort)
#   - Math library (openblas, mkl, or atlas)
#   - DDI communication (sockets or mpi)
#   - Network type (sockets, mpi)

# Compile the DDI communication library
cd ddi
./compddi 2>&1 | tee compddi.log
mv ddikick.x ..
cd ..

# Compile GAMESS itself
./compall 2>&1 | tee compall.log

# Link the executable
./lked gamess 01 2>&1 | tee lked.log

The version number (here 01) is arbitrary and appears in the executable name gamess.01.x. Many groups use the two-digit year or a sequential build number.

If compilation fails, check compall.log for the first error. Common problems include missing Fortran modules (usually a compiler version issue) and math library link failures (usually a path issue in install.info). The install.info file generated by config contains all the paths and flags; you can edit it directly if the interactive script got something wrong.

Verifying the build

GAMESS ships with a set of test inputs in the tests/ directory. The runall script runs them and compares against reference outputs:

./tests/standard/runall 01 1 2>&1 | tee runall.log

The arguments are: version number (01), number of compute processes (1). A passing exam produces output like:

exam01:  PASSED    water  energy
exam02:  PASSED    uhf    energy
...

A few exams may show small numerical differences on different hardware. Differences in the last digit of energies (sub-microhartree) are normal and reflect differences in math library implementations.

GAMESS Input File Anatomy

GAMESS input files are organized into named groups, each starting with $GROUP and ending with $END. Whitespace matters: group names must begin in column 2 (one leading space). Data can be free-format within each group.

Here is a minimal input file with annotations:

 $CONTRL SCFTYP=RHF RUNTYP=ENERGY COORD=UNIQUE $END
 $SYSTEM MWORDS=100 $END
 $BASIS GBASIS=N31 NGAUSS=6 NDFUNC=1 $END
 $DATA
Water RHF/6-31G*
C1
O     8.0  0.0000000   0.0000000   0.0000000
H     1.0  0.7569503   0.5858900   0.0000000
H     1.0 -0.7569503   0.5858900   0.0000000
 $END

The $CONTRL group

$CONTRL contains the master control options. The most important keywords:

Keyword	Values	Description
`SCFTYP`	`RHF`, `UHF`, `ROHF`, `MCSCF`, `GVB`	Self-consistent field type
`RUNTYP`	`ENERGY`, `OPTIMIZE`, `HESSIAN`, `SADPOINT`, `IRC`	Type of calculation
`MPLEVL`	`0`, `2`	Moller-Plesset perturbation level (0=none, 2=MP2)
`CITYP`	`CIS`, `SFCIS`, `ALDET`, `ORMAS`, `GENCI`	CI type for excited states or correlation
`DFTTYP`	`B3LYP`, `PBE`, `PBE0`, `wB97X-D`, `M06-2X`, …	DFT functional
`COORD`	`UNIQUE`, `CART`, `ZMT`, `ZMTMPC`	Coordinate input format
`ICHARG`	integer	Molecular charge (default 0)
`MULT`	integer	Spin multiplicity (default 1)
`ISPHER`	`-1`, `0`, `1`	Spherical harmonic (1) vs Cartesian (0) d/f functions

For a charged doublet radical cation, you would set SCFTYP=UHF ICHARG=1 MULT=2.

The $BASIS group

$BASIS specifies the basis set using GAMESS-specific keywords. The mapping between standard names and GAMESS keywords is not always obvious:

Standard name	GAMESS keywords
STO-3G	`GBASIS=STO NGAUSS=3`
3-21G	`GBASIS=N21 NGAUSS=3`
6-31G	`GBASIS=N31 NGAUSS=6`
6-31G*	`GBASIS=N31 NGAUSS=6 NDFUNC=1`
6-31G**	`GBASIS=N31 NGAUSS=6 NDFUNC=1 NPFUNC=1`
6-31+G*	`GBASIS=N31 NGAUSS=6 NDFUNC=1 DIFFSP=.TRUE.`
6-311G**	`GBASIS=N311 NGAUSS=6 NDFUNC=1 NPFUNC=1`
cc-pVDZ	`GBASIS=CCD`
cc-pVTZ	`GBASIS=CCT`
aug-cc-pVDZ	`GBASIS=ACCD`
aug-cc-pVTZ	`GBASIS=ACCT`

Alternatively, you can specify basis sets inline in the $DATA group on a per-atom basis, which is useful for mixed basis set calculations.

The $DATA group

$DATA contains the molecular geometry. The format is:

 $DATA
Title line (anything you want)
Symmetry group (C1 for no symmetry, Cnv, Cs, Ci, etc.)
AtomLabel  NuclearCharge  X  Y  Z
AtomLabel  NuclearCharge  X  Y  Z
...
 $END

The nuclear charge is a floating-point number: 8.0 for oxygen, 1.0 for hydrogen, 6.0 for carbon, etc. Coordinates are in Angstroms by default (COORD=UNIQUE in $CONTRL). If you prefer Bohr, set UNITS=BOHR in $CONTRL.

When using symmetry higher than C1, you only specify the symmetry-unique atoms. GAMESS generates the rest. For C1 (no symmetry), list all atoms explicitly. The symmetry group line can include additional information for axes and planes, but for C1 it is just the two characters C1.

The $SYSTEM group

$SYSTEM controls resource allocation:

 $SYSTEM MWORDS=200 MEMDDI=100 $END

MWORDS is the memory per compute process in units of 1,000,000 64-bit words (~7.6 MB per MWORD). MEMDDI is the distributed memory per process, used by certain methods (MP2 with distributed storage, FMO). Start with MWORDS=100 (760 MB) for small molecules and increase if you get memory errors.

Other commonly used groups

Group	Purpose
`$SCF`	SCF convergence options: `DIRSCF=.TRUE.` for direct SCF, `NCONV=8` for convergence threshold
`$STATPT`	Geometry optimization options: `NSTEP=50` max steps, `OPTTOL=0.0001` gradient tolerance
`$DFT`	DFT grid and method options
`$FMO`	Fragment molecular orbital settings
`$GDDI`	Parallel group configuration
`$FORCE`	Force constant (Hessian) options
`$GUESS`	Initial orbital guess: `GUESS=HUCKEL` (default), `MOREAD` (read from file)
`$VEC`	Orbital coefficients (used with `GUESS=MOREAD`)

Your First Calculation: RHF Energy of Water

Create a file called water_rhf.inp:

 $CONTRL SCFTYP=RHF RUNTYP=ENERGY $END
 $SYSTEM MWORDS=100 $END
 $BASIS GBASIS=STO NGAUSS=3 $END
 $DATA
Water RHF/STO-3G energy
C1
O     8.0  0.0000000   0.0000000   0.1173640
H     1.0  0.0000000   0.7572150  -0.4694560
H     1.0  0.0000000  -0.7572150  -0.4694560
 $END

This requests a restricted Hartree-Fock single-point energy calculation on water with the STO-3G minimal basis set. The geometry is the experimental equilibrium structure.

Running the calculation

./rungms water_rhf.inp 01 1 > water_rhf.log 2>&1

The arguments to rungms are: input file, version number, number of compute processes. The rungms script handles temporary file management, scratch directory setup, and launching the actual gamess.01.x executable.

Reading the output

The log file is long but the important sections are easy to find with grep or a text editor search. Here are the key sections in order of appearance.

Input echo. GAMESS reproduced your input near the top of the log. Check that it matches what you intended:

          SCFTYP=RHF      RUNTYP=ENERGY   EXETYP=RUN

Basis set summary. Look for TOTAL NUMBER OF BASIS SET SHELLS and NUMBER OF CARTESIAN GAUSSIAN BASIS FUNCTIONS:

 TOTAL NUMBER OF BASIS SET SHELLS          =    5
 NUMBER OF CARTESIAN GAUSSIAN BASIS FUNCTIONS =    7

STO-3G on water (2 H + 1 O) gives 7 basis functions: 1s on each hydrogen (2 total), and 1s, 2s, 2px, 2py, 2pz on oxygen (5 total).

Nuclear repulsion energy. This appears before the SCF iterations:

 NUCLEAR REPULSION ENERGY =         9.1571164588

This is a useful sanity check. If it is wildly different from what you expect, the geometry is probably wrong.

SCF iterations. The SCF convergence table shows the energy at each iteration and the density change:

 ITER EX  TOTAL ENERGY       E CHANGE   DENSITY CHANGE
   1  0  -74.9041884825  -74.9041884825   0.613277776
   2  1  -74.9629824512   -0.0587939687   0.179901615
   3  2  -74.9643240093   -0.0013415581   0.063568252
   ...
   9  0  -74.9643287230    0.0000000000   0.000000066

Convergence is reached when both the energy change and the density change fall below the threshold (default: 10^-5 hartree for energy).

Final energy. Search for TOTAL ENERGY:

 TOTAL ENERGY =      -74.9643287230

This is the total electronic energy plus nuclear repulsion, in Hartree. For water/STO-3G, the RHF energy is approximately -74.964 Hartree. If you get this number (to 3-4 decimal places), your GAMESS installation is working correctly.

Orbital energies. After the SCF converges, GAMESS prints the molecular orbital energies:

                      1          2          3          4          5
                  -20.2432    -1.2687    -0.6184    -0.4533    -0.3913

Water has 10 electrons in 5 doubly-occupied MOs. The HOMO is MO 5 at -0.3913 Hartree and the LUMO is MO 6 (check the next line for its energy). The HOMO-LUMO gap gives a rough indication of chemical stability.

Mulliken population analysis. Atomic charges from Mulliken analysis appear near the end:

          ATOM      MULLIKEN CHARGE
     1  O           -0.380382
     2  H            0.190191
     3  H            0.190191

Mulliken charges are basis-set dependent and should not be over-interpreted, but they provide a quick sanity check that the electron density is chemically reasonable. Oxygen should be negative, hydrogens positive.

Comparing Basis Sets

The choice of basis set has a large effect on calculated energies and properties. Here is water at the RHF level with several basis sets, using the same geometry:

Basis set	Basis functions	RHF energy (Hartree)	Relative (kcal/mol)
STO-3G	7	-74.9643	+35.2
3-21G	13	-75.5854	-3.8
6-31G*	19	-76.0107	+6.9
6-31G**	25	-76.0236	-1.2
cc-pVDZ	24	-76.0268	+3.2
cc-pVTZ	58	-76.0573	+0.3
cc-pVQZ	115	-76.0651	reference

The relative column shows how far each result is from the near-complete-basis-set result (cc-pVQZ). STO-3G is qualitatively wrong for energetics (35 kcal/mol too high). 6-31G* is a reasonable starting point for most work. The cc-pVDZ and cc-pVTZ Dunning basis sets are designed for correlated calculations (MP2, CCSD) and converge systematically.

To change the basis set, edit the $BASIS group. For example, to use cc-pVDZ:

 $BASIS GBASIS=CCD $END

Or 6-31+G* (diffuse functions on heavy atoms):

 $BASIS GBASIS=N31 NGAUSS=6 NDFUNC=1 DIFFSP=.TRUE. $END

Geometry Optimization

A geometry optimization starts from an initial geometry and finds the nearest local minimum on the potential energy surface. Change RUNTYP=ENERGY to RUNTYP=OPTIMIZE and add a $STATPT group.

Create water_opt.inp:

 $CONTRL SCFTYP=RHF RUNTYP=OPTIMIZE $END
 $SYSTEM MWORDS=100 $END
 $BASIS GBASIS=N31 NGAUSS=6 NDFUNC=1 $END
 $STATPT NSTEP=50 OPTTOL=0.0001 $END
 $DATA
Water RHF/6-31G* optimization
C1
O     8.0  0.0000000   0.0000000   0.0000000
H     1.0  0.0000000   0.7800000   0.5600000
H     1.0  0.0000000  -0.7800000   0.5600000
 $END

The starting geometry here is deliberately a bit off from equilibrium. NSTEP=50 allows up to 50 optimization steps, and OPTTOL=0.0001 sets the gradient convergence threshold in Hartree/Bohr.

Run it the same way:

./rungms water_opt.inp 01 1 > water_opt.log 2>&1

Reading optimization output

Each optimization step prints the current energy and the maximum gradient component. Search for NSERCH to find the step summaries:

 NSERCH:   0  E=      -76.0098041618  GRAD. MAX=  0.0234511
 NSERCH:   1  E=      -76.0105834271  GRAD. MAX=  0.0067892
 NSERCH:   2  E=      -76.0107214831  GRAD. MAX=  0.0004325
 NSERCH:   3  E=      -76.0107237155  GRAD. MAX=  0.0000421

When the maximum gradient drops below OPTTOL, the optimization has converged. Look for:

 ***** EQUILIBRIUM GEOMETRY LOCATED *****

The final optimized coordinates appear after this line. Compare the O-H bond length and H-O-H angle against experimental values (0.958 A and 104.5 degrees) as a sanity check.

If the optimization does not converge in NSTEP iterations, you will see:

 ***** FAILURE TO LOCATE STATIONARY POINT *****

This usually means the starting geometry was too far from a minimum, or the optimization is oscillating. Try a better starting geometry, increase NSTEP, or switch to a different optimizer (METHOD=RFO or METHOD=QA in $STATPT).

DFT Calculations

DFT calculations in GAMESS use the DFTTYP keyword in $CONTRL. The SCF type remains RHF for closed-shell DFT (GAMESS internally handles the Kohn-Sham equations within the RHF framework).

Create water_dft.inp:

 $CONTRL SCFTYP=RHF RUNTYP=ENERGY DFTTYP=B3LYP $END
 $SYSTEM MWORDS=100 $END
 $BASIS GBASIS=N31 NGAUSS=6 NDFUNC=1 $END
 $DATA
Water B3LYP/6-31G* energy
C1
O     8.0  0.0000000   0.0000000   0.1173640
H     1.0  0.0000000   0.7572150  -0.4694560
H     1.0  0.0000000  -0.7572150  -0.4694560
 $END

The output structure is the same as for RHF. The TOTAL ENERGY now includes the exchange-correlation energy from the B3LYP functional. For water/6-31G*, the B3LYP energy is approximately -76.409 Hartree, lower than the RHF energy (-76.011) because DFT captures electron correlation that Hartree-Fock misses.

Choosing a functional

GAMESS supports a range of DFT functionals. Some commonly used ones:

Functional	`DFTTYP`	Type	Notes
B3LYP	`B3LYP`	Hybrid GGA	Workhorse general-purpose functional
PBE	`PBE`	GGA	Good for solids and surfaces
PBE0	`PBE0`	Hybrid GGA	More accurate than PBE for molecules
M06-2X	`M06-2X`	Meta-hybrid GGA	Good for thermochemistry and noncovalent interactions
wB97X-D	`wB97X-D`	Range-separated hybrid + dispersion	Strong for noncovalent interactions
BLYP	`BLYP`	GGA	Simpler version of B3LYP without exact exchange

For noncovalent interactions (hydrogen bonds, van der Waals complexes), use a functional with dispersion correction. wB97X-D includes it by default. For B3LYP, you can add Grimme’s D3 correction with the $DFT group:

 $CONTRL SCFTYP=RHF RUNTYP=ENERGY DFTTYP=B3LYP $END
 $DFT DC=.TRUE. $END

DFT grid options

The numerical integration grid for DFT affects both accuracy and cost. GAMESS uses a Lebedev-Laikov angular grid and a Euler-Maclaurin radial grid. The default grid is adequate for most calculations, but you can tighten it for benchmarks:

 $DFT NRAD=99 NLEB=590 $END

This sets 99 radial points and 590 angular points per atom (a fine grid). The default is roughly NRAD=96 NLEB=302.

Running in Parallel

GAMESS parallelism is built on the Distributed Data Interface (DDI). DDI can run over TCP sockets (simplest setup) or MPI. The rungms script handles the details.

For a 4-process run:

./rungms water_rhf.inp 01 4 > water_rhf.log 2>&1

For MPI-based DDI, the rungms script calls mpirun internally. You may need to edit rungms to point to your MPI installation.

GAMESS also supports the Generalized DDI ($GDDI) for FMO calculations, which divides processors into groups. Each group independently handles a subset of fragment calculations:

 $GDDI NGROUP=4 $END

This creates 4 groups. If you run with 16 total processes, each group gets 4 processes. Group decomposition is how FMO achieves parallel scalability for large systems.

Memory considerations

The MWORDS value in $SYSTEM is per compute process. If you run 4 processes on a node with 16 GB of RAM, each process should use at most MWORDS=500 (about 3.8 GB each, leaving headroom for the OS and DDI overhead). Running out of memory produces cryptic errors. When in doubt, start small and increase.

Common Errors and Troubleshooting

“EXECUTION OF GAMESS TERMINATED -ABNORMALLY-” appears at the bottom of nearly every failed run. Scroll up to find the actual error message. Common causes:

Error message	Cause	Fix
`INSUFFICIENT DISTRIBUTED MEMORY`	`MEMDDI` too small	Increase `MEMDDI` in `$SYSTEM`
`INSUFFICIENT MEMORY`	`MWORDS` too small	Increase `MWORDS` in `$SYSTEM`
`FAILURE TO LOCATE STATIONARY POINT`	Optimization did not converge	Better starting geometry, more steps, different optimizer
`SCF IS NOT CONVERGING`	SCF oscillating or diverging	Try `DIRSCF=.TRUE.` in `$SCF`, damping, or level shifting
`ERROR: ATOMIC SYMBOL NOT RECOGNIZED`	Typo in atom label in `$DATA`	Check element symbols
`ILLEGAL CHARGE`	Wrong `ICHARG`/`MULT` combination	Check electron count: neutral closed-shell needs `ICHARG=0 MULT=1`

SCF convergence problems are the most common annoyance. For difficult cases (transition metals, open-shell systems, nearly degenerate states), try these in order:

Use DIRSCF=.TRUE. in $SCF (direct SCF, recomputes integrals each iteration)
Tighten the convergence: NCONV=7 or NCONV=8 in $SCF
Add level shifting: RSTRCT=.TRUE. or SOSCF=.TRUE. in $SCF
Use a different initial guess: GUESS=HUCKEL or GUESS=MOREAD in $GUESS

Scratch disk issues. GAMESS writes temporary files to a scratch directory (set in rungms). If the scratch disk is full or slow (e.g., NFS-mounted), calculations will fail or run slowly. Use a local SSD if possible.

Quick Reference

 $CONTRL
   SCFTYP=RHF          Wavefunction type (RHF, UHF, ROHF, MCSCF)
   RUNTYP=ENERGY        Calculation type (ENERGY, OPTIMIZE, HESSIAN)
   DFTTYP=NONE          DFT functional (B3LYP, PBE0, M06-2X, ...)
   MPLEVL=0             MP2 correlation (0=none, 2=MP2)
   ICHARG=0             Molecular charge
   MULT=1               Spin multiplicity
   COORD=UNIQUE         Coordinate format
   ISPHER=-1            Spherical harmonics (-1=basis-dependent)
 $END

 $SYSTEM
   MWORDS=100           Memory per process (millions of 64-bit words)
   MEMDDI=0             Distributed memory per process
 $END

 $BASIS
   GBASIS=N31           Basis set family
   NGAUSS=6             Number of Gaussians
   NDFUNC=1             d polarization functions
   NPFUNC=0             p polarization functions on H
   DIFFSP=.FALSE.       Diffuse sp on heavy atoms
 $END

 $STATPT
   NSTEP=50             Max optimization steps
   OPTTOL=0.0001        Gradient convergence (Hartree/Bohr)
   METHOD=QA            Optimizer (QA, NR, RFO)
 $END

 $SCF
   DIRSCF=.TRUE.        Direct SCF (recompute integrals)
   NCONV=5              Energy convergence (10^-NCONV)
   SOSCF=.FALSE.        Second-order SCF convergence aid
 $END

Next Steps

Once you are comfortable with single-molecule calculations, several directions open up:

Correlated methods. Add MPLEVL=2 in $CONTRL to run MP2 on top of RHF. MP2 captures dynamical correlation and gives much better energetics than HF alone, especially for reaction energies and noncovalent interactions. It requires more memory (set MEMDDI appropriately) and scales as O(N^5).

Excited states. Use CITYP=CIS for configuration interaction singles (excited state energies and properties) or TDDFT by combining DFTTYP with TDDFT=EXCITE in $CONTRL.

Fragment molecular orbital (FMO). For large systems (proteins, molecular clusters), FMO partitions the system into fragments and computes interactions between them. This is where GAMESS really distinguishes itself from other codes. See my autofragment tutorial for a hands-on walkthrough of setting up FMO calculations, and the fragment-based methods overview for the theory behind it.

Interfacing with Python. GAMESS input files are plain text, so they are straightforward to generate and parse programmatically. The autofragment library automates the generation of FMO input files from molecular structure files.

For the full list of keywords and features, the GAMESS documentation is the definitive reference. The REFERENCES.TXT file in the GAMESS distribution lists the papers to cite for each method.