Introduction

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:

Support for SCF and DFT QM energy and gradients

Parallel MP2 energies and gradients (GA build only)

Excluded MM host and Excluded group options

The fluctuating charge model [1] as implemented by Ben Webb
in CHARMM is supported.

Use ADDL or PATCH commands to add any link atoms, and use the
lone pair facility to set up constraints on the link atom positions
The GAMESS-UK interface supports both the conventional (single) link
atom approach and the double link atom approach suggested by Brooks et
al [2].

Use the GAMESS command, together with an atom selection
to specify which atoms should be included in the Quantum
region, and additional keywords

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":

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:

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).

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

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

(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,

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

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:

adds an atom and renumbers the rest of the PSF accordingly

adds bond terms QQL-MMHost and QQL-QMHost to the PSF

adds an angle term QQL-QMHost-MMHost. (Note that this term will be
removed in a future release as it is no longer needed

Patch the PSF using a patch residue, such as the
following entry in the RTF:

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.

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:

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

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

FLUCQ test case

Building CHARMM/GAMESS-UK

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 GAMESS-UK source code (version 6.3.1 or later) should
be obtained from CFS Ltd and unpacked
into the $CHMROOT/source/gukint.

If the platform is one that is supported by the interface (see
the table below) you can simply add the U option to install.com and
the GAMESS-UK libraries should be compiled and linked in
automatically.

The MPI version of GAMESS-UK should be built if the "M" option
is passed to install.com. This provides a reasonable degree of parallelism,
say up to 16 processors.

To activate the GA (Global Array) version of
GAMESS-UK you will need to set the environment variable
CHMGUK_USE_GA to 1.
Some porting work will
probably be needed in most cases. Also provide the M keyword, to
activate MPI parallelism in CHARMM. The GA version used must be one
which works in an MPI setting, generally this means using a tcgmsg-mpi
based implementation. Some examples are provided below.

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.

Notes

there is no longer a ga flag on install.com (cf version 3)

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:

Setenv CHMGUK_USE_GA to 1.

You will need to set CHMGUK_LIBS for all global
array cases (including the names of the GA,MA,tcgmsg libs)

You may need to set some addition GAMESS-UK configuration
options to control the GA build (e.g. scali, myrinet), this
is done using CHMGUK_EXTRA_OPTIONS.

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:

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.

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.

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.

install.com processes build/UNX/Makefile_$chmhost to
build/$chmhost/Makefile, this may insert additional libraries needed for
GAMESS-UK, such as a vendor-provided BLAS library (or additional libraries
specified using the CHMGUK_LIBS variable).
Search for QLIB in install.com. It also includes the GAMESS-UK
libraries (gamessuk.a and dft.a) in the list of libraries to be
loaded. The libraries are held in the lib/$chmhost directory in line
with internal CHARMM libraries.

When install.com issues the make command it
incorporates guk.mk into the list of sub-makefiles, this sets
up the dependencies of the GAMESS-UK libraries on the specific
GAMESS-UK source files and provides the targets to build them.

guk.mk runs the script source/gukint/GAMESS-UK/utilities/charmm_configure,
which performs the processing of the GAMESS-UK Makefiles. This script is
passed a single argment (the charmm host type, all additional logic is
controlled by checking the CHMGUK_* variables and searching
pref.dat is for certain keywords (e.g. FLUCQ).

guk.mk invokes sub-makes in the GAMESS-UK/m4 and GAMESS-UK/dft
directories which should build the libraries.

The code is loaded against gamessuk.a and dft.a in lib/$chmhost
and any additional libraries.

Porting to New Architectures

The following steps are recommended

Check that GAMESS-UK builds and works on the platform
without any charmm options activated. You will need to establish
the keywords fed into the configure command with the help of the
GAMESS-UK documentation, see GAMESS-UK/INSTALL_README/INSTALL
in the first instance. If you plan to run in parallel you must
check the parallel build as well.
You can restrict the build to the "base" build options which will
give you SCF and DFT capabilities.

Check that build/UNX/Makefile_$chmhost contains gukint.mk

Check that source/gukint/GAMESS-UK/utilities/charmm_configure
script generates a correct set of configuration keywords, and modify it
accordingly. As an alternative to adapting the script, you can
hardwire a particular set of options by setting the GHMGUK_OPTIONS
environment variable.

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.

Table of CHARMM versions

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

~

Broken

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

Download

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.