[an error occurred while processing this directive] [an error occurred while processing this directive] [an error occurred while processing this directive] [an error occurred while processing this directive]


This is an updated version of the file and is still "work in progress". To access the old version, click here.


Test Cases
Known Problems


This document describes the interface between the GAMESS-UK and CHARMM. The interface allows a single binary to be built with support for ab-initio and DFT QM/MM calculations.

The CHARMM side of the interface is distributed as part of http://yuri.harvard.edu CHARMM) but is not activated by default. The GAMESS-UK part is distributed as part of GAMESS-UK (version 6.2 and later) from http://www.cfs.dl.ac.uk). However as both CHARMM and GAMESS-UK are developing there are some issues relating to which versions of the programmes you can use, as described below. This documentation relates to version 4 of the interface.

The CHARMM/GAMESS-UK Interface supports the following QM/MM functionality:

Other wavefunction options in GAMESS-UK can be accessed, but some changes to the build procedure will be needed.



To run a QM/MM calculation within GAMESS-UK you will need the following steps: The remainder of this section deals with some of the above steps in more detail.

GAMESS-UK input file

The GAMESS-UK control data is provided in a standard GAMESS-UK input file but without any coordinates specification. A number of charmm specific keywords may be provided and are illustrated in the following sample input, all start with "chm":

core 5000000
#Include only when running with GA tools
parallel iomode nzo
# Request that all gamess-uk outputs are concatented
# (default is to overwrite)
chm append
# Suppress printing of the atom list
# This can reduce file sizes significantly
chm noatom
# Provide an energy offset, this is subtracted from the
# energy before returning to charmm
chm offset -1200.000
qm region for charmm
charge -1
adapt off
noprint distance analysis
basis sto3g
scftype rhf
runtype gradient
vectors atoms
enter 1

Note that noprint distance analysis us included to avoid two sections of diagnostic print which require a large amount of memory to generate. Without this keyword memory problems can be expected.

Environment Variables

Environment variables are used to control the files written and read by GAMESS-UK. Many of these are described in the GAMESS-UK documentation. When running with CHARMM, providing a name for the dumpfile (ed3) is mandatory. This can be peformed by issuing setenv before running CHARMM, but it will more typically be performed using the envi command in the CHARMM script:

envi "ed3" "charmm.ed3"

The iput and output files can optionally be renamed, using the strings "gamess.in" and "gamess.out", which are the default file names.

envi "gamess.in" "data/alanine_guk.in"

Adding Single Link Atoms

Traditionally QM/MM calculations in CHARMM have been performed using unconstrained link atoms, with additional terms added to the RTF and parameter files to restrain the positions of the link atoms, which then move independently in the dynamics or optimisation procedures. The recommended approach now is to derive the link atom coordinates from the positions of the atoms defining the bond being terminated. Within CHARMM, this can be achieved most easily using the lone pair facility. No additional forcefield terms are needed and there are no additional degrees of freedom in the simulations. At the current time it is still necessary to make some changes to the topology and parameter files as detailed here:

  1. There should be an atom type in the .RTF file of type QQH with a mass of 1.008 (a much lighter mass would make more sense, still needs to be tested, it may get zeroed by the lone pair facility anyway).
  2. There should be a record in the NONBONDED section setting the van der waals parameters to zero
    QQH    0.000000   0.000000     0.224500 ! Link atom
  3. Provide a zero force-constant bond parameter between the link atom type (QQH) and the QM host, and between the link atom type (QQH) and the MM host type
  4. (ADDLink users only) Provide a zero force-constant angle parameter QQH-QMHost-MMHost. If you are using the LONEPair facility to restrain the link atom positions, this should have a force constant of zero. e.g.
    qqh  cc   ct1    0.0        0.0    ! Link atom
    Otherwise a co-linearity restraint term is provided here.

To add the link atom to the PSF you have 3 options,

  1. Edit it into the RTF as part of the QM residue This may be best if you already have edited RTF files from semi-empirical studies
  2. Use the ADDLink command. e.g. for a link between QM atom C2 and MM atom C1 in residue 1 of segment PAMN:
    ADDL QQL pamn 1 c2 pamn 1 c1
    ADDLink performs the following functions:
  3. Patch the PSF using a patch residue, such as the following entry in the RTF:
    PRES  SLA   -0.27
    ATOM  C2  CT2   0.00  ! Sets pointer so that link is added after the QM host
    ATOM  QQL QQH   0.00  ! The new atom
    ATOM  C1  CT3  -0.27  ! This record is not actually needed
                          ! as the charge and type are unchanged
    BOND  C2  QQL
    BOND  C1  QQL
    which is invoked using the following command.
    PATCH SLA pamn 1 setup
    Note that two new bonds QMHost -- Link and MMHost -- Link have been added. This requires that the parameter file be adapted to include zero force constant bond terms for the appropriate types as described above.

At this stage it is possible to define the QM atoms using the gamess keyword.

gamess remove sele qm end

To position the link atoms use the lone pair facility with the co-linear keyword.

! constraining the QM link atom qql (between QMH c2 and MMH c1)
lone coli dist -1.0 sele atom pamn 1 qql end -
                      sele atom pamn 1 c2  end -
                      sele atom pamn 1 c1  end

Because the lone pair code sets the mass of the lone pair to zero, and because the gamess command uses the atom mass to determine the atomic type, it is necessary to issue the lone pair command after the gamess module has been invoked.

Adding Double Link Atoms

You should follow the procedure described above except that there is curently no ADDLink command option, so you will need to use a patch or edit the RTF. An example patch is shown below:
PRES  DLA   -0.27
ATOM  C2  CT2   0.00
ATOM  QQL QQH   0.00
ATOM  C1  CT3  -0.36  ! modified MMHost + MMLink charges
ATOM  MML QQH   0.09  ! must sum to old MMHost charge

You need to provide zero force constant bonds for both the QMHost--QQL and MMHost--MML bonds.

There is no MMHost-QQL connection. This is significant because this connection is the one that identifies the MM Host and activates the exclusion of the MM host, or the MM charge group. The DLA model must be used with gaussian blur and as such MM Host deletion is not desired.

Two lone pair commands are needed to position and constrain the link atoms

! constraining the QM link atom qql (between QMH c2 and MMH c1)
lone coli dist -1.0   sele atom pamn 1 qql end -
                      sele atom pamn 1 c2  end -
                      sele atom pamn 1 c1  end

! constraining the MM link atom mml (between MMH c1 and QMH c2)
lone coli dist -1.0   sele atom pamn 1 mml end -
                      sele atom pamn 1 c1  end -
                      sele atom pamn 1 c2  end

Keywords to the GAMESS Command

The gamess keyword accepts an atom selection, which defines the QM atoms, together with a number of keywords. e.g.:

gamess remo exgr sele qm end
Some are probably now of historical interest only, so a limited number of them are discussed here. The syntax is

REMO: Remove MM Terms

This should always be presented to avoid double counting the QM energy.

EXGR: Exclude Group

The EXGR keyword causes CHARMM to exclude the charges from the whole charge group containing the MM host. This is option is strongly recommended for calculations using the single link atom method. It will not be effective for DLA calculations following the procedures described above, but it could be enabled by adding a zero-force constant bond between MMHost and QQL.

BLUR: Gaussian Blur

Gaussian blur is selected by setting up an array of values, in the CHARMM WMAIN vector and adding the BLUR keyword. A value greater than 999.0 is taken as signal to exclude a specific atom from the QM/MM interaction. A value of 0.0 (or less than zero??) indicates a point charge. The units of the blur are angstroms2.

Test Cases

The test cases can be found directory cquantumtest. Data files are references in subdirectory tests/data, and assume the examples are being run from the test subdirectory. If the example is not present you can download the test and you should unpack the tar file in the tests directory.

Alanine Dipeptide

alanine_guk.inp: Simple single link atom QM/MM, ADDL Command Sample Output

FLUCQ test case

fqqguk.inp: The water dimer using fluctuating charge qm/mm model. Sample Output


CHARMM must be built with the default quantum interface replaced by GAMESS-UK (they cannot co-exist) which requires the following changes relative to the normal CHARMM build procedure. $CHMROOT is the top directory of CHARMM, something like c28b2. The is version relates to version 4 of the interface. The install.com and makefiles will attempt to provide an automatic build provided that parallel code uses MPI (for both CHARMM and GAMESS-UK). To allow further customisation of the build and operation of GAMESS-UK a number of environment variables are provided.
Variable Default Function
CHMGUK_LIBS none Extra libraries to link
CHMGUK_MACHINE guess GAMESS-UK machine specification
CHMGUK_OPTIONS guess them automatically configuration keywords for GAMESS-UK Build
CHMGUK_EXTRA_OPTIONS none Extra configuration keywords to append to guessed set
CHMGUK_USE_GA 0 Whether to activate GA version of GAMESS-UK
CHMGUK_BUILD_LEVEL base (mp2 for GA builds) GAMESS-UK build level (base, mp2, etc, see GAMESS-UK documentation).
CHMGUK_USE_CHARMMPAR 0 Whether GAMESS-UK should call CHARMM CMPI layer (needed for replica path)


  1. there is no longer a ga flag on install.com (cf version 3)
  2. if you change the build level from base (serial,mpi) mp2 (ga) the charmm makefiles won't detect dependencies on the extra files you bring in. If you change the GAMESS-UK files issue a "make" command within source/gukint/GAMESS-UK/m4 before running install.com

Building with Global Arrays

While we have tried to ensure that the MPI build can be carried out from install.com, this is not really possible for the GA based build without complicating the rather complicated install.com even further. To switch the GAMESS-UK to run over the Global Arrays the following are needed:

The main problem that will be encountered in building the GA version of the interface, once GAMESS-UK runs over the GAs, is the possibility that different parts of the softare are compiled in incompatible ways, e.g. when using the g77 compiler it is necessary to ensure that consistent fortran name mangling options are used for all elements. Other possible sources of incompatibility are the 64 vs 32 bit compilation, and choice of 4 or 8 byte integfers.

Building with Global Arrays on Linux Clusters

The calling structure for the CHARMM-GAMESS-UK program on a Linux cluster is as shown in the following diagram:

   |                                     |
   |             CHARMM                  |
   |                                     |
   |______________________               |
   |                      |              |
   |      GAMESS-UK       |              |
   |______________________|              |
   |                      |              |
   |  Global Arrays       |              |
   |       _______________|______________|
   |       |                             |
   |       |  MPI  (e.g. MPICH)          |
   | low-level comms libs (gm, scali etc)|

When using the GNU g77 compiler a problems will be encountered with the setting of the -fno-second-underscore flags, since GA's convention (to use the flag) usually clashes with CHARMM/MPI ones A workaround is to make your own g77 script that incorporates -fno-second-underscore, use this to re-build mpich and CHARMM to match the global arrays and GAMESS-UK. When using the Portland Group compilers is easier as the double-underscore mangling is not present.

Supported Platforms, c30a1, c29b2

In the table below, "Keys" denotes the additional keywords to present to install.com in addition to the chmhost keyword (see the relevant column) the size parameter, and "U" for GAMESS-UK. Click on the "script" link for a sample installation script.
System OS, compiler CHARMM host type GAMESS host type Parallel Integer Length Address Length Ported Keys Notes
Alpha Tru64 alpha axpev6 serial i4 64 Yes - script
Pentium Linux, g77 gnu linux serial i4 32 Yes - So far only tested with g77. When using g77 check that the -fno-second-underscore options chosen for GAMESS-UK and CHARMM are the same. script
Pentium Linux gnu linux mpi i4 32 Yes - script
Pentium Linux PGI linux mpi i4 32 Yes - script

Untested Platforms

These platforms should work but have not been tried (or not tried recently). In the table below, "Keys" denotes the additional keywords to present to install.com in addition to the chmhost keyword (see the relevant column) the size parameter, and "U" for GAMESS-UK. Click on the "script" link for a sample installation script.
System OS, compiler CHARMM host type GAMESS host type Parallel Integer Length Address Length Ported Keys Notes
Alpha Tru64 alpha axpev6 MPI i4 64 No M As above, use COMPAQ MPI implementation.
Alpha Tru64 alpha axpev6 GA i8 64 No i8 M
Alpha Linux gnu axpev6 serial i8 64 No cfort i8 version of GAMESS-UK is needed (check charmm_configure script).
Alpha Linux gnu axpev6 GA i8 64 No cfort No major problems expected, see comment above regarding i8
Pentium Linux gnu linux GA i4 32 Yes M mpich Note
IBM rs6000 ibmrs AIX rs6000 serial i4 32 Yes - -
IBM SP3 AIX ibmsp3 sp3 MPI i4 32 No M No Major problems expected
IBM SP3 AIX ibmsp3 sp3 GA i4 32 No M Requires availability of LAPI
SGI mips2 Irix sgi sgi serial i4 32 Yes - -
SGI r10k etc Irix sgi sgitfp serial i4 32 No - Not clear if this is sensible, try 64 bit build
SGI mips4 Irix sgi64 sgitfp serial i4 64 No - GAMESS-UK build options are currently under review. This should be possible but there might be problems with i8 being switched on GAMESS-UK
SGI mips4 Irix sgi64 sgitfp MPI i4 64 No M Should work but see above
SGI mips4 Irix sgi64 sgi64 GA i8 64 No M i8 Should work, script
Sun Ultrasparc Solaris sun solaris? serial i4 32 No - script

Problem Build Combinations

System OS, compiler CHARMM host type GAMESS host type Parallel Integer Length Address Length Ported Keys Notes
Alpha Linux gnu axpev6 MPI i8 64 No cfort Will not work (i8 GAMESS-UK calls i4 MPI)

Replica Path builds

Build as for a MPI based CHARMM but add CHMGUK_USE_CHARMMPAR setting. e.g., for linux cluster:
setenv MPI_LIB /usr/local/mpich-1.2.0/lib
setenv MPI_INCLUDE /usr/local/mpich-1.2.0/lib
install.com gnu medium U M MPICH
You cannot combine the replica path parallelism with the global arrays.

How the build works

The following list provides some guidance on the CHARMM/GAMESS-UK build procedure which will help if the process fails for some reason.

Porting to New Architectures

The following steps are recommended

Version History

These table is provided to help work out how to build a CHARMM/GAMESS-UK executable for given CHARMM and GAMESS-UK versions.

It is strongly recommended that all users of the interface use the latest version (4), even if this means updating some of the files on the charmm side, and some routines on the gamess side.
Version GAMESS-UK versions Notes Problems
0 ?
  • First implementation
1 Release 6.3 some versions of 6.3.1, util3 version # < 1.88
  • flucq not correct
2 some versions of 6.3.1, util3 version # >= 1.88
  • Atom reordering (GMSMAP array) introduced. This significantly improved the performance of DFT calculations
  • ????INTEGER8 pref.dat keyword
  • install.com changes not distributed
  • flucq option broken
3 some versions of 6.3.1 util3 version # >= 1.89
  • Replica path implemented, interface code merged with GAMESS(US),
  • ?
4 6.3.2 Onwards
  • GAMESS-UK specific details handled by environment variables
  • parallel groups for replica path
  • Version checking added
  • definition of charmm->gamess mapping array changed
  • flucq repaired (serial and parallel)
None Known yet

Table of CHARMM versions

Version Status Date i/f ver # Notes
c27a1 Dev Sep 1998 ~ c27 releases are tricky because a lot of variable and routine name clashes were still present. Not recommended.~
c27a2 Dev Feb 1999 ~ ~
c27b1 Rel Aug 1999 ~ ~
c27b2 Rel Feb 2000 ~ ~
c27b3 Rel Aug 2000 ~ ~
c27b4 Rel Feb 2001 ~ ~
c28a1 Dev Aug 1999 ~ ~
c28a2 Dev Feb 2000 0 ~
c28a3 Dev Aug 2000 ~ ~
c28a4 Dev Feb 2001 1 ~
c28b1 Rel Aug 2001 1 ~
c28b2 Rel Feb 2002 2 To upgrade to v4, replace gukini.src, gamess.fcm, fluqqmmm
c29a1 Dev Aug 2001 2 ~
c29a2 Dev Apr 2002 ~ ~
c29b1 Rel Aug 2002 3 ~
c29b2 Rel Feb 2003 3 ~
c30a1 Dev Aug 2002 3 ~
c30a2 Dev Feb 2003 4 merged us/uk code, fixed
c30a2x Eval Feb 2003 4 ~
c30b1 Rel Aug 2003 4 ~
c30b2 Rel Feb 2004 4 ~
c31a1 Dev Aug 2003 4 ~
c31a2 Dev Feb 2004 4 ~

Known Problems

The be added


At present, we only maintain information relating to interfacing various versions of CHARMM with modern versions of GAMESS-UK, those that support version 4 of the interface. If you do not find your version of CHARMM in the list below, please contact p.sherwood@dl.ac.uk.


  1. Fluctuating charge

    Rick et. al., J. Chem. Phys. 101 (7) 1994 p6141 (MM system)

    Bryce et. al., Chem. Phys. Lett. 279 1997, p367 (QM/MM interaction )

  2. Gaussian Blur/Double Link Atom

    Optimization of Quantum Mechanical/Molecular Mechanical Partitioning Schemes: Gaussian Delocalization of MM Charges and the Double Link Atom Method, Debananda Das, Kirsten P. Eurenius, Eric M. Billings, Paul Sherwood, David C. Chatfield, Milan Hodocek, and Bernard R. Brooks J. Chem. Phys 117 (2002): 10534-10547.

  3. Replica Path

    Exploring the QM/MM Replica Path Method: A Pathway Optimisation of the Chorismate to Prephenate Claisen Rearrangement Catalyzed by Chorismate Mutase, H.L. Woodcock, M. Hodoscek, P. Sherwood Y. S. Lee, H.F. Schaefer III and B.R. Brooks, Theoretical Chemistry Accounts, 109, (2003) 140-148

For more information about the work of the Computational Chemistry Group please contact Paul Sherwood p.sherwood@dl.ac.uk.

back to top

 Quick links





Modelling Superoxide Dismutases
Crystal Polymorph Prediction
Modelling powders
Diffusion at Grain Boundaries
Paul Sherwoood
Bill Smith
Laurence Ellison
John Purton
C.W. Yong
Michael Seaton
Tom Keal
Rick Anderson
Sebastian Metz
Ilian Todorov