MDMovie User's Guide

This document describes MDMovie, a stand-alone graphical chemistry program that runs on a Silicon Graphics IRIS workstation. This program was written by chemist Jerry Greenberg of the San Diego Supercomputer Center and the Chemistry Department at UC San Diego. It allows you to

View molecular configurations.
Animate molecular dynamics trajectories.
View dynamics configurations in real-time as they are calculated on a remote UNIX system.
Display various properties you choose. The display can be in the form of , for example, vector data (such as atomic velocities).
Generate graphics output for hardcopy and animations, provided the devices and the related external software are available. "Camera control" options support rotation, zooming, and translation.

MDMovie is not a model-building program. Rather, it can be used for post-simulation analysis and to monitor the course of a simulation when running in distributed mode. However, you can create or delete bonds by selecting a maximum bond distance or picking atoms or bonds with the mouse.

MDMovie has been an ongoing research project and most, but not all, features are described here. Greenberg continues to add new features that suit the needs of particular researchers. You can modify MDMovie to suit your needs. Please contact the author (jpg@sdsc.edu) for further assistance.<>

This manual describes:

MDMovie input files
How to run MDMovie
How to use MDMovie menus
How to use MDMovie in distributed mode

MDMovie Input Files

By default, MDMovie reads a MOLPLOT input data file, a file format written by the

ab initio quantum mechanics program GAMESS. A MOLPLOT file consists of four parts: molecule descriptions, atom specifications, atom coordinates, and a list of bonds. All data is ASCII.

A molecule description consists of the following:

NATOMS Number of atoms
NKINDS Number of types of atoms
NBONDS Number of bonds
BNDWIDTH Width of bonds

(The description also includes a dummy character string describing the molecule type, but MDMovie does not use this value.)

Atom specifications give the name of each atom, its color index, and its initial radius that should be in the same units as the coordinate input described below. The color index refers to a pre-defined set of colors (that may be changed via the COLOR menu item).

These are given below

Table 1

	Color 		RGB

	Index	Value
	1				255 255 255

	2				0 150 0

	3				0 0 150

	4				150 0 0

	5				150 150 0

	6				0 150 150

	7				150 0 150

	8				125 125 255

	9				150 60 60

	10				60 150 60

	11				150 150 60

	12				150 60 150

	13				60 150 150

	14				150 225 30

	15				150 30 60

	16				30 150 60

	17				125 60 0

	18				150 0 60

	19				100 100 100

	20				150 0 255

Atom coordinates list the type of each atom type followed by the atom's x, y, and z coordinates. The x and y axes are parallel to the plane of the screen. The z axis is orthogonal to the plane of the screen. The center of geometry of the object is centered on the screen. Following the atomic coordinates, a set of coordinates corresponding to a vector property may be listed optionally. A vector property may correspond to, for example, a velocity or a force components. The number of atoms listed must correspond to the number for NATOMS.

A list of bonds may be given in pairs after the BONDATOMS keyword. Up to eight pairs may be listed per line. A negative number indicates that the radius of the bond will gradually increase towards the other atom.

Sample MOLPLOT File

The following example MOLPLOT file describes a molecule that consists of 6 atoms: 2 nitrogen atoms and 4 oxygen atoms. There are 5 bonds among the atoms, with the bonds having an initial bond width of 0.060. The nitrogen atoms (N) are blue (color index 3) with an initial radius of 0.30. The oxygen atoms (O) are magenta (color index 5) with an initial radius of 0.50. Next are lines that contain the atom name, the atomic coordinates, and then a set of coordinates corresponding to a vector property (here set to 0.0) There are bonds between the third and first atoms, the fourth and second atoms, the fifth and first atoms, the sixth and second atoms, and the first and second atoms.

NATOMS = 6 NKINDS = 2 NBONDS = 5
BNDWIDTH = 0.060
N204-geometry, 2.5 A N-N distance
N 3 0.30
O 5 0.50
N -0.883884 0.000000 0.883883 0.0 0.0 0.0
N 0.883884 0.000000 -0.883883 0.0 0.0 0.0
O -1.289056 1.076000 1.289056 0.0 0.0 0.0
O 1.289056 1.076000 -1.289056 0.0 0.0 0.0
O -1.289056 -1.076000 1.289056 0.0 0.0 0.0
O 1.289056 -1.076000 -1.289056 0.0 0.0 0.0
BONDATOMS 3 -1 4 -2 5 -1 6 -2 1 -2

Dynamics History File

The dynamics history file contains information to animate the trajectories of a molecule. The format of the file is similar to the MOLPLOT file: It includes atom specifications, an atom list, and a dynamics history.

The atom specifications contain a blank first line, then the number of atoms, the number of atom types, and the atom description (name, color index, radius).

The atom list contains the atom types, one per line, in the order they appear in the dynamics history.

The dynamics history contains a time step followed by a coordinate list. The coordinate list consists of the x, y, and z coordinates and their current velocities in the x, y, and z axes. A maximum of 10,000 configurations may be listed per file.

Sample Dynamics History File

The following sample file describes the trajectories of 15 atoms consisting of three types (B, B12, and D) for two time steps. (The B12 atom type distinguishes boron atom 12 from other boron atoms. By creating a different atom type, you can specify its color differently from that of other boron atoms.)

In the following sample file, two dynamics configurations are given.

15 3
B 2 1.0
B12 2 1.0
D 7 0.5
B
B
B
B
B
B
B
B
B
B
B
B12
B
D
D
0.200000E+02
2.74099 1.77908 -1.12053 -0.00001 0.00004 0.00007
0.05226 -0.61542 3.00336 -0.00001 0.00004 0.00007
1.69230 -0.35865 -2.70662 -0.00001 0.00004 0.00007
2.34800 -0.95014 0.20634 -0.00001 0.00004 0.00007
1.46048 2.38038 1.35893 -0.00001 0.00004 0.00007
-2.18170 1.76166 1.27469 -0.00001 0.00004 0.00007
-1.87257 -1.66282 0.10769 -0.00001 0.00004 0.00007
0.49352 -3.00551 1.51181 -0.00001 0.00004 0.00007
-0.24371 1.80571 -1.79869 -0.00001 0.00004 0.00007
-1.32069 -0.86828 -2.77809 -0.00001 0.00004 0.00007
0.52992 -2.83468 -1.34540 -0.00001 0.00004 0.00007
-0.43053 2.16412 3.50098 -0.00001 0.00005 0.00007
-3.08170 0.79653 -1.25476 -0.00001 0.00004 0.00007
-0.99444 4.86917 7.94279 0.00033 -0.00159 -0.00261
-1.14653 5.59843 9.14032 0.00032 -0.00157 -0.00258
0.400000E+02
2.74082 1.77996 -1.11910 -0.00001 0.00004 0.00007
0.05208 -0.61457 3.00480 -0.00001 0.00004 0.00007
1.69212 -0.35777 -2.70518 -0.00001 0.00004 0.00007
2.34782 -0.94927 0.20778 -0.00001 0.00004 0.00007
1.46032 2.38126 1.36036 -0.00001 0.00004 0.00007
-2.18191 1.76254 1.27612 -0.00001 0.00004 0.00007
-1.87275 -1.66194 0.10913 -0.00001 0.00004 0.00007
0.49334 -3.00464 1.51325 -0.00001 0.00004 0.00007
-0.24389 1.80659 -1.79725 -0.00001 0.00004 0.00007
-1.32088 -0.86742 -2.77665 -0.00001 0.00004 0.00007
0.52973 -2.83384 -1.34398 -0.00001 0.00004 0.00007
-0.43072 2.16502 3.50247 -0.00001 0.00005 0.00007
-3.08188 0.79740 -1.25333 -0.00001 0.00004 0.00007
-0.98781 4.83779 7.89113 0.00033 -0.00156 -0.00256
-1.14016 5.56748 9.08953 0.00031 -0.00153 -0.00251

Surface Data Files

A surface data file contains density values laid out on a three-dimensional orthogonal grid. It is written in a free format with one restriction: The density index must vary from fastest to slowest in x, y, z order.

Surface Specification File

The surface specification file contains information on the grid edges (only rectangular grids may be used), grid resolution, coordinates of the grid origin, the range of density values, and the number of surfaces requested. The first line specifies the number of grid points minus 1. The second line specifies the number of requested surfaces. The next three lines give the ranges for the x, y, and z values, respectively. The last line gives the range of the density values.

Checkpoint Files

When MDMovie writes to disk, you can specify the filename with the command-line option -co. If you don't specify a filename, MDMovie writes the file sysname.check (where sysname is the name of the data input file). The file, also called a checkpoint file, contains the information necessary to reproduce the image in the same orientation, display types, and colors.

When you run MDMovie, it checks for a filename called sysname.check or a checkpoint file. (The command-line option -ci overrides these defaults.) If no checkpoint file exists, it uses the default values. You may overwrite the current checkpoint file at any time by pressing the W key.

How to Run MDMovie

To run MDMovie in its simplest form using a MOLPLOT data file, enter

mdmovie filename

where filename is a MOLPLOT file.

To use MDMovie with a dynamics history file, enter

mdmovie -m filename

To use MDMovie with a surface dynamics file, enter

mdmovie -i surfacedata coordinates < specs

where surfacedata contains density values, coordinates contains the coordinates, and specs contains specifications about the surface. (These files were described in greater detail in the previous section.)

To start MDMovie in distributed mode, enter

mdmovie -s

The -ci and -co options specify the names of the input and output checkpoint files, respectively. These options may be used in conjunction with any data file. The -ci option specifies the name of a checkpoint file to be read, and -co option specifies the name of a checkpoint file to be written. Thus, to read the checkpoint file oldcheck and specify the new checkpoint file newcheck while reading a MOLPLOT input data file myfile, enter

mdmovie -ci oldcheck -co newcheck myfile

How to Use MDMovie Menus

Entering Values from the Keyboard

Some MDMovie menus (e.g., color, queue name) may require you to enter the appropriate value through the keyboard; for example, the COLOR menu needs the RGB values for the color, and the queue menu needs the name of an output queue.

To enter the value, first select the menu item by moving the cursor over the menu and clicking the right mouse button. The menu color will change from RED to GREEN. Next, press the M key. Type the appropriate character string or number, and then press return.

For example, the COLOR menu requires three input values for red, green, and blue. Move the cursor over the menu, click the right mouse button, then press M. Enter the value for the red component and press return, then the value of the green component and return, and finally the value for the blue component and return. The last return terminates the keyboard input.

Transformation Menu

The menus at the bottom of the screen manipulate model transformations. To transform the object, move the mouse while holding down the middle mouse button.

If you enter a value via the keyboard, the transformation occurs with each frame update after you select the GO menu item. For example, if you enter the number 5 under the Z-ROT menu item, then the model will change 5 degrees about the Z axis with each frame update. This is particularly useful when transforming each successive frame of an animation incrementally, such as when making videos.

The menus items are

XY-ROT: Move the cursor left or right to rotate the object about the y axis. Move the cursor up or down to rotate about the x axis.
Z-ROT: Move the cursor left or right to rotate the object about the z axis (the axis perpendicular to the plane of the screen).
XY-TRAN: Move the cursor left or right to move the object in the x direction. Move the cursor up or down to move the object in the y direction.
Z-TRAN: Move the cursor up or down to move the object in the z direction.
NEAR: Move the cursor up or down to change the near clipping plane. In conjunction with the FAR clipping plane, you can isolate a portion of the object.
FAR: Move the cursor up or down to set the FAR clipping plane.
FIELD: MDMovie displays the image with a perspective projection. Objects that are closer in the z direction appear larger than those objects further away. An orthogonal projection may be approached by decreasing the field of view. The menu displays the current field of view in tenths of a degree. To change the field of view, move the cursor up or down.
SCALE: Move the cursor up to increase the scaling factor, down to decrease it.

Display Menus

The menus on the left side of the screen manipulate the color and appearance of the objects.

Atom Types Menu

When you select an atom, you can manipulate the color, radius, and display characteristics of the atom via a pop-up menu that appears. It offers you the following choices:

REMOVE: Does not display this atom type.
CIRCLE: Draws a circle of appropriate radius about the atomic center.
LINESPHERE: Draws a "beach ball" structure (circles transformed around two axes) with an appropriate radius about the atomic centers.
LIGHTSPHERE: Draws a lighted sphere about the atomic center. The position and characteristics of the light source are fixed.
TRANS_SPHERE: Draws a transparent sphere with fixed opacity about the atomic center. (This item works only on SGI machines with VGX hardware.)
DOTS: Renders the spheres as a surface of dots. A submenu allows the user to select dot density.
UNLABEL: Removes labels from the atoms.
LABEL: Labels the atoms.
COLOR: Selects one of the standard eight colors from a pop-up menu. The value of the color may also be entered as an RGB value in the COLOR menu item.

Background Menu

Changes the background color. You can also change the background color via the COLOR menu item.

All Menu

Changes the display characteristics, except color, of all atoms. The same pop-up menu that appears for the individual atom types is displayed.

Bond Menu

Changes the characteristics of the bonds. The items that appear on the pop-up menu are:

NOBONDS: No bonds are drawn.
LINES: Draws the bonds as lines.
CODELINES: Draws the bond as a colored line. The color depends on the atoms at the end of the bond. It changes halfway across the bond.
CYLINDERS: Draws the bond as a lighted cylinder.
CODECYLINDERS: Draws the bond as a lighted cylinder. The color depends on the atoms at the ends of the bond and changes halfway between the two atoms.
UNLABEL: Does not display bond lengths.
LABEL: Displays bond lengths in the units used in the input file.
ADD BONDS: Draws a bond between two selected atoms picked with the cursor and pressing the left mouse button. If the bond is already present, the bond distance is toggled.
REMOVE BONDS: Selects a bond (with the cursor) ; clicking the left mouse button deletes the bond.
ANGLE: Displays angles between three atoms that you you select via picking with the left mouse.
COLOR: Selects one of the standard eight colors from a pop-up menu. The value of the color may also be entered as an RGB value in the COLOR menu item.

Surface Menu

Surface menu items appear only when a surface data file is specified with the "-i" option. There is one menu item for each surface density value. A pop-up menu determines the display characteristics:

NOSURFACE: Does not draw the surface.
SURFACE: Draws the surface.

Vector Menu

Changes the display characteristics of the vectors. The items that appear on the pop-up menu are:

NOVECTORS: No vectors are drawn.
LINES: Draws the vectors as a lines with an arrow at the tip.
CODELINES: Draws the vectors as a colored line. The color depends on the atoms that the vector has been assigned to.
CYLINDERS: Draws the vector as a lighted cylinder with an arrow at the tip.
CODECYLINDERS: Draws the bond as a lighted cylinder. The color depends on the atoms that the vector has been assigned to.
UNLABEL: Does not display vector values.
LABEL: Displays vector values in the units used in the input file.
ADD VECTOR: Displays the vector assigned to an atom when it is picked if it had been previously removed with DEL VECTOR.
DEL VECTOR: Deletes a a vector when it is picked. Clicking the left mouse button deletes the vector.
ADD ALL: Adds all vectors to the display. This differs from NO VECTORS in that it restores all vectors previously removed with DEL VECTOR.
DEL ALL: Deletes all vectors from the display
COLOR: Selects one of the standard eight colors from a pop-up menu. The value of the color may also be entered as an RGB value in the COLOR menu item.

Color Menu

Selects one of the standard eight colors from a pop-up menu or chooses an RGB color from the COLOR menu. Three values--one each for the red, green, and blue channels of the color--are set. The values range from 0 to 255.

Bondlength Menu

Sets bond length threshold. After you enter a value, all bonds whose lengths are less than this value are displayed.

Trace Menu

Traces the movement of an atom in a dynamics history file. Select atoms by entering their atom numbers. The trajectory of the atom to the current configuration is drawn; the line color is set to the color of the atom. Entering new atom numbers adds new trajectories. Entering a negative number deletes the trajectory of that atom.

Radius Menu

Sets the radius of atoms, bonds, or vectors, depending on which menu item is highlighted. The radius may be changed by moving the cursor up and down while pressing the middle mouse button or by entering a value after pressing the M key.

Vector Menu

Scales the lengths of the vectors. When this menu item is highlighted, the values of the vectors are scaled either by moving the cursor up or down or by keyboard input as described above.

Output Menus

MDMovie can generate output suitable for video, film, or a color or PostScript printer. The menus on the right side of the screen allow you to control the following output parameters:

CONFIG (Dynamics files): Sets an increment value. The dynamics configurations are incremented by the current value at each step.
FRAMES: Sets the number of frames. The program animates this number of frames.
FILE: Selects the output file. An IRIS RGB file will be generated. The name is automatically appended with .rgb.
QUEUE NAME: Selects the output queue for vpr or lpr.
GO Start. When selected, the cursor disappears, the object fills the entire screen, and output is sent to a device. For dynamics files, shows a trajectory.
VPR: Sends output to a vpr queue via the SDSC vpr program. After you select GO, you select a queue to which the output is sent through a pop-up menu or the QUEUE NAME menu. You can modify this to suit your site. If vpr is not available, an error will not occur and an IRIS RGB format image file will be created.
LPR: Converts the file to PostScript via the SDSC Image Tools and sends the output to a PostScript printer. After you select GO, the output is sent to the lpr queue. You can modify this to suit your site.
VIDEO: Displays output. When the queue is set to off, the output is not sent (used for viewing dynamics files). When the queue is set to on, the output is sent to a video disk if the appropriate hardware and control software is available.
WINDOWS: Toggles IRIS windows.
STEREO: Toggles stereo viewing when stereographics hardware is available.

Titles Menus

Pressing the F7 key toggles menus for writing titles and labels on the screen. These may be used to identify the molecular structure or for making titles for presentation videos.

Keyboard Commands

Certain functions may be accessed by keyboard input. Press the appropriate key to activate the appropriate function as indicated in the following table.

Table 2

Key		Function
2	Toggles side-by-side stereo.
3	Increases eye separation for stereo.
4	Decreases eye separation for stereo.
C	Recalculates the center of geometry (useful when there is a
	significant movement of the center of geometry in a dynamics trajectory).
D	Moves planar contour along the x axis in a negative direction.
E	Toggles between drawing planar contours and entire surfaces.      
F	On animations, sends the current configuration to the output queue
	(video, film, or color printer) before updating the frame. Normally, MDMovie
	updates the frame then sends the result to the output queue.
G	Displays surface density grid.
K	Kills the program.
R	Re-initializes the rotation matrix to an identity matrix.
S	Kills program in distributed mode, but allows the dynamics to
	continue on remote machine.
U	Moves planar contour along the x axis in a positive direction.
W	Writes a checkpoint file.
X	Places surface contour parallel to the y-z plane.
Y	Places surface contour parallel to the x-z plane.
Z	Places surface contour parallel to the x-y plane.
F1	(function key) Toggles full-screen display.
F7	(function key) Toggles display menus.

R-ARROW (right arrow key): Displays next dynamics configuration, according to the value in the CONFIG menu item.
L-ARROW (left arrow key): Displays previous dynamics configuration according to the value in the CONFIG menu item.
U-ARROW (up arrow key): Displays last configuration.
D-ARROW (down arrow key): Displays first configuration.
ESC: Kills the program.

How to Use MDMovie in Distributed Mode

In distributed mode, a remote machine such as a CRAY C90 or Intel Paragon computes the values that MDMovie displays as each configuration is calculated. When you start MDMovie in distributed mode, it prompts you for the name of the remote machine, port number, directory on the remote machine where the job will execute, the name of the executable program, and whether the job is running or is a new job. The remote machine must also have access to a name server or have the workstation's name in its /etc/hosts file.

After the connection has been made, the first configuration is displayed along with a new menu at the top of the screen. To start the dynamics run, place the cursor in the GO menu, and press the mouse button; to stop the dynamics run temporarily, place the cursor in the STOP menu, and press the mouse button. Any transformations or options that require input temporarily stop the dynamics run on the remote machine. After you enter the input, the program continues.

To stop the run, press the K key. This kills the program on the remote machine and MDMovie. The S key stops MDMovie but allows the program to continue on the remote machine. MDMovie can reconnect to the running program at a later time. This is done by typing:

mdmovie -s

and answering "yes" when prompted to reconnect to a running job.

Subroutine Calls

To transfer data from the remote machine to MDMovie, the program on the remote machine must call certain subroutines. Before any data is sent, the program must initialize certain variables with the SENDINIT subroutine. Each time a new configuration is calculated, the program sends the data to MDMovie with the SENDIT subroutine. These routines may be tailored to the requirements of a particular simulation code and/or remote platform. The call to SENDINIT looks as follows:

CALL SENDINIT (NADDRESS,NAD,NSTEP,NI,NTYPES,* XADDRESS,ANAMES, ATYPES,RAD,NITES,PDISP,PFROM,* PDISPCH)

where the parameters have the following meanings:

NADDRESS: Number of locations of data (e.g., if the cluster data is kept separate from the impurity data, then NADDRESS = 2).
NAD: Integer array giving array indices for XADDRESS.
NSTEP: Step length between elements.
NI: Number of atoms.
NTYPES: Number of atom types.
XADDRESS: Integer array that specifies the addresses where the coordinate data are stored.
ANAMES: Integer array containing atom names.
RAD: Floating-point array containing radii of each atom type.
NITEMS: Number of properties to be displayed on an IRIS workstation.
PDISP: Integer array containing memory locations of displayed items.
PFORM: Type of data in PDISP, either CFLOAT for floating-point (real) numbers, or CINT for integer values.
DISPCH: Character string describing data in PDISP.

Subroutine SENDIT()

The subroutine SENDIT is called each time a new coordinate set is calculated. This subroutine has no arguments.