Installation

FESetup Installation
Linux, Intel 32bit and 64bit
1. Run the installer package from Releases in a convenient location (N will stand for the release
you have downloaded). You can run the installer with "--help" to see further options. Here we
describe interactive installation i.e. without any command line options. The installer requires
the xz compression tool to be installed on your system.

2. >cd/where/I/want/it

#replacethepathtowhateveryou

like
3. >./FESetupN_Linux.sh#extractallfilesintoFESetupN/
The installer will automatically detect which version to extract (either 32 or 64 bit). You will be
asked to provide paths to AMBER, GROMACS, NAMD and DL_POLY. It is strongly
recommended to choose 'N' (the default, so just press Enter) if the first question suggests to
use your existing $AMBERHOME. Choose the internal path as suggested in the following
question to avoid modifications to the original AmberTools installation. Press Enter to accept
defaults or to set an empty path if you do not have a certain MD package. You will also be
asked for a Python 2.7 interpreter (the default is "python", assumed to be found in $PATH but
read the note below). You will find the FESetup script in ./FESetupN/FesetupMM/bin (MM is
either 32 or 64 depending on your hardware) after successful installation.
4. Check that FESetup is working. You can do this by running the test set from our first tutorial or
just run the FESetup script without any command line parameters. This will write the default
input parameters to your terminal.
5. You can copy/link the FESetup script to your PATH e.g. /usr/local/bin if you like, or point an alias
to the script.

Our packages are self-contained and come with all relevant tools from AmberTools 16 including
sander (pmemd still requires a full AMBER license). To carry out standard MD simulations, in particular
equilibration of your system, the abstract MD engine supports AMBER (both sander and

pmemd), NAMD, GROMACS and DL_POLY. Please note that currently we do not directly support
NAMD's alchemical free energy methods though there is support for dual topology runs with AMBER
inputs in NAMD (an additional PDB file is required to designate appearing/vanishing atoms, see NAMD
manual). Standard MD is supported for NAMD.

Also note that you should use the standard Python interpreter (e.g. the one that comes as a
package with your OS distribution or you download and compile from python.org). Python versions
that come with a package management systems of their own may break the assumptions that our
installer makes with regards to shared libraries. Specifially, anaconda appears to mess with the library
search path and seems to disregard the setup in the FESetup script.

MacOSX, Intel 64bit

There is currently no installer but only an XZ archive in Releases which needs to be extracted. The
current version has been compiled on MacOSX 10.8.5. NB: Please get in touch with the maintainer if
you observe any problems with this version.

>tarxfvFESetup1.2_MacOSX_64.tar.xz

This assumes that you have the xz tool installed on your system. Then follow instructions starting from
point 2 in Linux above.

Windows, etc.
Download the virtual machine image and extract it. The OVA file needs to be imported into VirtualBox,
VMWare, etc.

User:fesetup
Password:fesetup(samefortherootuser).

Activate the shared folder facility according to the documentation of you virtual machine software.
The local directory shared can so be connected to the host system (use also shared for the folder, but
it can be located anyware).

After login follow the instructions starting from point 2 in Linux above.

A build for release 1.1 is also available for BlueGene (Power7, PPC64) in an XZ archive (see MacOSX
above), see Releases.

Updates
Bug fixes for the current release will be made available when necessary through subversion.

>cd$FES_HOME/FESetupMM/lib/python2.7/sitepackages/FESetup
>svnupdate

In case you have a subversion that is older than what the developers use you may get a message that
says that you need to upgrade subversion. However, there is a simpler workaround as follows (MM has
been replaced here with the current release number).

>cd$FES_HOME/FESetup1.1/lib/python2.7/sitepackages/
>mvFESetupFESetup.old
>svncousernameanonymous
http://ccpforge.cse.rl.ac.uk/svn/ccpbiosim/FESetup/tags/release1.2
FESetup

Releases will be made availbale from time to time depending on how many features have been
implemented at a certain time and how stable the code appears.

The adventurous user can update the FESetup source to the latest development version through svn
at any time

>cd$FES_HOME/FESetupMM/lib/python2.7/sitepackages/
>mvFESetupFESetup.old
>svncousernameanonymous
http://ccpforge.cse.rl.ac.uk/svn/ccpbiosim/FESetup/trunkFESetup

Note: Although I try to always check-in a working version this may not always be true. Also, the
newest version may have bugs, have less functionality, etc. I do not guarantee proper
functioning after update to the latest development tree.

Dependencies
FESetup depends on various third-party software. All of these are included in the installer package.
Here a list of dependencies for those who want to compile everything themselves. Not listed are some
dependencies which can be installed through the operating sytem's package managment. Some
secondary dependencies are listed too. Debian based systems have most libraries, toolkits and tools
pre-compiled and ready to install through the package managment system.

Python 2.7

Sire/corelib 0.0.1, Sire/Python2 0.0.1: Qt4, Boost, GSL, BLAS/LAPACK, pcre3

Ambertools 16

OpenBabel 2.3.x: eigen, swig, xml2

RDKit 2016: numpy, Boost

Manual

Manual for FESetup (dGprep.py)

Note: this describes options used as of Release 1.2

Command line

Default values of all keyvalue pairs in all four section are written to stdout when dGprep.py is called
without parameters. Calling dGPrep with '--help' gives information of all possible command line
parameters. There are none of relevance at the moment.

>FESetuphelp

usage:dGprep.py[h][tracebacklimitTRACEBACKLIMIT][infile]

positionalarguments:<p>Thisimpliesthatfilenamescannothavethequote
'&quot;'&quot;characterinfilenames.</p>
infileinputfileinINIformat,ifnotgiventhenjust
outputdefaults

optionalarguments:
h,helpshowthishelpmessageandexit
tracebacklimitTRACEBACKLIMIT

setthePythontracebacklimit

Input format

The input format to dGprep.py is an INI style format. It is not exactly the same (we do not use
ConfigParser) but a simplified version.

The input file may contain four sections where the section names are delimited with brackets:

The four sections of the INI file

[globals]

global settings, the section name is optional if it is the first section in the file

[ligand]

settings for the ligand

[protein]

settings for the protein

[complex]

settings for the complex

Each section consists of various key-value pairs which are two strings separated with an equal sign
("="). The key must not contain any whitespace.

#atypicalkeyvaluepair
morph_pairs=paminophenol>ocresol

Lines may be continued with an initial whitespace on the following line:

#multiplecontinuationlines
morph_pairs=ethane>methanol,ethane>tbutane,ethane>propane,
tbutane>propane,tbutane>acetone,
propane>acetone,propane>methane

However, list pairs must always appear on the same line because each line is parsed individually. So
the following will cause an error.

#thiswillresultinanerror
morph_pairs=ethane>methanol,ethane>tbutane,ethane>
propane,#thestring"propane"mustappearintheprevious
line!

Comments are either empty lines or lines starting with '#' or ';' (leading whitespace is removed). Inline
comments are allowed too provided the comment character is preceded by a space. Otherwise the
string is part of the preceding string, e.g.

basedir=smallmols#thisisaninlinecomment
basedir=smallmol#foo#thevalidstringanddirectoryname
'smallmol#foo'

Explicit tagging mechanism

In some cases it may be necessary to explicitly map certain atoms to one another, that is the default
mapping algorithm (maximum common substructure search) can be given additional hints.

[ligand]
basedir=smallmols
morph_pairs=benzol>benzofuran/1=3/2=2

An alternative mechanism is to be create a special file in basedir (as set in the [ligand] section). The
name of the file must be in the form ligand1~ligand2.map, e.g. if the input reads

[ligand]
basedir=smallmols
morph_pairs=benzol>benzofuran
then the map file must be in smallmols i.e. smallmols/benzol~benzofuran.map .
The map file has a two column format indicating which atom index in the initial state maps to which
atom index in the final state. Atom indexes start from 1.

#examplemappingfilebenzol~benzofuran.mapinthebasedirsmallmols/
#explicitlymapthefollowingatomindexesontoeachother
13#thismappingand...
22#...thisonefixtheorientationofbenzofuraninspace

Full option list

The following table lists all options unique to each section. Note that empty strings (denoted as 'none'
in the table) means that the user has to use appropriate values. 'molecules' will be overwritten when

'morph_pairs' are used in [ligand]. The default for complex building is to combine each protein with
each ligand. If you do no want that, you must explicitly list all 'pairs'. Please note that your file and
directory names must not contain the characters ':' (colon), '>' (right angle bracket), '"' (double
quote) and '~' (tilde). The comma ',' is permited as long as the filename is enclosed in double quotes,
e.g.

morph_pairs="1,2dichloroethane">Edichloroethene,
Edichloroethene>"1,2dichloroethane"

Options unique to each section

Key

Values, default in bold

Type

Explanation

[globals]
Sire, sander/dummy, sander/softcore,

free energy type, for backwards compatibility

AFE.type (previously

pmemd/softcore, pmemd/dummy,

FE_type)

gromacs, charmm/pert

string

AMBER = sander/dummy and AMBER/softcore

= sander/softcore

(experimental!)
separate the Coulomb (charge) transformation
AFE.separate_vdw_elec

True, False

bool
from the vdW+bonded transformation
list of

forcefield

amber, ff14SB, tip3p, hfe

ff family, subtyp of ff, water ff, divalent ion set

strings

ff_addons

list of

additional for fields like GLYCAM_06j-1 or

strings

lipid14

empty

Choice for the small molecules forcefield, either

gaff

gaff1, gaff2

strings
GAFF 1.x or GAFF2.x

logfile

dGprep.log

string

name of the debug log

mdengine

amber, sander

list of 2

program for minimisation and MD, the first in the

strings

list is the MD package, the second is the actual

binary; e.g. gromacs, mdrun or namd,

namd2 or amber, pmemd.MPI
the string preceding the mdengine binary
mdengine.prefix

empty

string
command, e.g. mpirun -np 4 (for MPI programs)
the string following the mdengine binary

mdengine.postfix

empty

string

command, e.g. +p2 +isomalloc_sync (for namd

multicore)

parmchk_version

2, 1

integer

parmchk version

mcs.timeout

60.0

float

timeout in seconds for fmcs, 0 means no timeout

remake

False, True

bool

remake already done molecules (excluding

morphs)
by default no files are ever overwritten in the _
overwrite

False, True

bool
directories, use this to change this behaviour
read user force fied parameter files, i.e. all

user_params

False, True

bool

*.frcmod, *.prep and *.lib (OFF format) files are

read in

[ligand]
basedir

none, must be set by user

string

base directory to find ligands

file.name

ligand.pdb

string

ligand input file name

none, determined from extension of

file.format

format of file.name, used to overwrite if file

string

file.name

extension is different from actual file format

ions.conc

0.0

float

ions.dens

1.0

float

sets the NaCl concentration

the density for which the ion concentration is
wanted

calc_charge

False, True

bool

Force calculation of molecule's formal charge,

required e.g. for mol2 format for which

Openbabel computes the charge only in select
cases.
conf_search.conj_econv

1e-06

float

conformation search option

conf_search.conj_steps

250

integer

conformation search option

conf_search.ffield

mmff94

string

conformation search option

conf_search.geomsteps

integer

conformation search option

conf_search.numconf

integer

conformation search option

conf_search.steep_econv

0.0001

float

conformation search option

conf_search.steep_steps

100

integer

conformation search option

molecules

none, must be set by user

list of
list of molecules
strings
write absolute transformation MORPH.pert files
morph.absolute

False, True

bool
for Sire

morph_pairs

list of

list of pairs in the form lig1 > lig2, overwrites

strings

'molecules', do not use '>' in file names

none, must be set by user

neutralize the solvation box by adding minimum

neutralize

False, True

bool
couterions required
skip the parameterisation step, useful in

skip_param

False, True

bool

conjunction with user_params or ff_addons see

[globals]

[protein]
align complex along principal axes before
align_axes

False, True

bool
hydrating

basedir

none, must be set by user

string

base directory to proteins

ions.conc

0.0

float

ions.dens

1.0

float

sets the NaCl concentration

the density for which the ion concentration is
wanted

list of
molecules

none, must be set by user

list of molecules
strings
neutralize the solvation box by adding minimum

neutralize

False, True

bool
couterions required

propka

False, True

bool

use ProPKA to protonate protein

propka.pH

7.0

float

pH for ProPKA

False, True

bool

[complex]
align complex along principal axes before
align_axes

hydrating
ions.conc

0.0

float

ions.dens

1.0

float

sets the NaCl concentration

the density for which the ion concentration is
wanted
neutralize the solvation box by adding minimum

neutralize

False, True

bool
couterions required
make aromatic rings fully planar, for MC with

flatten_rings

False, True

bool
Sire

pairs

list of

list of pairs in the form prot :lig, do not use ':' in

strings

file names

none, must be set by user

The following options are the minimsation and MD options for molecule setup common to ligands,
proteins and complexes. To allow minimisation and MD 'box.type' has to be set explicilty which also
creates a water box. It 'box.type' is not set by the user no box will be created and minimisation or MD
will not be possible. To actually run simulation you will need to set any of the '.nstpes' to a value larger
than 0. The only difference is relaxation where setting 'md.relax.nsteps' to values larger than 0 will
trigger restraint relaxation. The order of simulation protocols is heating, constant VT, pressurising,
relaxation. If any of those steps are not needed set '.nstpes' to 0 but be aware that there are no
further sanity checks. The MD protocol can be preceded by a minimisation step.

The minimisation and MD options

Key

Value, defaults

Type

Explanation

string

creates a box of water

rectangular, octahedron, (empty

box.type

string by default = no box

created)

the distance between solute and the box edges, NOTE: the TIP3P
box.length

10.0

float

box will create a system of low density and thus this distance will
decrease on pressuring the sytem.

intege
min.ncyc

number of steepest decent steps (sander)

r

intege
.nsteps

number of steps
r

.restr_force

10.0

float

backbone, heavy, protein,

.restraint

restraint type, if other string then in the list it is the

string

notligand, notsolvent
.T

restraint force

300.0

"restraintmask" for sander

float

temperature

.p

1.0

md.relax.nrest

float

intege
0

pressure

number of relaxation steps

r