March 26, 1998

WMOVIEC

Features     |     Usage     |     Command Line Options     |     File Options     |     Colors

FEATURES

WMOVIEC is a program that creates movies of atomic motion. It has the following features:

• Creates movies for display on a PC compatible with VGA or EGA graphics.
• Up to 16 colors from a palette of 64 possible colors, plus special "clear" color.
• A variable resolution of up to 640 by 350.
• Reads atomic coordinates from a COR or RCV file.
• Reads atomic types from a TYPELIST file.
• Display displacement (tails) for each atom.
• Display bonds connecting atoms a specific distance apart.
• Color atoms according to atom type.
• Color atoms according to atomic displacement magnitude and direction.
• Color bonds according to bond length.
• Calculate displacements relative the either (1) previous step in COR or RCV file or (2) relative to a fixed step in another COR or RCV file.
• Limit displayed atoms to those in a specified layer.
• Orient the atoms so that any of the three coordinates axies are drawn horizontally and verticially on the display.

USAGE

WMOVIEC (and VMOVIEC) will describe their own usage when run without any command line parameters (just typing WMOVIEC or VMOVIEC followed by a return).

WMOVIEC can be invoked in two ways.

WMOVIEC [options...] fcor [+]fmov orient nlayer ilayer

WMOVIEC [options...] fcmd fcor [+]fmov

The first form specifies all options in the command line. With the second form WMOVIEC reads options placed in the file fcmd.

In all descriptions for commands, words which appear all in UPPERCASE are commands that must be entered verbatim (but the actual case used is irrelevant). Words which appear in lower or Mixed case must be replaced by the appropriate values. Words in square brackets [] are optional. Choices are denoted by |. When you must make a choice, then they are enclosed in braces {} and separated by |. For instance,

ORIENT { X/Y | X/Z | Y/X | Y/Z | Z/X | Z/Y }

means that the ORIENT command requires one of the 6 choices listed. A legal command is

ORIENT Y/Z.

COMMAND LINE OPTIONS - First Input Form

Command Line:

WMOVIEC [options...] fcor [+]fmov orient nlayer ilayer

REQUIRED PARAMETERS

fcor     The name of the COR or RCV file containing the particle coordinates

fmov     The name of the movie file produced. The optional + indicates that the movie produced will be appended to the end of the existing movie file.

orient     Determines orientation of the particle display, and can be either X/Y, Y/X, Y/Z, Z/Y, X/Z, Z/X. The first letter indicates which direction in particle space will run vertically, the second indicates which will run horizontally. The / is required.

nlayer     Number of layers into which to divide the atoms.

ilayer     Layer of atoms to display.

OPTIONAL PARAMETERS

-b b1 b2     Draw lines (called bonds) connecting atom pairs separated by a distance of b1 to b2 angstroms.

-t ftype     Name of file containing the types of the particles stored in the file fcor. The format for this file is described in the section TYPELIST FILE. The atom type is used to selected by symbol used to draw the image.

-w     When drawing bonds, the default is to not connect atoms on opposite sides of the repeating boundaries. The -w options will draw such bonds.

-x     Draws the particle number in place of a particle symbol. This is useful for identifying particular atoms.

-r fref     Use first step in file fref for selecting atom layers (see orient required option above). By default, layer atoms are selected anew each step.

-d scale fref     Draw tails for atoms. A tail is a line drawn from the atom back to a reference position (in other words, a displacement). The first step in the file fref is used as the reference position. The value of scale is used to increase, decrease, or change sign of the tail.

-s scale fref rad     Draw slip tails. This filters out the bulk displacment of a region of atoms, leaving only an atom’s displacement relative to its neighbors. This is done by subtacting the average size of an atom’s neighbor’s tails from the atom’s own tail. The neighbors of an atom are those that are within a distance rad from the neighbor in the first step of the COR or RCV file fref. The value of scale is used to increase, decrease, or change sign of the tail.

-m scale     Draws moving tails. The tails are drawn relative to the previous step, not a fixed reference step as is done for the -d and -s options above. The value of scale is used to increase, decrease, or change sign of the tail.

The WMOVIE program projects the particles onto the xy, yz or xz plane, and can draw either axis in the horizontal direction. The orient parameter is used to specify this orientation, and it takes the form u/v where u (either x, y or z) is the direction running vertically and v runs horizontally. The / symbol is required. The remaining direction (called depth) runs perpendicular to the screen. The coordinate origin is located at the lower left hand corner of the screen with coordinates increasing (ie positive) in both the horizontal and vertical directions.

For large simulations it is often impractical to display all the particles, so there is the option of displaying individual slices or layers from the particles. The layers are always oriented parallel to the screen. The particles are divided into nlayer number of layers and the ilayer numbered layer is displayed. For example if nlayer and ilayer are 4 and 2 respectively, then the particles are divided into four layers, and the second layer is displayed.

Two different schemes are used to divide the particles into nlayer layers, depending on the boundary conditions specified in the COR or RCV file. If there are repeating boundary conditions in the direction normal to the screen, then the repeat distance (the size of the repeating cell) is divided into nlayer equal parts. If there is no repeating boundary condition then the interval between the highest and lowest particle (depth-wise) is divided into nlayer equal parts.

WMOVIE gives the options of drawing "bonds", these are lines connecting all atoms between distance b1 and b2 apart. This action is controlled by the -b command line option. Bonds are useful for uncovering various lattice structures and orientations. As an example, if a BCC lattice with lattice parameter equal to 1.0 undergoes a Bain strain into an FCC lattice, then there will be atoms a distance 2^1/3 (approximately 1.260) apart where there were no such atoms in the BCC case. Thus by drawing bonds between all atoms between 1.25 and 1.27 apart (an interval centered on 1.260) one can observe the creation of the FCC phase.

The -w option controls how bonds between atoms on opposite side of repeating boundaries are drawn. By default, such bonds are not drawn. The -w option forces WMOVIE to draw such bonds from one of the atoms to where its neighbor would be if it were not wrapped around to the opposite side of the box.

Tails is the name given to the lines depicting atom displacments. They come in three varieties. The most basic is -d scale fref option. This draws tails from atoms to their positions in the first step of COR or RCV file fref. The value of scale is used to increase, decrease or change the sign of the tails.

The -m scale option draws tails from atoms to their positions in the previous step.

The -s rad is the slip tail option. It modifies both the -d and -m options. Each tail is normalized by the tails of its neighbors. The average value for its neighbor’s tails is subtracted from an atom. This results in the displacement of an atom relative to its neighbors, and is different from is absolute displacement. This is useful for highlighting the action along slip planes.

Unlike the COR file, the RCV file does not store information about file types (ie species). So if you are using a RCV file this information must be obtained elsewhere. If no type file is specified, then all particle types are set to 1. The type file is an ASCII file with a simple format. The first line contains the text

TYPELIST n

where TYPELIST must be present verbatim and n is the number of types present. The following lines contain the type values (integers between 0 and 255) separated by one or more spaces or line breaks. The first type value applies to the first set of atom coordinates in the RCV file, the second type value with the second coordinates, and so on. The type values are used to access images stored in the image file. Each image in an image file has a unique type number. Type 0 is a special type, atoms with type 0 are displayed as points (a single screen pixel). Atom whose types have no symbol in the image file will not drawn.

The COR and RCV files are special format files produced by CDCMD and XMD (computer molecular dynamics programs). These file formats store particle coordinates in a compressed low resolution format accurate to one part in 10000. In RCV files, auxiliary information is stored as normal ASCII text, and the entire RCV file can be edited with a normal ASCII text editor (additionally there are 100 points of a radial distribution function stored in compressed low resolution format). The RCV file format was developed to facilitate transmission of CMD data over normal phone lines. Many computer systems will mangle a pure binary file in such a situation, so an ASCII type file was necessary. The RCV file contains no information about particle types, so a separate type file is needed to convey this information.

A COR or RCV file contains coordinates for an unlimited number of time steps. The WMOVIE program will use every time step in the file as a frame in the movie.

The order of the frames in the movie are determined strictly from the order of steps in the COR or RCV file, not the time step number of the step. So if steps are rearranged in a non-sequential order, the WMOVIE will display them out of sequence.

FILE OPTIONS - Second Input Form

Command Line:

WMOVIEC [options...] fcmd fcor [+]fmov

This input form requires only three file names. fcmd is the name of the command file. This file contiains commands describing the layout of the movie (see section COMMAND FILE below). The fcor and fmov files are the same as before, the COR or RCV file and the output movie file. The + tells the program to append the movie at the end of the existing movie file.

The command lines options are the same as those above, and can be used to override the commands in the command file.

The commands allowed in the command file duplicate the commands above as well as provide additional functionality. The command file is a text file containing the commands detailed below. In addtion to commands, comments (which must start with a #) and blank lines are allowed. Below is a list of commands.

Don't draw atoms. This does not affect the drawing of tails or bonds.

Draw atom number rather than circle. The number drawn is the position of the atom in the list of atoms, i.e. the first atom is draw as a number 1, the second as 2, and so on. This is useful for identifying individual atoms - if there are not too many atoms in the display.

The sereis of ATOM COLOR commands control the color of the atoms and displacements. The displacements are always the same color as the atoms.

Colors the atoms according to their type. NTYPE is the number of types listed on the line. type1 and color1 are the first type and color pair in the list, typeN and colorN are the last. The type is an integer from 1 to 256. See COLOR VALUES below for an explanation of the color values.

Colors the atoms according to the magnitude of the atom’s displacement. The range of displacements from 0 to mag is divided into Ndisp-1 equal segments, and the atom color is assigned the first Ndisp-1 colors according to its displacement magnitude. If the atom’s displacement exceeds mag, then it is drawn with colorN. See COLOR VALUES below for an explanation of the color values.

Colors the atoms according to the magnitude of the atom’s displacement in the plane normal to viewing direction. The component of the displacement parallel to the viewing direction is ignored. Otherwise, this command works like the previous command ATOM COLOR DISP MAG.

Colors the atoms according to the magnitude of the atom’s displacement. Unlike the previous setting, the maximum magnitude is not specified. This setting checks the maximum displacement of all the atoms, and uses this maximum to determine the atom colors. Thus the range of displacements from 0 to maximum displacement is divided into Ndisp equal segments (not Ndisp-1 like before). See COLOR VALUES below for an explanation of the color values.

Colors the atoms according to the magnitude of the atom’s displacement in the plane normal to viewing direction. The component of the displacement parallel to the viewing direction is ignored. Otherwise, this command works like the previous command ATOM COLOR DISP RMAG.

Colors the atoms according to the size and direction of the atoms displacement. Each atomic displacment is dotted with the vector (Vx Vy Vz). The value of this dot product is compared with MinRange and MaxRange. If it lies below (above) this range, then the atom is colored with color1 (colorN). Between these ranges, the atom color is mapped to the colors color2, color3, to colorN-1. Ndisp is the number of colors specified. Note that the dot product can be negative; typically MinRange and MaxRange will be set values like -0.5 and 0.5.

Colors the atoms according to the size and direction of the atoms displacement. Each atomic displacment is dotted with the vector (Vx Vy Vz). The range of values for all the dot products is calculated, and then the color for each atom is determined by mapping its dot product onto this range. For example, if the minimum and maximum dot product were -2 and 2, and Ndisp is 4, then atoms whose dot products are between -2 and -1 will be colored with color1, those with dot products between -1 and 0 will be colored color2, etc.

Colors the atoms according to the size and direction of the atoms displacement. The component of each displacement which lies within the plane of the display is isolated. If this component is less tha MinRange then the atom is draw with color1. Otherwise the angle relative to the horizontal axis is calculated, and added to the parameter Phase. The resulting angle is mapped to the interval of Ndisp-1 colors.

Bonds will be drawn between all pairs of atoms whose distance is between Lo and Hi (where Lo and Hi are specified in angstroms). Normally, atom pairs which lie on opposite sides of a repeating boundary will be ignored. If the option WRAP is specified, then bonds will be draw between such atoms.

This command must be specified before the TAIL command or the ATOM COLOR DISP command. It need only be down once in the command file. The option REF tells the program to calculate displacements relative to the first step in COR or RCV file fref. Otherwise, the program calculates displacement relative to the previous step.

Controls the size of move image. Normally, WMOVIEC re-adjusts the display size for each step, according to the boundary conditions. In the direction(s) with repeating boundary conditions, the image extends from 0 to the box size. In the direction(s) of with free surfaces, the image extends from the minimum to the maximum atom coordinate. With the frame option, you can specify a constant size image for the entire movie. The parameters specify the minimum and maximum extent of the image in units of angstroms.

Controls the drawing of labels on the display. When it is on (the default), the number of atoms, the temperature, and layer information is all drawn on the display. When off then only the atom, tails, displacements and a frame is drawn.

Like the options nlayer and ilayer in the section ORIENTATION and LAYERS above, this divides the atoms into nlayer number of layers and chooses all atoms in ilayer for display. If the option REF is specified, then the atoms from the first step in file fref are used to detemine which atoms belong to the displayed layer. Otherwise, the layers are re-calculated for each step in the fcor file.

Specifies the orientation for display. See section ORIENTATION and LAYERS above.

Specifies the horizontal and vertical resolution of display. The default is the maximum EGA resolution (640x350). This can be useful in conjunction with VMOVIEC. VMOVIEC allows you to save a movie frame as a PCX file. By controlling the resolution of the movie as its made, the resolution of the resulting PCX file can be controlled. (This PCX file can be converted afterward to a GIF file - using the shareware LVIEW utility for example - and included in a WWW page).

Tells the movie program to draw "tail" to represent particle displacements. This command must be preceded by the DISP statement (see above), which determines the how the displacements are calculated. The scale option will enlarge or reduce the size of the drawn tails.

The user can place lines of text within a movie file as an aid in later identification. This string of text can be read and displayed by the VMOVIEC program (but not while the movie is displayed), as well as the DOS TYPE program (just type TYPE file.mov - where file.mov is the name of the movie file).

The program will read the types for each atom from the typelist file flist. See the section TYPELIST above.

COMMAND FILE EXAMPLE

This is a sample input file for wmoviec. The individual lines do the following

atom index

Display the atom number instead of the default circle.

atom color type 2 1 300 2 222

Color atoms according to their type. Atom type 1 is drawn as the brightest red (300 means 3 parts red, no parts blue, green). Atom type 2 is drawn as light gray (2 parts each of red, blue, green).

orient x/z

Draw the atoms so that the x direction in the original atomic coordinates is displayed vertically in the movie, the z direction is displayed horizontally.

layer 8 1

The atomic configuration is divided into 8 layers in the depth direction (the y direction in the original atomic coordinates), and the only atoms from first layer are displayed.

disp ref test.cor

Calculate the atomic displacements for each atom and each step relative to the atom positions in the first step found in the file test.cor.

Tail 1.0

Plot tails for each atom according to the displacement calculated above.

title 2
bulk diffusion on plane
one vacancy at a periodic array, 1150K

Store a two line title with the movie. The two lines following the line "title 2" are used as the title.

Colors can be any one of 64 values, but only 16 colors can appear on screen at once. Colors can be specified in two ways. The first has the easiest syntax and is recommended. Colors are specified using three digits, ranging from 0 to 3. The three digits determine the amount of red, green and blue respectively. For example, the color 320 woul be 3 parts red to 2 parts green. The color 333 would be white, 000 black, 300 the brightest red, 030 the brightest green, 003 the brightest blue, 222 gray, and so on. All three digits must be present, otherwise the program assumes that the second system is desired.

The second way to specify color uses a number between 0 and 64. This mapping between number and displayed color is determined by the EGA graphics hardware. This method is not recommended.

The special clear color is specified by writing clear in place of the above formats. Atoms of this color will not be drawn.

The program keeps track of the total number of colors requested for the movie. Savings of speed and disk space can be realized by minimizing the total number of colors. By reducing the number of colors, you can reduce the number of bit planes required by the movie (bit planes are regions of display memory on the EGA graphics card). By keeping the number of colors less or equal to 2, 4, 8 and 16 you can restrict the movie to 1, 2, 3 or 4 bit planes. Keep in mind that the movie program sets aside two colors for itself, one for background (white, 333), the other text and frame (black, 000). Any additional colors you require will add to this number. If you use only black for your drawing colors, then you will be using the minimum amount of space.