= Using Chimera with MMTK =

[http://dirac.cnrs-orleans.fr/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.  [attachment:MMTK2Molecule.py 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: [attachment:showNormalModes.py showNormalModes.py] and [attachment:NormalModesTable.py NormalModesTable.py].  [attachment:showNormalModes.py showNormalModes.py] consists of the MMTK sample normal mode code, followed by the lines:

{{{
from NormalModesTable import NormalModesTableDialog
NormalModesTableDialog(modes)
}}}

[attachment:NormalModesTable.py 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 [attachment:followMD.py followMD.py], which contains a mix of MMTK and Chimera code.

A more elaborate example, [attachment:plotMD.py 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 [attachment:plotMD.mp4 plotMD.mp4].  Note that Chimera remains interactive (user is able to select, move and color atoms) throughout the entire MD simulation.

== 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.