docs/user-guide/system-preparation.rst

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