docs/how-to/topology.rst

   1 .. _gmx_add_residue:
   2
   3
   4 Adding a Residue to a Force Field
   5 ---------------------------------
   6
   7 Adding a new residue
   8 ^^^^^^^^^^^^^^^^^^^^
   9
  10 If you have the need to introduce a new residue into an existing force field so that you can
  11 use :ref:`pdb2gmx <gmx pdb2gmx>`, or modify an existing one, there are several files you will
  12 need to modify. You must consult the :doc:`/reference-manual/index/` for description of the required format. Follow these steps:
  13
  14 #. Add the residue to the :ref:`rtp` file for your chosen force field. You might be able to copy
  15    an existing residue, rename it and modify it suitably, or you may need to use an external
  16    topology generation tool and adapt the results to the :ref:`rtp` format.
  17 #. If you need hydrogens to be able to be added to your residue, create an entry in the relevant :ref:`hdb` file.
  18 #. If you are introducing new atom types, add them to the ``atomtypes.atp`` and ``ffnonbonded.itp`` files.
  19 #. If you require any new bonded types, add them to ``ffbonded.itp``.
  20 #. Add your residue to ``residuetypes.dat`` with the appropriate specification (Protein, DNA, Ion, etc).
  21 #. If the residue involves special connectivity to other residues, update ``specbond.dat``.
  22
  23 Note that if all you are doing is simulating some weird ligand in water, or some weird ligand
  24 with a normal protein, then the above is more work than generating a standalone :ref:`itp`
  25 file containing a ``[moleculetype]`` (for example, by modifying the :ref:`top` produced by some
  26 parameterization server), and inserting an ``#include`` of that :ref:`itp` file into a :ref:`top`
  27 generated for the system without that weird ligand.
  28
  29 Modifying a force field
  30 ^^^^^^^^^^^^^^^^^^^^^^^
  31
  32 Modifying a force field is best done by making a full copy of the installed forcefield directory and
  33 ``residuetypes.dat`` into your local working directory::
  34
  35     cp -r $GMXLIB/residuetypes.dat $GMXLIB/amber99sb.ff .
  36
  37 Then, modify those local copies as above. :ref:`pdb2gmx <gmx pdb2gmx>` will then find both the original
  38 and modified version and you can choose the modified version interactively from the list, or if
  39 you use the :ref:`pdb2gmx <gmx pdb2gmx>` ``-ff`` option the local version will override the system version.
  40
  41 .. _gmx-solvate-water:
  42
  43 Water solvation
  44 ---------------
  45
  46 When using :ref:`solvate <gmx solvate>` to generate a box of solvent, you
  47 need to supply a pre-equilibrated box of a suitable solvent for :ref:`solvate <gmx solvate>`
  48 to stack around your solute(s), and then to truncate to give the simulation volume you desire. When
  49 using any 3-point model (e.g. ``SPC``, ``SPC/E`` or ``TIP3P``) you should specify ``-cs spc216.gro``
  50 which will take this file from ``the gromacs/share/top`` directory. Other water models (e.g.
  51 ``TIP4P`` and ``TIP5P``) are available as well. Check the contents of the ``/share/top`` subdirectory
  52 of your GROMACS installation. After solvation, you should then be sure to equilibrate for at
  53 least 5-10ps at the desired temperature. You will need to select the right water model in your
  54 :ref:`top` file, either with the ``-water`` flag to :ref:`pdb2gmx <gmx pdb2gmx>`, or by editing
  55 your :ref:`top` file appropriately by hand.
  56
  57 For information about how to use solvents other than pure water, please see
  58 :ref:`Non-Water Solvation <gmx-solvate-other>` or :ref:`Mixed Solvents <gmx-solvate-mix>`.
  59
  60 .. _gmx-solvate-other:
  61
  62 Non water solvent
  63 -----------------
  64
  65 It is possible to use solvents other than water in |Gromacs|. The only requirements are that you
  66 have a pre-equilibrated box of whatever solvent you need, and suitable parameters for this species
  67 in a simulation.  One can then pass the solvent box to the -cs switch of :ref:`solvate <gmx solvate>` to accomplish solvation.
  68
  69 A series of about 150 different equilibrated liquids validated for use with |Gromacs|,
  70 and for the OPLS/AA and GAFF force fields, can be found at `virtualchemistry <http://virtualchemistry.org/>`_.
  71
  72 Making a non-aqueous solvent box
  73 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  74
  75 Choose a box density and box size. The size does not have to be that of your eventual simulation
  76 box - a 1nm cube is probably fine. Generate a single molecule of the solvent. Work out how much
  77 volume a single molecule would have in the box of your chosen density and size. Use :ref:`editconf <gmx editconf>`
  78 to place a box of that size around your single molecule. Then use :ref:`editconf <gmx editconf>` to move the
  79 molecule a little bit off center. Then use :ref:`genconf <gmx genconf>` ``-rot`` to replicate that box into a large
  80 one of the right size and density. Then equilibrate thoroughly to remove the residual ordering of
  81 the molecules, using NVT and periodic boundary conditions. Now you have a box you can pass to
  82 :ref:`solvate <gmx solvate>` ``-cs``, which will replicate it to fit the size of the actual simulation box.
  83
  84
  85 .. _gmx-solvate-mix:
  86
  87 Mixed solvent
  88 -------------
  89
  90 A common question that new users have is how to create a system with mixed solvent (urea or
  91 DMSO at a given concentration in water, for example). The simplest procedure for accomplishing
  92 this task is as follows:
  93
  94 * Determine the number of co-solvent molecules necessary, given the box dimensions of your system.
  95 * Generate a coordinate file of a single molecule of your co-solvent (i.e., ``urea.gro``).
  96 * Use the ``-ci -nmol`` options of :ref:`gmx insert-molecules` to add the required number of co-solvent molecules to the box.
  97 * Fill the remainder of the box with water (or whatever your other solvent is) using :ref:`gmx solvate` or :ref:`gmx insert-molecules`.
  98 * Edit your :ref:`topology <top>` to ``#include`` the appropriate :ref:`itp` files, as well as make
  99   changes to the ``[ molecules ]`` directive to account for all the species in your system.
 100
 101
 102 Making Disulfide Bonds
 103 ----------------------
 104
 105 The easiest way to do this is by using the mechanism implemented with the ``specbond.dat``
 106 file and :ref:`pdb2gmx <gmx pdb2gmx>`. You may find :ref:`pdb2gmx <gmx pdb2gmx>` ``-ss yes``
 107 is useful. The sulfur atoms will need to be in the same unit that :ref:`pdb2gmx <gmx pdb2gmx>`
 108 is converting to a ``moleculetype``, so invoking :ref:`pdb2gmx <gmx pdb2gmx>` ``-chainsep``'
 109 correctly may be required. See :ref:`pdb2gmx <gmx pdb2gmx>` ``-h``. This requires that the
 110 two sulfur atoms be within a distance + tolerance (usually 10%) in order to be recognised
 111 as a disulfide. If your sulfur atoms are not this close, then either you can
 112
 113 * edit the contents of ``specbond.dat`` to allow the bond formation and do energy
 114   minimization very carefully to allow the bond to relax to a sensible length, or
 115 * run a preliminary EM or MD with a distance restraint (and no disulfide bond)
 116   between these sulfur atoms with a large force constant so that they approach within
 117   the existing ``specbond.dat`` range to provide a suitable coordinate file for a
 118   second invocation of :ref:`pdb2gmx <gmx pdb2gmx>`.
 119
 120 Otherwise, editing your :ref:`top` file by hand is the only option.