gromacs.setup – Setting up a Gromacs MD run

Individual steps such as solvating a structure or energy minimization are set up in individual directories. For energy minimization one should supply appropriate mdp run input files; otherwise example templates are used.

Warning

You must check all simulation parameters for yourself. Do not rely on any defaults provided here. The scripts provided here are provided under the assumption that you know what you are doing and you just want to automate the boring parts of the process.

User functions

The individual steps of setting up a simple MD simulation are broken down in a sequence of functions that depend on the previous step(s):

topology()
generate initial topology file (limited functionality, might require manual setup)
solvate()
solvate globular protein and add ions to neutralize
energy_minimize()
set up energy minimization and run it (using mdrun_d)
MD_restrained()
set up restrained MD
MD()
set up equilibrium MD

Each function uses its own working directory (set with the dirname keyword argument, but it should be safe and convenient to use the defaults). Other arguments assume the default locations so typically not much should have to be set manually.

One can supply non-standard itp files in the topology directory. In some cases one does not use the topology() function at all but sets up the topology manually. In this case it is safest to call the topology directory top and make sure that it contains all relevant top, itp, and pdb files.

Example

Run a single protein in a dodecahedral box of SPC water molecules and use the GROMOS96 G43a1 force field. We start with the structure in protein.pdb:

from gromacs.setup import *
f1 = topology(protein='MyProtein', struct='protein.pdb', ff='G43a1', water='spc', force=True, ignh=True)

Each function returns “interesting” new files in a dictionary in such a away that it can often be used as input for the next function in the chain (although in most cases one can get away with the defaults of the keyword arguments):

f2 = solvate(**f1)
f3 = energy_minimize(**f2)

Now prepare input for a MD run with restraints on the protein:

MD_restrained(**f3)

Use the files in the directory to run the simulation locally or on a cluster. You can provide your own template for a queuing system submission script; see the source code for details.

Once the restraint run has completed, use the last frame as input for the equilibrium MD:

MD(struct='MD_POSRES/md.gro', runtime=1e5)

Run the resulting tpr file on a cluster.

Functions

The following functions are provided for the user:

gromacs.setup.topology(struct=None, protein='protein', top='system.top', dirname='top', **pdb2gmx_args)

Build Gromacs topology files from pdb.

Keywords:
struct

input structure (required)

protein

name of the output files

top

name of the topology file

dirname

directory in which the new topology will be stored

pdb2gmxargs

arguments for pdb2gmx such as ff, water, ...

Note

At the moment this function simply runs pdb2gmx and uses the resulting topology file directly. If you want to create more complicated topologies and maybe also use additional itp files or make a protein itp file then you will have to do this manually.

gromacs.setup.solvate(struct='top/protein.pdb', top='top/system.top', distance=0.90000000000000002, boxtype='dodecahedron', concentration=0, cation='NA+', anion='CL-', water='spc', with_membrane=False, ndx='main.ndx', mainselection='"Protein"', dirname='solvate', **kwargs)

Put protein into box, add water, add counter-ions.

Currently this really only supports solutes in water. If you need to embedd a protein in a membrane then you will require more sophisticated approaches.

However, you can supply a protein already inserted in a bilayer. In this case you will probably want to set distance = None and also enable with_membrane = True (using extra big vdw radii for typical lipids).

Arguments:
struct : filename

pdb or gro input structure

top : filename

Gromacs topology

distance : float

When solvating with water, make the box big enough so that at least distance nm water are between the solute struct and the box boundary. Set this to None in order to use a box size in the input file (gro or pdb).

boxtype : string

Any of the box types supported by Genbox. If set to None it will also ignore distance and use the box inside the struct file.

concentration : float

Concentration of the free ions in mol/l. Note that counter ions are added in excess of this concentration.

cation and anion : string

Molecule names of the ions. This depends on the chosen force field.

water : string

Name of the water model; one of “spc”, “spce”, “tip3p”, “tip4p”. This should be appropriate for the chosen force field. If no water is requird, simply supply the path to a box with solvent molecules (used by gromacs.genbox()‘s cs argument).

with_membrane : bool

True: use special vdwradii.dat with 0.1 nm-increased radii on lipids. Default is False.

ndx : filename

The name of the custom index file that is produced here.

mainselection : string

A string that is fed to Make_ndx and which should select the solute.

dirname : directory name

Name of the directory in which all files for the solvation stage are stored.

includes : list of additional directories to add to the mdp include path

Note

non-water solvents only work if the molecules are named SOL.

gromacs.setup.energy_minimize(dirname='em', mdp='/sansom/gfio/oliver/Library/python/GromacsWrapper/gromacs/templates/em.mdp', struct='solvate/ionized.gro', top='top/system.top', output='em.pdb', deffnm='em', mdrunner=None, **kwargs)

Energy minimize the system.

This sets up the system (creates run input files) and also runs mdrun_d. Thus it can take a while.

Additional itp files should be in the same directory as the top file.

Many of the keyword arguments below already have sensible values.

Keywords:
dirname

set up under directory dirname [em]

struct

input structure (gro, pdb, ...) [solvate/ionized.gro]

output

output structure (will be put under dirname) [em.pdb]

deffnm

default name for mdrun-related files [em]

top

topology file [top/system.top]

mdp

mdp file (or use the template) [templates/em.mdp]

includes

additional directories to search for itp files

mdrunner

gromacs.run.MDrunner class; by defauly we just try gromacs.mdrun_d() and gromacs.mdrun() but a MDrunner class gives the user the ability to run mpi jobs etc. [None]

kwargs

remaining key/value pairs that should be changed in the template mdp file, eg nstxtcout=250, nstfout=250.

Note

If mdrun_d() is not found, the function falls back to mdrun() instead.

gromacs.setup.MD_restrained(dirname='MD_POSRES', **kwargs)

Set up MD with position restraints.

Additional itp files should be in the same directory as the top file.

Many of the keyword arguments below already have sensible values. Note that setting mainselection = None will disable many of the automated choices and is often recommended when using your own mdp file.

Keywords:
dirname

set up under directory dirname [MD_POSRES]

struct

input structure (gro, pdb, ...) [em/em.pdb]

top

topology file [top/system.top]

mdp

mdp file (or use the template) [templates/md.mdp]

ndx

index file (supply when using a custom mdp)

includes

additional directories to search for itp files

mainselection

`` make_ndx`` selection to select main group [“Protein”] (If None then no canonical index file is generated and it is the user’s responsibility to set tc_grps, tau_t, and ref_t as keyword arguments, or provide the mdp template with all parameter pre-set in mdp and probably also your own ndx index file.)

deffnm

default filename for Gromacs run [md]

runtime

total length of the simulation in ps [1000]

dt

integration time step in ps [0.002]

qscript

script to submit to the queuing system; by default uses the template gromacs.config.qscript_template, which can be manually set to another template from gromacs.config.templates; can also be a list of template names.

qname

name to be used for the job in the queuing system [PR_GMX]

mdrun_opts

option flags for the mdrun command in the queuing system scripts such as “-stepout 100”. [“”]

kwargs

remaining key/value pairs that should be changed in the template mdp file, eg nstxtcout=250, nstfout=250 or command line options for grompp` such as ``maxwarn=1.

In particular one can also set define and activate whichever position restraints have been coded into the itp and top file. For instance one could have

define = “-DPOSRES_MainChain -DPOSRES_LIGAND”

if these preprocessor constructs exist. Note that there must not be any space between “-D” and the value.

By default define is set to “-DPOSRES”.

Returns:

a dict that can be fed into gromacs.setup.MD() (but check, just in case, especially if you want to change the define parameter in the mdp file)

Note

The output frequency is drastically reduce for position restraints runs by default. Set the corresponding nst* variables if you require more output.

gromacs.setup.MD(dirname='MD', **kwargs)

Set up equilibrium MD.

Additional itp files should be in the same directory as the top file.

Many of the keyword arguments below already have sensible values. Note that setting *mainselection*=``None`` will disable many of the automated choices and is often recommended when using your own mdp file.

Keywords:
dirname

set up under directory dirname [MD]

struct

input structure (gro, pdb, ...) [MD_POSRES/md_posres.pdb]

top

topology file [top/system.top]

mdp

mdp file (or use the template) [templates/md.mdp]

ndx

index file (supply when using a custom mdp)

includes

additional directories to search for itp files

mainselection

make_ndx selection to select main group [“Protein”] (If None then no canonical index file is generated and it is the user’s responsibility to set tc_grps, tau_t, and ref_t as keyword arguments, or provide the mdp template with all parameter pre-set in mdp and probably also your own ndx index file.)

deffnm

default filename for Gromacs run [md]

runtime

total length of the simulation in ps [1000]

dt

integration time step in ps [0.002]

qscript

script to submit to the queuing system; by default uses the template gromacs.config.qscript_template, which can be manually set to another template from gromacs.config.templates; can also be a list of template names.

qname

name to be used for the job in the queuing system [MD_GMX]

mdrun_opts

option flags for the mdrun command in the queuing system scripts such as “-stepout 100 -dgdl”. [“”]

kwargs

remaining key/value pairs that should be changed in the template mdp file, eg nstxtcout=250, nstfout=250 or command line options for grompp` such as ``maxwarn=1.

Returns:

a dict that can be fed into gromacs.setup.MD() (but check, just in case, especially if you want to change the define parameter in the mdp file)

Helper functions (mainly of use to developers):

gromacs.setup.make_main_index(struct, selection='"Protein"', ndx='main.ndx', oldndx=None)

Make index file with the special groups.

This routine adds the group __main__ and the group __environment__ to the end of the index file. __main__ contains what the user defines as the central and most important parts of the system. __environment__ is everything else.

The template mdp file, for instance, uses these two groups for T-coupling.

These groups are mainly useful if the default groups “Protein” and “Non-Protein” are not appropriate. By using symbolic names such as __main__ one can keep scripts more general.

Returns:

groups is a list of dictionaries that describe the index groups. See gromacs.cbook.parse_ndxlist() for details.

Arguments:
struct : filename

structure (tpr, pdb, gro)

selection : string

is a make_ndx command such as "Protein" or r DRG which determines what is considered the main group for centering etc. It is passed directly to make_ndx.

ndx : string

name of the final index file

oldndx : string

name of index file that should be used as a basis; if None then the make_ndx default groups are used.

This routine is very dumb at the moment; maybe some heuristics will be added later as could be other symbolic groups such as __membrane__.

gromacs.setup._setup_MD(dirname, deffnm='md', mdp='/sansom/gfio/oliver/Library/python/GromacsWrapper/gromacs/templates/md_OPLSAA.mdp', struct=None, top='top/system.top', ndx=None, mainselection='"Protein"', qscript='/sansom/gfio/oliver/Library/python/GromacsWrapper/gromacs/templates/local.sh', qname=None, mdrun_opts='', budget=None, walltime=0.33333333333333331, dt=0.002, runtime=1000.0, **mdp_kwargs)

Generic function to set up a mdrun MD simulation.

See the user functions for usage.

Table Of Contents

Previous topic

gromacs.cbook – Gromacs Cook Book

Next topic

gromacs.qsub – utilities for batch submission systems

This Page