docs/user-guide/system-preparation.rst

   1 System preparation
   2 ==================
   3
   4 .. toctree::
   5    :hidden:
   6
   7 There are many ways to prepare a simulation system to run with
   8 |Gromacs|. These often vary with the kind of scientific question being
   9 considered, or the model physics involved. A protein-ligand atomistic
  10 free-energy simulation might need a multi-state topology, while a
  11 coarse-grained simulation might need to manage defaults that suit
  12 systems with higher density.
  13
  14 Steps to consider
  15 -----------------
  16
  17 The following general guidance should help with planning successful
  18 simulations. Some stages are optional for some kinds of simulations.
  19
  20 1. Clearly identify the property or phenomena of interest to be
  21    studied by performing the simulation. Do not continue further until
  22    you are clear on this! Do not run your simulation and then seek to
  23    work out how to use it to test your hypothesis, because it may be
  24    unsuitable, or the required information was not saved.
  25
  26 2. Select the appropriate tools to be able to perform the simulation
  27    and observe the property or phenomena of interest. It is important
  28    to read and familiarize yourself with publications by other
  29    researchers on similar systems. Choices of tools include:
  30
  31    - software with which to perform the simulation (consideration of
  32      force field may influence this decision)
  33
  34    - the force field, which describes how the particles within the
  35      system interact with each other. Select one that is appropriate
  36      for the system being studied and the property or phenomena of
  37      interest. This is a very important and non-trivial step! Consider
  38      now how you will analyze your simulation data to make your
  39      observations.
  40
  41 3. Obtain or generate the initial coordinate file for each molecule to
  42    be placed within the system. Many different software packages are
  43    able to build molecular structures and assemble them into suitable
  44    configurations.
  45
  46 4. Generate the raw starting structure for the system by placing the
  47    molecules within the coordinate file as appropriate. Molecules may
  48    be specifically placed or arranged randomly. Several non-|Gromacs|
  49    tools are useful here; within |Gromacs| :ref:`gmx solvate`,
  50    :ref:`gmx insert-molecules` and :ref:`gmx genconf` solve frequent
  51    problems.
  52
  53 5. Obtain or generate the topology file for the system, using (for
  54    example) :ref:`gmx pdb2gmx`, :ref:`gmx x2top`, `SwissParam
  55    <http://swissparam.ch/>`_ (for CHARMM forcefield), `PRODRG
  56    <http://davapc1.bioch.dundee.ac.uk/cgi-bin/prodrg>`_ (for GROMOS96
  57    43A1), `Automated Topology Builder
  58    <http://compbio.biosci.uq.edu.au/atb/>`_ (for GROMOS96 53A6),
  59    `MKTOP <http://www.aribeiro.net.br/mktop>`_ (for OPLS/AA) or your
  60    favourite text editor in concert with chapter 5 of the |Gromacs|
  61    `Reference Manual`_. For the AMBER force fields, `antechamber
  62    <http://amber.scripps.edu/antechamber/antechamber.html>`__ or
  63    `acpype <https://github.com/choderalab/mmtools/blob/master/converters/acpype.py>`__
  64    might be appropriate.
  65
  66 6. Describe a simulation box (e.g. using :ref:`gmx editconf`) whose
  67    size is appropriate for the eventual density you would like, fill
  68    it with solvent (e.g. using :ref:`gmx solvate`), and add any
  69    counter-ions needed to neutralize the system (e.g. using :ref:`gmx
  70    grompp` and :ref:`gmx insert-molecules`). In these steps you may
  71    need to edit your topology file to stay current with your
  72    coordinate file.
  73
  74 7. Run an :ref:`energy minimization <gmx-energy-min>`
  75    on the system (using :ref:`gmx grompp`
  76    and :ref:`gmx mdrun`). This is required to sort out any bad
  77    starting structures caused during generation of the system, which
  78    may cause the production simulation to crash. It may be necessary
  79    also to minimize your solute structure in vacuo before introducing
  80    solvent molecules (or your lipid bilayer or whatever else). You
  81    should consider using flexible water models and not using bond
  82    constraints or frozen groups. The use of position restraints and/or
  83    distance restraints should be evaluated carefully.
  84
  85 8. Select the appropriate simulation parameters for the equilibration
  86    simulation (defined in :ref:`mdp` file). You need to choose simulation
  87    parameters that are consistent with how force field was
  88    derived. You may need to simulate at NVT with position restraints
  89    on your solvent and/or solute to get the temperature almost right,
  90    then relax to NPT to fix the density (which should be done with
  91    Berendsen until after the density is stabilized, before a further
  92    switch to a barostat that produces the correct ensemble), then move
  93    further (if needed) to reach your production simulation ensemble
  94    (e.g. NVT, NVE). If you have problems here with the system :ref:`blowing
  95    up <blowing-up>`,
  96    consider using the suggestions on that page, e.g. position
  97    restraints on solutes, or not using bond constraints, or using
  98    smaller integration timesteps, or several gentler heating stage(s).
  99
 100 9. Run the equilibration simulation for sufficient time so that the
 101    system relaxes sufficiently in the target ensemble to allow the
 102    production run to be commenced (using :ref:`gmx grompp` and
 103    :ref:`gmx mdrun`, then :ref:`gmx energy` and `trajectory
 104    visualization tools
 105    <http://www.gromacs.org/Documentation/How-tos/Trajectory_Visualization>`_).
 106
 107 10. Select the appropriate simulation parameters for the production
 108     simulation (defined in :ref:`mdp` file). In particular, be careful not
 109     to re-generate the velocities. You still need to be consistent
 110     with how the force field was derived and how to measure the
 111     property or phenomena of interest.
 112
 113 .. _Reference Manual: `gmx-manual-parent-dir`_
 114
 115 Tips and tricks
 116 ---------------
 117
 118 Database files
 119 ^^^^^^^^^^^^^^
 120
 121 The ``share/top`` directory of a |Gromacs| installation contains
 122 numerous plain-text helper files with the ``.dat`` file extension.
 123 Some of the command-line tools (see :doc:`cmdline`) refer to these,
 124 and each tool documents which files it uses, and how they are used.
 125
 126 If you need to modify these files (e.g. to introduce new atom types
 127 with VDW radii into ``vdwradii.dat``), you can copy the file from your
 128 installation directory into your working directory, and the |Gromacs|
 129 tools will automatically load the copy from your working directory
 130 rather than the standard one. To suppress all the standard
 131 definitions, use an empty file in the working directory.