From 6be1d47d3a14921fce14d3527a51fd6d36a271e4 Mon Sep 17 00:00:00 2001 From: Mark Abraham Date: Fri, 20 Jan 2017 11:43:43 +0100 Subject: [PATCH] Introduced system preparation section to user guide This gives us somewhere we could document the use and limitations of vdwradii.dat better. Enchanced documentation of solvate and insert-molecules, similarly. Refs #2094 Change-Id: I019948472dfc308c1acd74d4fce271ba4d481ead --- docs/CMakeLists.txt | 3 +- docs/user-guide/index.rst | 1 + docs/user-guide/system-preparation.rst | 130 +++++++++++++++++++++++++ src/gromacs/gmxpreprocess/insert-molecules.cpp | 6 +- src/gromacs/gmxpreprocess/solvate.cpp | 10 +- 5 files changed, 143 insertions(+), 7 deletions(-) create mode 100644 docs/user-guide/system-preparation.rst diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index ec6e4550ef..b4ed183113 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -1,7 +1,7 @@ # # This file is part of the GROMACS molecular simulation package. # -# Copyright (c) 2014,2015,2016, by the GROMACS development team, led by +# Copyright (c) 2014,2015,2016,2017, by the GROMACS development team, led by # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, # and including many others, as listed in the AUTHORS file in the # top-level source directory and at http://www.gromacs.org. @@ -120,6 +120,7 @@ if (SPHINX_FOUND) user-guide/index.rst user-guide/getting-started.rst user-guide/flow.rst + user-guide/system-preparation.rst user-guide/cutoff-schemes.rst user-guide/mdrun-features.rst user-guide/mdrun-performance.rst diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst index df631e5398..625c3d53ac 100644 --- a/docs/user-guide/index.rst +++ b/docs/user-guide/index.rst @@ -20,6 +20,7 @@ For background on algorithms and implementations, see the :maxdepth: 2 getting-started + system-preparation cutoff-schemes mdrun-features mdrun-performance diff --git a/docs/user-guide/system-preparation.rst b/docs/user-guide/system-preparation.rst new file mode 100644 index 0000000000..08e31ca9f7 --- /dev/null +++ b/docs/user-guide/system-preparation.rst @@ -0,0 +1,130 @@ +System preparation +================== + +.. toctree:: + :hidden: + +There are many ways to prepare a simulation system to run with +|Gromacs|. These often vary with the kind of scientific question being +considered, or the model physics involved. A protein-ligand atomistic +free-energy simulation might need a multi-state topology, while a +coarse-grained simulation might need to manage defaults that suit +systems with higher density. + +Steps to consider +----------------- + +The following general guidance should help with planning successful +simulations. Some stages are optional for some kinds of simulations. + +1. Clearly identify the property or phenomena of interest to be + studied by performing the simulation. Do not continue further until + you are clear on this! Do not run your simulation and then seek to + work out how to use it to test your hypothesis, because it may be + unsuitable, or the required information was not saved. + +2. Select the appropriate tools to be able to perform the simulation + and observe the property or phenomena of interest. It is important + to read and familiarize yourself with publications by other + researchers on similar systems. Choices of tools include: + + - software with which to perform the simulation (consideration of + force field may influence this decision) + + - the force field, which describes how the particles within the + system interact with each other. Select one that is appropriate + for the system being studied and the property or phenomena of + interest. This is a very important and non-trivial step! Consider + now how you will analyze your simulation data to make your + observations. + +3. Obtain or generate the initial coordinate file for each molecule to + be placed within the system. Many different software packages are + able to build molecular structures and assemble them into suitable + configurations. + +4. Generate the raw starting structure for the system by placing the + molecules within the coordinate file as appropriate. Molecules may + be specifically placed or arranged randomly. Several non-|Gromacs| + tools are useful here; within |Gromacs| :ref:`gmx solvate`, + :ref:`gmx insert-molecules` and :ref:`gmx genconf` solve frequent + problems. + +5. Obtain or generate the topology file for the system, using (for + example) :ref:`gmx pdb2gmx`, :ref:`gmx x2top`, `SwissParam + `_ (for CHARMM forcefield), `PRODRG + `_ (for GROMOS96 + 43A1), `Automated Topology Builder + `_ (for GROMOS96 53A6), + `MKTOP `_ (for OPLS/AA) or your + favourite text editor in concert with chapter 5 of the |Gromacs| + `Reference Manual`_. For the AMBER force fields, `antechamber + `_ or + `acpype `_ might be + appropriate. + +6. Describe a simulation box (e.g. using :ref:`gmx editconf`) whose + size is appropriate for the eventual density you would like, fill + it with solvent (e.g. using :ref:`gmx solvate`), and add any + counter-ions needed to neutralize the system (e.g. using :ref:`gmx + grompp` and :ref:`gmx insert-molecules`). In these steps you may + need to edit your topology file to stay current with your + coordinate file. + +7. Run an energy minimization on the system (using :ref:`gmx grompp` + and :ref:`gmx mdrun`). This is required to sort out any bad + starting structures caused during generation of the system, which + may cause the production simulation to crash. It may be necessary + also to minimize your solute structure in vacuo before introducing + solvent molecules (or your lipid bilayer or whatever else). You + should consider using flexible water models and not using bond + constraints or frozen groups. The use of position restraints and/or + distance restraints should be evaluated carefully. + +8. Select the appropriate simulation parameters for the equilibration + simulation (defined in .mdp file). You need to choose simulation + parameters that are consistent with how force field was + derived. You may need to simulate at NVT with position restraints + on your solvent and/or solute to get the temperature almost right, + then relax to NPT to fix the density (which should be done with + Berendsen until after the density is stabilized, before a further + switch to a barostat that produces the correct ensemble), then move + further (if needed) to reach your production simulation ensemble + (e.g. NVT, NVE). If you have problems here with the system `blowing + up `_, + consider using the suggestions on that page, e.g. position + restraints on solutes, or not using bond constraints, or using + smaller integration timesteps, or several gentler heating stage(s). + +9. Run the equilibration simulation for sufficient time so that the + system relaxes sufficiently in the target ensemble to allow the + production run to be commenced (using :ref:`gmx grompp` and + :ref:`gmx mdrun`, then :ref:`gmx energy` and `trajectory + visualization tools + `_). + +10. Select the appropriate simulation parameters for the production + simulation (defined in .mdp file). In particular, be careful not + to re-generate the velocities. You still need to be consistent + with how the force field was derived and how to measure the + property or phenomena of interest. + +.. _Reference Manual: `gmx-manual`_ + +Tips and tricks +--------------- + +Database files +^^^^^^^^^^^^^^ + +The ``share/top`` directory of a |Gromacs| installation contains +numerous plain-text helper files with the ``.dat`` file extension. +Some of the command-line tools (see :doc:`cmdline`) refer to these, +and each tool documents which files it uses, and how they are used. + +If you need to modify these files (e.g. to introduce new atom types +with VDW radii into ``vdwradii.dat``), you can copy the file from your +installation directory into your working directory, and the |Gromacs| +tools will automatically load the copy from your working directory +rather than the standard one. To suppress all the standard +definitions, use an empty file in the working directory. diff --git a/src/gromacs/gmxpreprocess/insert-molecules.cpp b/src/gromacs/gmxpreprocess/insert-molecules.cpp index 20fb243157..019327750f 100644 --- a/src/gromacs/gmxpreprocess/insert-molecules.cpp +++ b/src/gromacs/gmxpreprocess/insert-molecules.cpp @@ -3,7 +3,7 @@ * * Copyright (c) 1991-2000, University of Groningen, The Netherlands. * Copyright (c) 2001-2004, The GROMACS development team. - * Copyright (c) 2013,2014,2015,2016, by the GROMACS development team, led by + * Copyright (c) 2013,2014,2015,2016,2017, by the GROMACS development team, led by * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, * and including many others, as listed in the AUTHORS file in the * top-level source directory and at http://www.gromacs.org. @@ -409,8 +409,10 @@ void InsertMolecules::initOptions(IOptionsContainer *options, "inserted molecule is less than the sum based on the van der Waals", "radii of both atoms. A database ([TT]vdwradii.dat[tt]) of van der", "Waals radii is read by the program, and the resulting radii scaled", - "by [TT]-scale[tt]. If radii are not found in the database, those" + "by [TT]-scale[tt]. If radii are not found in the database, those", "atoms are assigned the (pre-scaled) distance [TT]-radius[tt].", + "Note that the usefulness of those radii depends on the atom names,", + "and thus varies widely with force field.", "", "A total of [TT]-nmol[tt] * [TT]-try[tt] insertion attempts are made", "before giving up. Increase [TT]-try[tt] if you have several small", diff --git a/src/gromacs/gmxpreprocess/solvate.cpp b/src/gromacs/gmxpreprocess/solvate.cpp index 93f9ba6c49..2ee48d2fc7 100644 --- a/src/gromacs/gmxpreprocess/solvate.cpp +++ b/src/gromacs/gmxpreprocess/solvate.cpp @@ -3,7 +3,7 @@ * * Copyright (c) 1991-2000, University of Groningen, The Netherlands. * Copyright (c) 2001-2004, The GROMACS development team. - * Copyright (c) 2013,2014,2015,2016, by the GROMACS development team, led by + * Copyright (c) 2013,2014,2015,2016,2017, by the GROMACS development team, led by * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl, * and including many others, as listed in the AUTHORS file in the * top-level source directory and at http://www.gromacs.org. @@ -827,9 +827,11 @@ int gmx_solvate(int argc, char *argv[]) "the solvent molecule is less than the sum of the scaled van der Waals", "radii of both atoms. A database ([TT]vdwradii.dat[tt]) of van der", "Waals radii is read by the program, and the resulting radii scaled", - "by [TT]-scale[tt]. If radii are not found in the database, those" - "atoms are assigned the (pre-scaled) distance [TT]-radius[tt].[PAR]", - + "by [TT]-scale[tt]. If radii are not found in the database, those", + "atoms are assigned the (pre-scaled) distance [TT]-radius[tt].", + "Note that the usefulness of those radii depends on the atom names,", + "and thus varies widely with force field.", + "", "The default solvent is Simple Point Charge water (SPC), with coordinates ", "from [TT]$GMXLIB/spc216.gro[tt]. These coordinates can also be used", "for other 3-site water models, since a short equibilibration will remove", -- 2.11.4.GIT