Using Chimera with MMTK

​MMTK is an open source program library for molecular simulation applications. Chimera uses MMTK to implement its energy minimization functionality. Using the code below, MMTK users can run their scripts and visualize their simulations as they execute.

The biggest hurdle in visualizing MMTK results in Chimera is the difference in data used by the graphics and the simulation library. Chimera displays "molecules" while MMTK simulates a "universe". Fortunately, they both use "atoms", so if we can find a correspondence between Chimera atoms and MMTK atoms, we can bridge the gap between the two worlds. MMTK2Molecule.py​ implements a conversion routine from an MMTK universe to a Chimera molecule. Typical usage looks something like:

from MMTK2Molecule import convert
molecule, atomMap = convert(universe, defaultCS=1, usePDBnames=False)

where molecule is a Chimera Molecule instance; atomMap is a dictionary whose keys are MMTK atoms and whose values are Chimera atoms; universe is a MMTK Universe instance; defaultCS is the default coordinate set index; and usePDBnames controls whether the conversion attempts to generate Protein Data Bank style atom names. The default value for defaultCS is None, which results in coordinate set numbering starting with zero. The default value for usePDBnames is True. The easiest way to see how MMTK2Molecule.convert may be used is through examples. We We will describe two use cases: visualizing normal modes results, and monitoring molecular dynamics.

Visualizing Normal Modes

To visualize the results of the MMTK normal modes calculation example, we can create a Chimera trajectory of the molecule. The trajectory represents a single normal mode and has four sequential steps (equilibrium position, positive extreme, equilibrium position, negative extreme). When played, the trajectory will appear to oscillate between the two extremes. For this example, we need two source files: showNormalModes.py​ and NormalModesTable.py​. showNormalModes.py​ consists of the MMTK sample normal mode code, followed by the lines:

from NormalModesTable import NormalModesTableDialog
NormalModesTableDialog(modes)

NormalModesTable.py​ does all the work of the conversion from MMTK to Chimera, displaying the user interface, and updating trajectory coordinates when the user selects a different normal mode to display.

Monitoring Molecular Dynamics

To follow the progress of a molecular dynamics run, we can create a Chimera molecule from the MMTK universe and update its atomic coordinates as simulation progresses. To keep Chimera interactive, we can run the simulation in the background, and poll for atom coordinates changes every few display frames. The example code is in followMD.py​, which contains a mix of MMTK and Chimera code.

A more elaborate example, plotMD.py​, extends the previous example to include a plot of the system potential energy along with updating atomic coordinates. The additional creates a matplotlib plot, and registers a callback function that is invoked whenever Chimera atomic coordinates are updated. The arguments to the callback are (1) the MMTK universe, (2) a mapping from MMTK atoms to Chimera atoms, and (3) an MMTK state (which is None when the callback is invoked after the simulation ends). The execution of plotMD.py is shown in plotMD.mp4​.

Caveats

There are a few caveats in using MMTK with Chimera:

• The above examples are tested with a development version of MMTK dated September 1, 2010, and will only work with versions of Chimera built on that date or later.
• Use of MMTK threading with Chimera is not thoroughly tested.
• The code is intended as examples and may require modification for different applications.
• Conversion with usePDBnames=True is not very well tested.