Molecule Viewers In and Out
This document describes how to use the Pymol-based molecule viewer through <structure> outputs in Rappture. For the VTK-based molecule viewer through <drawing> outputs, see drawing (output)
Molecule Viewer Basics
Rappture contains a utility which helps make viewing molecules easy. It is
called the Molecule Viewer. By telling Rappture the x, y, and z coordinates
of an atom, the basic structure of a molecule can be visualized. To generate a
molecular viewer, the user will need to take advantage of the following
Rappture element types:
- loaders
- structures
- molecules
- atoms
Molecule Viewers are made up of <molecule> and <atom> elements.
We'll start by explaining <atom>s.
<atom id="0">
<symbol>H</symbol>
<xyz>-1.24935 -3.41562 0.0</xyz>
</atom>
<atom> elements in Rappture recognize two sub-elements, <symbol> and <xyz>. The <symbol> sub-element is used to define the type of atom the xml stanza represents. In the example above, the symbol H is used for Hydrogen. The <xyz> sub-element tells the position of the atom in angstroms. It is important to note that these values are in angstroms and not nanometers. If nanometers are used for the units of the position, the resultant molecule will look like the atoms are overlapping.
<molecule>
<about><emblems>on</emblems></about>
<formula>pdt</formula>
<atom id="0">
<symbol>H</symbol>
<xyz>-1.24935 -3.41562 0.0</xyz>
</atom>
</molecule>
<molecule> elements in Rappture recognize three sub-elements, <about>, <formula>, and <atom>. The <about> sub-element contains an <emblems> element which tells the molecule visualizer whether emblems should be turned on or off. The <formula> element names the molecule you are visualizing. This element is used in the molecule description. The <atom> element can appear any number of times to specify all the atoms in the molecule.
Molecule Viewers as Inputs
Molecule Viewers can be placed in the input section of the Rappture graphical user interface by using loaders and structures. Here is an example:
<?xml version="1.0"?>
<run>
<tool>
<title>Molecular Structure As Input</title>
</tool>
<input>
<structure>
<default>
<components>
<molecule>
<about><emblems>on</emblems></about>
<formula>pdt</formula>
<atom id="0">
<symbol>H</symbol>
<xyz>-1.24935 -3.41562 0.0</xyz>
</atom>
<atom id="1">
<symbol>S</symbol>
<xyz>0.08092 -3.19426 0.0</xyz>
</atom>
<atom id="2">
<symbol>C</symbol>
<xyz>0.00055 -1.40789 0.0</xyz>
</atom>
</molecule>
</components>
</default>
</structure>
</input>
</run>
In the above example, we have encapsulated a <molecule> with a <structure>. <molecule>'s within the input section of a tool.xml should be placed inside of the <default> section of a <structure> element, as a component as shown above. If the <structure> element is inside of a <loader>, then <current> tags should be used instead of <default>.
Molecule Viewers as Outputs
Molecule Viewers are also recognized as output for the Rappture graphical user interface. The example below show how to make setup a molecule viewer as output.
<?xml version="1.0"?>
<run>
<tool>
<title>Molecular Structure As Output</title>
<command> echo =RAPPTURE-RUN=>tool.xml </command>
</tool>
<input>
</input>
<output>
<structure>
<components>
<molecule>
<about><emblems>on</emblems></about>
<formula>pdt</formula>
<atom id="0">
<symbol>H</symbol>
<xyz>-1.24935 -3.41562 0.0</xyz>
</atom>
<atom id="1">
<symbol>S</symbol>
<xyz>0.08092 -3.19426 0.0</xyz>
</atom>
<atom id="2">
<symbol>C</symbol>
<xyz>0.00055 -1.40789 0.0</xyz>
</atom>
</molecule>
</components>
</structure>
</output>
</run>
Molecule Viewers as output are very similar to molecule viewers as input. One major difference to note is the lack of <current> and <default> tags.
Sending PDB files to the Molecule Viewer
The PyMol? Visualization Engine can accept PDB files directly. To include a PDB file in your run.xml file, swap out the <atom></atom> sections for a <pdb></pdb> section. Here is an example:
<?xml version="1.0"?>
<run>
<tool>
<title>Sending PDB file to Molecule Viewer</title>
</tool>
<input>
</input>
<output>
<structure>
<components>
<molecule>
<pdb>ATOM 1 C 0.000 0.000 0.000
ATOM 2 C 1 0.000 0.000
ATOM 3 C 0 1.000 0.000
ATOM 4 C 0 0.000 1.000
</pdb>
</molecule>
</components>
</structure>
</output>
</run>
Sending LAMMPS files to the Molecule Viewer
The Molecule Viewer can also display LAMMPS dump files in a manner similar to PDB files, as described above. The contents of a standard atom style LAMMPS dump file can be placed in the <lammps> sub-element as follows:
<?xml version="1.0"?>
<run>
<tool>
<title>Sending LAMMPS file to Molecule Viewer</title>
</tool>
<input>
</input>
<output>
<structure>
<components>
<molecule>
<lammps>
ITEM: TIMESTEP
0
ITEM: NUMBER OF ATOMS
3
ITEM: BOX BOUNDS
-4.0 4.0
-4.0 4.0
-4.0 4.0
ITEM: ATOMS id type x y z
1 1 -1.24935 -3.41562 0.0
2 2 0.08092 -3.19426 0.0
3 3 0.00055 -1.40789 0.0
</lammps>
</molecule>
</components>
</structure>
</output>
</run>
The <lammpstypemap> sub-element can be used to map the atom type numbers in the dump file to specific elements. The contents of this element should be a whitespace delimited sequence of element names corresponding to the desired element for each atom type. For example, a type map of "H S C" will map atom type 1 to hydrogen, 2 to sulfur, and 3 to carbon.
Displaying trajectories as sequences
By default, if a PDB or LAMMPS trajectory is given to the molecule viewer, only the first frame of the trajectory will be visible. To view the entire trajectory as an animation, put a "yes" in the <trajectory> sub-element. When this option is enabled, the PDB or LAMMPS data will be automatically split into unique molecule elements for each time step, and placed into a sequence element. Example:
<?xml version="1.0"?>
<run>
<tool>
<title>Viewing trajectory as sequence</title>
</tool>
<input>
</input>
<output>
<structure>
<components>
<molecule>
<trajectory>yes</trajectory>
<pdb>
...
</pdb>
</molecule>
</components>
</structure>
</output>
</run>
Creating unit cells with Parallelepiped
You can create a wireframe parallelepiped shape to display crystal unit cells. The shape is specified with an x,y,z <origin> position, three edge <vector> elements pointing out from the origin, and x,y,z <scale> factors to set the length of the edges. If a single value is given for <scale>, all edges will be scaled by the same amount.
<structure>
<components>
<molecule>...</molecule>
<parallelepiped>
<origin>0.0 0.0 0.0</origin>
<scale>1.0 1.0 2.0</scale>
<vector id="1">0.5 0.5 0.0</vector>
<vector id="2">0.5 0.0 0.5</vector>
<vector id="3">0.0 0.5 0.5</vector>
</parallelepiped>
</components>
</structure>
See the parallelepiped example in the zoo of examples.
