Tutorial - Introduction

Introduction

The examples in this tutorial focus on preparing inputs for LAMMPS, as this is what the package was initially written for, however, most of the components of TopoTools have been written in a very generic way and thus can be used for other cases as well. Specific backend scripts may need to be written. This tutorial assumes that have at least TopoTools version 1.4 installed. This version is part of VMD version 1.9.2; if you have an older VMD, you can try to upgrade your TopoTools package with a newer version from this web page, however an upgrade to VMD 1.9.2 is recommended due to corrections for bugs that are triggered by TopoTools.

If you have further questions, contact me at akohlmey@gmail.com.TopoTools calling conventions

Most of the functionality of the plugin is accessible via the topo command that acts as an interface to the individual implemented low-level functions. To get a summary of the available options interactively, type topo help or topo without any options.

topo somecommand someargument someotherargument [...] [-sel ] [-mol |top]

For high-level "convenience" functions that use combinations frequently use lower level script commands to perform specific and frequently used tasks, the syntax it usually either:

::TopoTools::somecommand someargument someotherargument

or

namespace import TopoTools::* ;# only needed once per script

somecommand someargument someotherargument [...]

Building data files for use with LAMMPS

The LAMMPS MD simulation package has no internal tools to build systems of bonded atoms or other complex structures. Instead it requires preparing a so-called data file with information about the atoms in the system (atom types, masses, charges, coordinates, bond definitions and types, angles, dihedreals and so on). For "bio-systems" the most direct way to get the data file is usually to use the topology building tools of a simulation package like Amber, CHARMM or NAMD and then convert this to a data file with the tools provided with the LAMMPS package. In those cases, the individual tools are very well suited for those systems but cannot be easily extended for more general systems. The specific format of the data file has several restrictions that make it inconvenient to write it in a text editor from scratch for all by the most trivial systems. This is where the TopoTools plugin aims to help by providing abstract scriptable functions that help to automate the process and thus eliminate the risk of typos or the need for writing a custom program for each new system. A typical scenario would be to generate a data file when a software like Packmol is used to generate the starting coorrdinates for systems of groups of identical monomers. To write a LAMMPS data file, you have to know which atom style is going to be used in the input. By default full is assumed, since this is compatible with most types of simulations.

topo writelammpsdata data.mysystem molecular

What else is needed to run an MD simulation with LAMMPS?

The data files created by TopoTools don't contain any potential parameters or pair/bond/angle/dihedral style definitions. Those have to be generated in addition, however, the generated data files contain comments that match the symbolic type names with the corresponding numeric definitions, which helps in writing those input segment. In many cases, this can be easily scripted, too.

Building .xml files for use with HOOMD-blue

Generating .xml files to be used with the HOOMD-blue GPU MD code is fairly straightforward. As of VMD version 1.9, it ships on several platforms with a suitable plugin, you can also compile and install by yourself for older versions of VMD using the source available elsewhere on this site, and then you can write out coordinates just like for other VMD-supported file formats, either from the GUI File dialog or from script with:

animate write hoomd mysystem.xml

What else is needed to run an MD simulation with HOOMD-blue?

Same as for LAMMPS, the .xml file only contains the system topology information and the sytem coordinates. Parameters are set in a similar manner from an input script, only that HOOMD-blue uses a customized python interpreter.

Building .psf files for use with VMD and NAMD

In many cases it is much more convenient to use symbolic names for atom types in for visualization and analysis rather then the numbers that LAMMPS uses internally. For that purpose one can generate a .psf file to be used with dump outputs from LAMMPS. This is especially helpful when using compact binary file formats like .dcd or .xtc that only contain coordinate data and no type or topology information. It also helps to display the correct bonding information instead of relying on VMD's guess functions, that can often fail with LAMMPS dump files. The command to write a .psf file is:

animate write psf myfile.psf

For that to work, you first need to read in your system with a file format that has additional information. The regular text mode dump files or an xyz file will work, but it may be better to read in a LAMMPS data file. For that you have to know which atom style is to be used with it in the input. By default full is assumed.

topo readlammpsdata data.mysystem molecular

What else is needed to run an MD with NAMD?

NAMD typically requires a .psf-file with atom type, charge, mass and bonding information, a .pdb or .coor with the initial coordinates, and a file which matches the topology to the force field parameters. The latter step is a little less flexible than the equivalent step for LAMMPS, since angle, dihedral, and other types are inferred from the atom types and cannot be easily overridden except by assigning new atoms types which otherwise are identical.

Continue to the next part of the tutorial.