Input files

Mapping files

Mapping relates atomistic and coarse-grained representations of the system. It is organized as follows: for each molecule type a mapping file is created. When used as a command option, these files are combined in a list separated by a semicolon, e. g. --cg protein.xml;solvent.xml.

Atom labeling and mapping from an all-atom to a united atom representation of a propane molecule.

Each mapping file contains a topology of the coarse-grained molecule and a list of maps. Topology specifies coarse-grained beads and bonded interactions between them. Each coarse-grained bead has a name, type, a list of atoms which belong to it, and a link to a map. A map is a set of weights \(c_{Ii}\) for an atom \(i\) belonging to the bead \(I\). It is used to calculate the position of a coarse-grained bead from the positions of atoms which belong to it. Note that \(c_{Ii}\) will be automatically re-normalized if their sum is not equal to 1, i. e. in the case of a center-of-mass mapping one can simply specify atomic masses. A complete reference for mapping file definitions can be found in Mapping file.

As an example, we will describe here a mapping file of a united atom model of a propane molecule, chemical structure of which is shown in the figure in the introduction. In this coarse-grained model, two bead types (A,B) and three beads (A1, B1, A2) are defined, as shown in the figure above. We will use the centers of mass of the beads as coarse-grained coordinates.

Extracts from the propane.xml file of the tutorial are shown below.

<cg_molecule>
  <name>ppn</name> <!-- molecule name in cg representation -->
  <ident>ppn</ident> <!-- molecule name in atomistic topology -->

  <topology> <!-- topology of one molecule -->
    <cg_beads>
      <cg_bead>  <!-- definition of a coarse-grained bead -->
        <name>A1</name>
        <type>A</type>
        <mapping>A</mapping> <!-- reference to a map -->
          <!-- atoms belonging to this bead -->
        <beads>1:ppn:C1 1:ppn:H4 1:ppn:H5 1:ppn:H6</beads>
      </cg_bead>
      <!-- more bead definitions -->
    </cg_beads>

    <cg_bonded> <!-- bonded interactions -->
      <bond>
        <name>bond</name>
        <beads>
          A1 B1
          B1 A2
        </beads>
      </bond>

      <angle>
        <name>angle</name>
        <beads>
          A1 B1 A2
        </beads>
      </angle>
    </cg_bonded>
  </topology>

  <maps>
    <map> <!-- mapping A -->
      <name>A</name>
      <weights> 12 1 1 1 </weights>
    </map>
    <!-- more mapping definitions -->
  </maps>
</cg_molecule> <!-- end of the molecule -->

An extract from the mapping file propane.xml of a propane molecule. The complete
file can be found in the csg-tutorials/propane/single_molecule tutorial

The name tag indicates the molecule name in the coarse-grained topology. The ident tag must match the name of the molecule in the atomistic representation. In the topology section all beads are defined by specifying bead name (A1, B1, A2), type, and atoms belonging to this bead in the form residue id:residue name:atom name. For each bead a map has to be specified, which is defined later in the maps section. Note that bead type and bead map can be different, which might be useful in a situation when chemically different beads (A1, B1) are assigned to the same bead type. After defining all beads, the bonded interactions of the coarse-grained molecule must be specified in the cg_bonded section. This is done by using the identifiers of the beads in the coarse-grained model. Finally, in the mapping section, the mapping coefficients are defined. This includes a weighting of the atoms in the topology section. In particular, the number of weights given should match the number of beads.

Verification of a mapping

Note that the ident tag should match the molecule name in the reference system. A common mistake occurs when beads have wrong names. In this case, the tool csg_dump can be used in order to identify the atoms which are read in from a topology file .tpr. This tool displays the atoms in the format residue id:residue name:atom name. For multicomponent systems, it might happen that molecules are not identified correctly. The workaround for this case is described in Advanced topology handling.

To compare coarse-grained and atomistic configurations one can use a standard visualization program, e. g. vmd. When comparing trajectories, one has to be careful, since vmd opens both a .gro and .trr file. The first frame is then the .gro file and the rest is taken from the .trr file. The coarse-grained trajectory contains only the frames of the trajectory. Hence, the first frame of the atomistic run has to be removed using the vmd menu.

Advanced topology handling

A topology is completely specified by a set of beads, their types, and a list of bonded interactions. VOTCA is able to read topologies in the GROMACS.tpr format. For example, one can create a coarse-grained topology based on the mapping file and atomistic GROMACS topology using csg_gmxtopol.

csg_gmxtopol --top topol.tpr --cg propane.xml --out out.top

In some cases, however, one might want to use a .pdb, H5MD or .dump file which does not contain all the required atomistic topology information. In this case, additional information can be supplied in the XMLmapping file.

A typical example is lack of a clear definition of molecules, which can be a problem for simulations with several molecules with multiple types. During coarse-graining, the molecule type is identified by a name tag as names must be clearly identified. To do this, it is possible to read a topology and then modify parts of it. The new XML topology can be used with the --tpr option, as any other topology file.

For example, if information about a molecule is not present at all, a XML topology file can be created from a .pdb file as follows

<topology base="snapshot.pdb">
  <molecules>
    <clear/>
    <define name="mCP" first="1" nbeads="52" nmols="216"/>
  </molecules>
</topology>

where <clear> clears all information that was present before.

Old versions of GROMACS did not store molecule names. In order to use this feature, a recent .tpr file containing molecule names should always be provided. For old topologies, rerun GROMACS grompp to update the old topology file.

If molecule information is already present in the parent topology but molecules are not named properly (as is the case with old GROMACS.tpr files), one can rename them using

<topology base="topol.tpr">
  <molecules>
    <rename name="PPY3" range="1:125"/>
    <rename name="Cl" range="126:250"/>
  </molecules>
</topology>

Here, the file topol.tpr is loaded first and all molecules are renamed afterwards.

If you do not have a .pdb/.gro file and you want to read trajectories from a LAMMPS .dump file or H5MD file then it is also possible to directly define the topology in a XML file. Here is an example of a XML file where the trajectory is read from a H5MD file:

<topology>
  <!-- particle group name in H5MD file -->
  <h5md_particle_group name="atoms" />
  <molecules>
    <!-- define molecule, number of beads, number of mols -->
    <molecule name="BUT" nmols="4000" nbeads="4">
      <!-- composition of molecule, bead definition -->
      <bead name="C1" type="C" mass="15.035" q="0.0" />
      <bead name="C2" type="C" mass="14.028" q="0.0" />
      <bead name="C3" type="C" mass="14.028" q="0.0" />
      <bead name="C4" type="C" mass="15.035" q="0.0" />
    </molecule>
  </molecules>
  <!-- bonded terms -->
  <bonded>
    <bond>
      <name>bond1</name>
      <beads>
        BUT:C1 BUT:C2
      </beads>
    </bond>
    <bond>
      <name>bond2</name>
      <beads>
        BUT:C2 BUT:C3
      </beads>
    </bond>
    <angle>
      <name>angle1</name>
      <beads>
        BUT:C1 BUT:C2 BUT:C3
        BUT:C2 BUT:C3 BUT:C4
      </beads>
    </angle>
    <dihedral>
      <name>dihedral1</name>
      <beads>
        BUT:C1 BUT:C2 BUT:C3 BUT:C4
      </beads>
    </dihedral>
  </bonded>
</topology>

The list of molecules is defined in section molecules where every molecule is replicated nmols times. Inside molecule, the list of bead has to be defined with the name, type, mass and charge.

The box size can be set by the tag box:

<box xx="6.0" yy="6.0" zz="6.0" />

where xx, yy, zz are the dimensions of the box.

A complete reference for a XML topology file can be found in Topology file.

Trajectories

A trajectory is a set of frames containing coordinates (velocities and forces) for the beads defined in the topology. VOTCA currently supports .trr, .xtc, .pdb, .gro and H5MD .h5 trajectory formats.

Once the mapping file is created, it is easy to convert an atomistic to a coarse-grained trajectory using csg_map.

csg_map --top topol.tpr --trj traj.trr --cg propane.xml --out cg.gro

The program csg_map also provides the option --no-map. In this case, no mapping is done and csg_map instead works as a trajectory converter. In general, mapping can be enabled and disabled in most analysis tools, e.g. in csg_stat or csg_fmatch.

Note, the topology files can have different contents as bonded interactions are not provided in all formats. In this case, mapping files can be used to define and relabel bonds.

Also note, the default settings concerning mapping varies individually between the programs. Some have a default setting that does mapping (such as csg_map, use --no-map to disable mapping) and some have mapping disabled by default (e.g. csg_stat, use --cg to enable mapping).

Setting files

<cg>
  <non-bonded> <!-- non-bonded interactions -->
    <name>A-A</name> <!-- name of the interaction -->
    <type1>A</type1> <!-- types involved in this interaction -->
    <type2>A</type2>
    <min>0</min>  <!-- dimension + grid spacing of tables-->
    <max>1.36</max>
    <step>0.01</step>
    <inverse>
      ... specific commands
    </inverse>

    ... specific section for inverse boltzmann, force matching etc.
  </non-bonded>
</cg>

Abstract of a settings.xml file. See secs. Program input, Three-body Stillinger-Weber interactions or Preparing the run for full versions.

A setting file is written in the format .xml. It consists of a general section displayed above, and a specific section depending on the program used for simulations. The setting displayed above is later extended in the sections on iterative boltzmann inversion (csg_inverse), force matching (csg_fmatch) or statistical analysis (csg_stat).

Generally, csg_stat is an analysis tool which can be used for computing radial distribution functions and analysing them. As an example, the command

csg_stat --top topol.tpr --trj traj.xtc --options settings.xml

computes the distributions of all interactions specified in settings.xml and writes all tabulated distributions as files interaction name.dist.new. A mapping file can be provided with the option --cg.

When calculating the angular distribution, an additional option <threebody> has to be added to the settings file. For example, the settings.xml file for calculating the angular distribution between three beads of type A which are all within a cutoff distance of 0.37 (nm) might look like:

<cg>
  <non-bonded> <!-- non-bonded interactions -->
    <name>A-A-A</name> <!-- name of the interaction -->
    <threebody>true</threebody> <!-- is a three-body interaction -->
    <type1>A</type1> <!-- types involved in this interaction -->
    <type2>A</type2>
    <type2>A</type2>
    <!-- dimension + grid spacing of tables-->
    <min>0</min> <!--minimum angle in radians -->
    <max>3.14</max> <!-- maximum angle in radians -->
    <step>0.02</step>
    <cut>0.37</cut>
  </non-bonded>
</cg>

In addition to distribution functions, csg_stat can also calculate the pair potential of mean force (PMF) for non-bonded pairs:

\[U_{\text{PMF}}\left(r\right)= - \int_0^r \, F_{\text{rad}}\left(r^\prime\right)\,\text{d}r^\prime.\]

The output file name is then interaction name.force.new. Here, \(F_{\text{rad}}\left(r\right)\) is the total force acting on a bead projected onto the unit distance vector connecting this pair of beads. The settings file has to contain the additional option:

<cg>
  <non-bonded> <!-- non-bonded interactions -->
    <name>A-A</name> <!-- name of the interaction -->
    <type1>A</type1> <!-- types involved in this interaction -->
    <type2>A</type2>
    <min>0</min>  <!-- dimension + grid spacing of tables-->
    <max>1.36</max>
    <step>0.01</step>
    <force>true</force>  <!-- calculate pair PMF for this interaction -->
  </non-bonded>
</cg>

Table formats

In the iterative framework distribution functions, potentials and forces are returned as tables and saved in a file. Those tables generally have the format

x y [error] flag

where x is input quantity (e.g. radius \(r\), angles \(\theta\) or \(\phi\)), y is the computed quantity (e.g. a potential) and [error] is an optional error for y. The token flag can take the values i, o or u. In the first case, i (in range) describes a value that lies within the data range, o (out of range) symbolises a value out of the data range and u stands for an undefined value.

The token flag will be important when extrapolating the table as described in Post-processing of the potential.

For historical reasons, csg_boltzmann uses a slightly different table format, it has no flag column and uses the third column as a force column when outputting a potential.