Scope and usage

Starting with VMD version 1.8.7 it is now possible to store the complete topology information, i.e. not only bonds, but also angle, dihedral, and improper definitions as well as their force field type labels (if available). This now allows to do a large variety of modifications to topology data or even building topologies from scratch. The focus lies hereby on being able to perform many operations manually or scripted and thus being less focused on and optimized for biomolecules like psfgen.

In combination with the new command mol new atoms <number> it is now also possible to do many operations directly that previously required writing and manipulating temporary files and reading them back into VMD, or even write complete molecule or simulation data readers in Tcl script. This is especially useful for file formats, where additional input from the user is required, for example reading LAMMPS format "data" (=topology) files, where the "style" of theAtoms section cannot be deduced from the data. Of course write support is also possible.

The underlying Tcl script API in VMD itself had been designed to be minimalistic, since most operations are not computationally demanding and could be programmed with scripting. The topotools packages is supposed to provide a middleware, i.e. more powerful and easy to use script commands that make combine multiple low lever commands in a way to solve common tasks conveniently and efficiently.

Finally topotools also contains some utilities and applications for more complex operations like combining multiple molecules (=different files) or multiple selections into one new molecule, or building larger systems by replicating a given unitcell.

Version

This documentation always describes the latest version of topotools available from this homepage.

Main command interface

This is the middleware part of the package that provides abstract operations on top of the low-level API. This is modeled after the example of the internal mol or molinfo commands, or the pbc command from the PBCTools package to provide a somewhat consistent interface to the functionality. All command lines start with the topo keyword and then take a subcommand name to determine the actual functionality that is requested.

Common flags

The following flags can be passed on to all subsequent topo commands. They will select the molecule to which the operation should be applied to and also the set of atoms. The -sel transparently handles both, previously defined selection functions or selection texts, as arguments. For operations on bonds, angles, dihedrals, and impropers selections will be applied in such a way that only topological data where all atoms are contained in the selection.

The following flags can be added to subsequently documented operations on bonds. Bond information is treated and stored differently from angles, dihedrals, and impropers in VMD, since bond information is used for visualization and the others not. This also results in performance differences in commands operating on the two groups.

numatoms

Returns the number of atoms.

numatomtypes

Returns the number of atom types as determined from the type property.

atomtypenames

Returns the list of unique atom types names. The list has topo numatomtypes entries.

guessatom <property> <from>

Resets per atom data through selected heuristics. This is most useful to recover some data when using a file format that doesn't set contain these properties, or when they cannot be reliably determined, so the user should choose which ones work. The following combinations are supported:

• element from mass: this assigns the closest match in the periodic table of elements.
• element from name: the atom name is looked up in the periodic table of elements, if no match is found the first two characters of the name are used and if there is still no match, then only the first character of the name is taken. The lookup is case insensitive since version 1.2 of the plugin.
• element from type: the atom type is looked up in the periodic system of elements in the same way as described for name (added in version 1.2).
• mass from element: the element name is compared against the periodic table of elements (case insensitively) and the mass looked up.
• name from element: the name is set to the element name with all uppercase characters.
• name from type: the atom type is copied to atom name.
• radius from element: the radius is looked up by element name. van-der-Walls radii are used for most elements, ionic radii for elements that are commonly ionic and 2.0 is used for all other elements.
• type from element: the type is set to the element name with all uppercase characters.
• type from name: the atom name is copied to atom type.
• lammps from data: this is a shortcut notation for guessing element from mass and then name and radius from the element. This is a combination that can be applied to many LAMMPS data files.

numbonds

Returns the number of bonds.

numbondtypes

Returns the number of unique bond types.

bondtypenames

Returns a list of all unique bond types. The list has topo numbondtypes entries.

clearbonds

Delete all bonds.

retypebonds

Assign new bond types composed of the atom type strings connected with a '-' character. Bond types are canonicalized so that the atom type with the lower dictionary sort value will be placed on the left and the other on the right.

addbond <id1> <id2>

Defines a bond bone between the two specified atoms. This does nothing if one of the two atom indices is outside the selection. You can specify the bond type and order via the optional flags -bondtype or -bondorder.

delbond <id1> <id2>

Deletes a bond between the two specified atoms. This does nothing if the bond does not exist or one of the two atom indices is outside the selection.

getbondlist [type|order|both|none]

Returns a list of unique bonds, the individual bond is a list of the atom indices forming the bond and optionally added the bond type name and/or the bond order value.

setbondlist [type|order|both|none] <list>

Defines bonds from a list in a format as returned by topo getbondlist. This is essentially a shortcut for calling topo clearbonds and a sequence of topo addbond commands with some optimization for the case of a selection encompassing all atoms.

num(angle|dihedral|improper)s

Returns the number of angles, dihedrals, or impropers.

num(angle|dihedral|improper)types

Returns the number of unique angle-, dihedral-, or improper-types.

(angle|dihedral|improper)typenames

Returns a list of all unique angles, dihedrals, or impropers. The list has topo num(angle|dihedral|improper)types entries.

clear(angle|dihedral|improper)s

Deletes the currently defined angles, dihedrals, or impropers.

sort(angle|dihedral|improper)s

Sorts and canonicalizes the list of angles, dihedrals, or impropers. Duplicates are removed and the list is sorted by atom types.

retype(angle|dihedral|improper)s

Assign new angle, dihedral, or improper types composed of the atom type strings connected with a '-' character. The resulting types are canonicalized and sorted.

guess(angle|dihedral)s

Guess angle or dihedral definitions from the bond topology. An angle is defined by two bonds sharing an atom and a dihedral by two bonds sharing a bond. Types are assigned in the same way as in the corresponging retype command.

guessimproper [tolerance <degrees>]

Guess improper angles. Are defined for atoms that are bonded to exactly 3 atoms when they form a near flat structure. The tolerance flag can be used as a cutoff for what is to be considered as "flat" and what not.

addangle <type> <id1> <id2> <id3>

Defines an angle of type <type> between the three specified atoms. All three atoms have to be contained in the specified atom selection ('all' if none is given) or else the command is ignored. No further checks are being performed on the input.

delangle <id1> <id2> <id3>

Deletes an angle between the three specified atoms. Does nothing if not all three atom indices are contained within the given selection (default 'all').

getanglelist

Returns a list of defined angles with each entry in the format {type <index 1> <index 2> <index 3>}. The type name may be set to {}, if no angletype has been set. The list is printed unsorted as it is stored in VMD.

setanglelist <list>

Resets the angle definitions from a list in a format as returned by topo getanglelist. This is essentially a shortcut for calling topo clearbonds and a sequence of topo addangle commands with some optimization for the case of a selection encompassing all atoms.

adddihedral <type> <id1> <id2> <id3> <id4>

Defines a dihedral or improper of type <type> between the four specified atoms. All four atoms have to be contained in the specified atom selection ('all' if none is given) or else the command is ignored. No further checks are being performed on the input.

deldihedral <idx1> <id2> <id3> <id4>

Deletes the dihedral or improper between the four specified atoms. Does nothing if not all four atom indices are contained within the given selection (default 'all').

addimproper <type> <id1> <id2> <id3> <id4>

Defines a dihedral or improper of type <type> between the four specified atoms. All four atoms have to be contained in the specified atom selection ('all' if none is given) or else the command is ignored. No further checks are being performed on the input.

delimproper <id1> <id2> <id3> <id4>

Deletes the dihedral or improper between the four specified atoms. Does nothing if not all four atom indices are contained within the given selection (default 'all').

get(dihedral|improper)list

Returns a list of defined dihedrals or impropers with each entry in the format {type <index 1> <index 2> <index 3> <index 4>}. The type name may be set to {}, if no type has been set. The list is printed unsorted as it is stored in VMD.

set(dihedral|improper)list <list>

Resets the dihedral or improper definitions from a list in a format as returned by topo getdihedrallist or topo getimproperlist. This is essentially a shortcut notations for clearning and then resetting them individually.

File I/O Commands

TopoTools provides a number of file I/O commands that contrast from the molfile plugins in such that they use Tcl scripting to read and write files. This provides additional flexibility and allows to easily pass flags to the reader or writer, that are not available in the molfile plugin API, however, it may also results in reduced reading performance. All of the file I/O commands also use the topo prefix and support the commonly supported optional flags for specifying molecule id and atom selection.

readlammpsdata <file name> [<atom style>]

Read in atom coordinates, properties, bond, angle, dihedral and other related topology info from a LAMMPS data file, i.e. a file suitable for the read_data command. This can be used to check a data file for its validity (e.g. after using restart2data), for manipulations from within VMD, or to generate a .psf file to be used for visualization of .dcd or .xtc format trajectory files in VMD. The 'atom style' is the value given to the atom_style command in the LAMMPS input file (default is 'full'). This subcommand creates a new molecule in VMD and returns its molecule id or -1 in case of failure. The -sel parameter is currently ignored.

writelammpsdata <file name> [<atom style>]

Write out atom coordinates, properties, bond, angle, dihedral and other related topology info stored inside VMD to a LAMMPS data file, i.e. a file suitable for the read_data command. This this way VMD can be used to build LAMMPS input with Tcl scripting and convert existing inputs from other MD codes to be used in LAMMPS. For some examples, please see the TopoTools tutorials. The 'atom style' is the value you want to give to the atom_style command in the LAMMPS input file (default is 'full'). Only data that is present will be written.

readvarxyz <file name>

Read in an xyz-format trajectory file (in xmol style) with a varying number of atoms per frame. This format is normally not supported in VMD and the script circumvents the restriction by automatically adding a sufficient number of dummy particles. Whether an atom is actually present in a given frame or not is flagged by the value of the corresponding user field, which is set to either 1.0 or -1.0, respectively. For efficiency reasons the atoms are sorted by type, thus atom order and bonding is not preserved. This subcommand creates a new molecule and returns its molecule id or -1, in case of failure.

writevarxyz <file name> [selmod <sel>] [first|last|step <frame]

writegmxtop <file name>

Write a "fake" gromacs topology file that can be used in combination with a .gro or .pdb file to generate a .tpr file, which is needed for some of the more advanced gromacs analysis tools in order to analyze trajectories that were not generated with gromacs. This file is in no way suitable to start a simulation.

Utility Functions

These are useful and convenient tools written on top of the topotools API. You can access them directly with their ::TopoTools:: namespace prefix or use namespace import ::TopoTools::<pattern> to import some or all of them (with the pattern '*') into your current namespace.

mergemols <list of molecule ids>

Combines multiple separate molecules into one file. This is non-destructive and will create a new molecule. The molecule id of the new molecule is returned, or -1 in case of a failure. Usage example:

selections2mol <list of atom selections>

This is very similar to the previous mergemols command. It combines one or multiple atom selections, which can be taken from different molecules, into one new molecule. This is also non-destructive and will create a new molecule. The molecule id of the new molecule is returned, or -1 in case of a failure. Usage example:

replicatemol <mol> <nx> <ny> <nz>

Replicate the current unitcell according to integer replicate counts. This currently assumes an orthorhombic cell. Usage example: