TopoTools

TopoTools is a VMD plugin for manipulating topology information. It is meant to be a complementary tool to psfgen, which is very much optimized for building topologies for biomolecules. TopoTools consists of a generic middleware script layer that makes access to the topology related data stored in VMD more convenient than the existing very basic API, but it also has a number of high-level tools that allow reading and writing of topology file formats that cannot be parsed by the molfile plugins (as they need additional information not available to molfile plugins), parsing of parameter and residue database files for generation of complete input files for MD codes like LAMMPS and HOOMD-blue, and replicating or combining multiple systems (i.e. VMD "molecules").

To find out which version of topotools you have, please open the VMD text mode console and type: package require topotools. This should return the version number of the plugin that you have installed. Example:

vmd > package require topotools 1.9

Please file bug reports and feature requests as GitHub issues.

Learn how to use TopoTools from the on-line tutorial.

Please cite TopoTools as:

Axel Kohlmeyer & Josh Vermaas, (2022). TopoTools: Release 1.9

https://doi.org/10.5281/zenodo.598373

Version History

Version 1.0

TopoTools-v1.0 has been released together with VMD version 1.8.7.

Key features: first public version, basic support for listing, typing, adding, and removing bonds, angles, dihedrals, and impropers, read/write support for LAMMPS data files, periodic system replication, merging of "VMD molecules" to a single molecule, merging of selections.

Version 1.1

TopoTools-v1.1 has been released with VMD version 1.9.

Several bugfixes, especially for operating on selections and assigning atom properties.

New features:

- determination of angle and dihedral definitions from bonding information.

- guess of impropers. searches for atoms bound to exactly three other atoms forming an almost flat construct. tested with peptide bonds, phenyls, histidines. an optional tolerance keyword allows to specify the maximum difference from a flat structure. default is 5 degrees.

- determination of atom properties based on other information (e.g. element from mass, mass from element, element from name, radius from element).

- support for reading and writing of xmol/xyz style trajectories with a varying number of atoms

- support for writing (fake!) gromacs topology files for use with gromacs analysis tools for non-gromacs trajectories.

- support for reading data files containing non-orthogonal cells.

- stricter checking for CGCMM extensions to the data file format. only if the string CGCMM is in the first line of the data file, the lammps data file parser will look for those extensions.

- encode the intended atom_style setting in data file header. Parse and compare - if present - against requested atom style on reading.

- write commented out Coeff sections to data files to provide hints on which coefficients need to be set.

Version 1.2

The final version of TopoTools-v1.2 has been released with VMD version 1.9.1.

This version contains important bugfixes in topo guessatom (one of which affects topo readvarxyz), a few small enhancements, and a much improved and expanded documentation in addition to the tutorial on this homepage.

New features:

- Sanity check on atom coordinate data when reading lammps data files.

- Initial implementation for topo guessbonds (only works on "all" selections).

- Bugfixes in topo readvarxyz (safer format checking, no spurious empty frames)

- Bugfixes in topo guessatom (can handle element/type/name fields with unusual characters) - Bugfixes in topo writegmxtop (doesn't create charge groups with more than 32 atoms, better atom indexing)

- Bugfixes in topo readlammpsdata (can handle data files with class2 coefficients, doesn't writes topology information (bonds, angles, dihedrals, impropers) compatible with atom style)

- Bugfixes in topo writelammpsdata (use resid instead of residue property, as basis for molecule ids, since this is what we read in)

Version 1.3

TopoTools version 1.3 was distributed with alpha test versions of VMD version 1.9.2.

This version contains bugfixes and improvements to reduce the stack space requirements when operating on large systems with over 500,000 atoms. Special thanks to John Stone and Michael Doig for bringing this to my attention and explanations why this happens and how this can be avoided.

New features:

- Reduced stack space requirements

- Support for writing non-orthogonal cells

- Better detection of unknown topo subcommands

- Better detection for insufficient data when parsing the Atoms section in LAMMPS data files

- Consistent behavior when guessing bonds after reading them through molfile rather than from within topotools script

- Support for reading PairIJ Coeff section (ignored like all Coeff sections currently)

Version 1.4

TopoTools version 1.4 was distributed with late alpha test versions of VMD version 1.9.2.

This version contains bugfixes and improvements and adds support for accessing crossterms contributed by Josh Vermaas. This feature requires a version of VMD newer than 1.9.2a33, but version 1.4 should also work with older versions of VMD; only the crossterm support will not function correctly.

New features:

- A new utility function TopoTools::fixupnumtypes which prepends numerical atom/bond/angle/etc types with leading zeros so they get sorted consistently and in the correct numerical order with ascii style sorting. This facilitates maintaining the order of numerical atom/bond/angle/etc types, e.g. when reading and writing data files from LAMMPS.

Version 1.5

TopoTools-v1.5 was included in the VMD release version 1.9.2.

This version contains bugfixes and adds support for (optionally) creating functional gromacs topology files for CHARMM force field system with code contributed by Josh Vermaas. This feature requires a version of VMD newer than 1.9.2a33, but otherwise version 1.5 should also work with older versions of VMD. The use of the 1.9.2 release version (when it is available) or the latest 1.9.2 beta is highly recommended because of the many other improvements, though. Please note that version 1.5 has a known bug that breaks the command "topo guessatom lammps data". This is fixed in version 1.6.

Version 1.6

TopoTools-v1.6 is in alpha and beta versions of VMD version 1.9.3. This version contains a bugfix for "topo guessatom", a bugfix for "topo readlammpsdata" for data files with PairIJCoeffs sections ( contributed by Brian Moths https://github.com/akohlmey/topotools/pull/4 ) and a few minor cleanups.

Version 1.7

TopoTools-v1.7 was released with VMD version 1.9.3. This version contains better error handling in several places and auto-detection of atom styles for reading LAMMPS data files with style hints. Support for incompatible atoms styles 'dpd' and 'hybrid' is removed and support for 'sphere' added. A few minor bugs have been fixed since and an updated version can be downloaded below.

Version 1.8

TopoTools-v1.8 was included in VMD version 1.9.4 alpha test releases. This version contains mostly bugfixes and now refuses to write data files with zero length simulation boxes.

Version 1.9

TopoTools-v1.9 is scheduled to be released with VMD version 1.9.4. This version adds support for writing and reading LAMMPS data files with type labels.

Installation

unpack the tar archive which will create a directory named topotools1.9, if your VMD installation already has this folder, overwrite the files with the new version, otherwise and move it next to the topotools1.x directory from your existing VMD installation. VMD should use the new version automatically at the next start. To uninstall, just remove the topotools1.9 directory.