VASP Data Viewer

Background
Instructions
Known Issues
Acknowledgements
Download

Background

This is a scientific visualization package for examining output files generated by the Vienna Ab-initio Simulation Package, a package for performing ab-initio quantum-mechanical molecular dynamics using pseudopotentials and a plane wave basis set. The project was initiated when a chemical engineering professor requested assitance in visualizing output files produced by the above package. It displays iso-surfaces and slices of a three-dimensional data set, along with the atoms that make up the molecule the calculations were performed for, and allows symbolic bonds to be inserted between them.

The source code is available for use in non-commerical products via the GNU General Public License. The program was designed to be both reasonably portable and extensible. The only system requirements are an ANSI C compiler, OpenGL 1.1 or later, and GLUT 3.6 or later. The application has been tested under Windows NT 4.0 SP 5 and FreeBSD 3.2, both on Intel processors. Although the program currently only supports the VASP data file format, it should be relatively straightforward to add support for additional file formats.

Instructions

Installation

Windows

If you are using a 32-bit Windows system (i.e., Windows 95, Windows 98, Windows NT, or Windows 2000), simply download the Win32 binaries and extract them into a separate directory (a free evaluation version of WinZip can extract the files for you). If you are using a version of Windows 95 prior to OSR 2, you may need to download OpenGL from Microsoft, which is required to run this program.

Once you have extracted the files, and installed OpenGL, if necessary, simply double-click on vaspview.exe or type vaspview from the command line, in the directory where you extracted it.

UNIX

If you are using a UNIX system (such as Linux, FreeBSD, etc.), you will have to download the source code and compile it for your system. If you download the .zip file instead of the .tar.gz file, make sure you use the -a option when extracting the files, to force use of the correct EOL sequence.

A Makefile is located in the src directory in the source archive. Edit this Makefile so the CINCLUDE and LIBS variables refer to the correct locations for include files and library files, respectively, for your system. Then type

make all

to build the executable. It will be placed by default in a bin directory in the main vaspview directory.

Opening a file

Type the name of the file you wish to open in the "Open File" text field, and press <Enter> or click the "Open" button. A progress indicator (or an error message) will be displayed in the status bar at the bottom of the window.

Currently, there is no way to browse for a file from within the data viewer. This is because there is no portable way to examine a computer's file system in C.

Viewing the data

There are two ways to view portions of the data set: you can view all the data values on a single plane, or slice, that cuts through the data set, or you can view an iso-surface, a surface where all the data has the same value.

The slice may be oriented arbitrarily by changing two angles: the azimuthal angle and the polar angle. These angles define the direction of a vector perpendicular to the plane of the slice. Finally, the slice may be offset along this vector, so that it can be positioned anywhere in the data set.

The controls to manipulate the slice are found on the "Data" tab. You may use the sliders, or type in a value and press <Enter>. Alternatively, you can move the slice directly. Click on the slice, or press <Tab> until it's border is highlighted. Then you can use the following keys to move the slice:

Left, Right arrows: Change the azimuthal slice angle
Up, Down arrows: Change the polar slice angle
Page Up, Page Down: Change the slice offset
Home: Reset the slice angles and offset
End: Align the view to look directly at the slice

You can also click and drag the slice to change its orientation.

You can also see the actual data value under the mouse as you move it over the slice, by looking at the read-out at underneath the color legend. The X, Y and Z coordinates listed are the integer coordinates of the actual position in the data set that the mouse is pointing at, and are zero-based.

There are two parameters for the iso-surface. The first is the value of data the surface should be drawn at. This will create a surface through all the points in the data set that are equal to this value. Data points that surround this value will be linearly interpolated to guess the true position of the surface. Once again, you can specify the value either by moving the slider control for it, or typing in a value and pressing <Enter>.

The second parameter is the detail level. This controls how much of the data set is sampled when computing the iso-surface, and determines how many polygons will be used to comprise the final surface. The "High" detail level samples every point in the data set, and is as detailed as the surface can get, but this may be very slow on some computers, or with large data sets. The low detail level samples much less of the data set, and should be much faster, though it will miss many of the small and medium features of the surface.

Viewing the atoms and bonds

You can also view the atoms that make up the data-set. Each type of atom is assigned a color, so that all atoms of the same type are the same color. You may also specify the radius of the atoms (though currently all atoms share the same radius), by using the slider bar, or typing a number into the "Atom radius" text field and pressing <Enter>.

You may want to hide some atoms (but not all of them), for a period of time. There are several ways to do this. You can click on an atom to select it, or enter it's number in the "Current Atom" text field, and press <Enter>. You can also use the keyboard, by first clicking on an atom, or using the <Tab> key until its color changes. Then the left and right arrow keys will cycle through the atoms, including those that are hidden (which will temporarily be drawn with a wire-frame model). Once you have selected an atom, there are several ways to hide it or make it visible again. You may right-click on the atom, which will cause it to be replaced by a wire-frame sphere. If you right-click again, it will become solid again, in case you made a mistake, but if you click somewhere else, it will completely disappear. You may also use the <Spacebar> key to toggle whether or not the current atom is visible. Finally, you can use the "Hide Atom" or "Show Atom" button on the "Atoms" tab. There is also a "Show All Atoms" button which will make all hidden atoms visible again.

You may also add a bond from the currently selected atom to another atom. First select an atom by left-clicking on it, then hold down the Ctrl key and click on another atom. A bond will now be drawn between the two atoms. You may also enter the numbers of each atom into the "Bond from" and "Bond to" text fields, and the desired size of the bond, and press <Enter> to add the bond. You can change the size of a bond by selecting it, and then entering the new size in the "Bond size" text field, or adjusting the slider. You may delete a bond by selecting it, and pressing the <Backspace> or <Delete> keys, or with the "Delete Bond" button.

Bonds will be saved in a special file with the same name as the data file you are viewing, except with an ".aux" extension added. You do not need to do anything special to save the bonds, it is done automatically as you edit them.

Changing the bounds

You can change the amount of the data set being viewed by changing the size of the box surrounding it. If you make the box smaller, you can zoom in to particular parts of the data without having to worry about the parts around it. If you make the box larger, the data set will be repeated so you can see how molecules with periodic boundary conditions appear.

You may change the position of any one of the sides of the box by moving the appropriate slider in the "Bounds" tab, or by typing in a value and pressing <Enter>. The default minimum value is zero, and the default maximum value is one. Be warned that if you make the box very large, performance may degrade from having to draw the data set up to twenty-seven times over.

You can also change the size of the box with the keyboard. Press the <Tab> key until one of the sides of the box is highlighted in green, and then the following keys may be used to control the size of the box:

Left, Right arrows: Select a different side of the box to modify
Up, Down arrows, Page Up, Page Down: Increase or decrease the position of the current side of the box
Home: Move the current side of the box to its default position
End: Move the current side of the box to its furthest extent

Finally, you can left-click somewhere on the background of the viewport, and drag out a rectangle that will clip the box. While you are dragging, the actual portion of the box you are selecting will be highlighted in green. If you make a mistake, or want to back up, you can right-click on the background to restore your previous view.

Changing the view

There are several parameters which control how you are looking at the data set. The first is the zoom factor. The smaller this number, the closer you are to the point you are looking at. The larger, the farther away. You can set this by using the "Zoom" slider on the "View" tab, or by typing a number into the text field and pressing <Enter>.

The next set of parameters control the orientation of the data set. These are three angles: yaw, pitch and roll. Each one controls a rotation about a different axis, and together they can specify any orientation for the data set. You can change them by using the sliders on the "View" tab, or by typing in a number in their text fields, and pressing <Enter>. However, it is usually much more convenient to drag the data set into the orientation you want. You can do this by moving your mouse over one of the edges of the box, or one of the coordinate axes, and clicking and dragging. The data set will be rotated around the point you are looking at so that the point you clicked on is always under your mouse.

The final set of parameters is the point you are looking at. By default, this is the center of the data set. The point you are looking at appears in the center of the viewport, and is the point the data set is rotated around when you change the angles above. You can change this by using the sliders on the "View" tab, or by typing in a number into the corresponding text fields, and pressing <Enter>.

Finally, there are three special buttons provided on the "View" tab. The first, "Reset Orientation," resets all three angles that control your orientation to zero. The second, "Reset Position," will move the point you are looking at back to the center of the data set. The third, "Align to Slice," will change your orientation so that you are looking directly at the slice.

All of these things may be controlled directly with the keyboard as well. Either click on the background of the viewport, or press <Tab> until the coordinate axes are highlighted in green, and then you can use the following keys to control your view:

Page Up, Page Down: Zoom in or out
Left, Right arrows: Rotate the box around the Y-axis
Up, Down arrows: Rotate the box around the X-axis
Shift + Left, Right arrows: Rotate the box around the Z-axis
Home: Reset the orientation
End: Align the orientation with the slice
Ctrl + Left, Right arrows: Move the point you are looking at left or right
Ctrl + Up, Down arrows: Move the point you are looking at up or down
Ctrl + Page Up, Page Down: Move the point you are looking at in or out
Ctrl + Home: Reset the point you are looking at

Miscellaneous options

There are several other options you can use to control how you view the data set. The first is the "Data scale type," which controls how data values are mapped into colors. There are two options, "Linear" and "Logarithmic." A linear map simply scales the data into the range 0 to 1, and assigns a color to each value in that range. The logarithmic map scales the data linearly into the range 1 to e². Then the natural log of the resulting value is taken, and divided by 2, to provide a number between 0 and 1, which is then assigned a color.

The next option, "Color scale type," determines what colors are used to display the data values on the slice and to distinguish different types of atoms. There are two options, "Rainbow" and "Grayscale." The rainbow scale goes from blue for small values, through green, and ends up with red at large values. The gray scale goes from black for low values to white for high values. While a rainbow scale is often clearer, the gray scale may be better for printing.

The next option, "Background color," controls what color is used as a backdrop for the data set. There are two choices, white and black. Black often provides better contrast, but white may be useful for printing.

The final option is the "Projection type." This controls whether or not the data set is shown with 3D perspective, so you can judge depth information, or if it is projected straight onto viewport (orthographic). While the first often gives you a better idea of the relative positions of objects, the second is useful when looking along an axis to see how things line up.

Saving and printing images

There no facility provided within this program to save or print images of a data set. However, your computer may already provide you with the tools to do this. If you are running Windows, you can use <Alt> + <PrintScreen> to copy the contents of the current window to the clipboard. You can then use one of the utilities provided in your "Accessories" menu off your start bar to paste the window into an image to be saved or printed. If you are using UNIX, the popular program XV offers similar functionality, and is shareware.

Known Issues

This program can only read files ouput by VASP version 4.4.4 or later. Earlier versions used fixed-format FORTRAN files, while later versions used free-format, which is incompatible.

This program was written primarily for Windows, though it can be compiled and run anywhere that supports OpenGL and the GL Utility Toolkit. As such, it can only use the features of OpenGL 1.1, since this is the latest version shipping with Windows as of the time of this writing. OpenGL 1.2 provides an additional feature known as 3D texturing, which substantially improves the speed and quality of the rendered slice. The data viewer can take advantage of this feature, but only if it is compiled on a system that supports it. The Win32 binaries distributed here have not been compiled on such a system, and so if you want to use it, you will have to recompile the program yourself. Some systems claim to support 3D texturing, but I have been unable to get it to work on them (some Linux machines and some SGI machines). If you experience this problem, add the switch -D__DS3_NO_3D_TEXTURES__ to the CFLAGS variable in the Makefile under UNIX, or add __DS3_NO_3D_TEXTURES__ to the list at "Project / Settings / C/C++ / General / Preprocessor definitions" under Windows.

The <Delete> key does not work under Windows. This is a bug in the GL Utility Toolkit that will hopefully be addressed in future versions. You can use the <Backspace> key instead.

The Shift + <Tab> key does not work under some versions X-Windows. This is a bug in the GL Utility Toolkit that will hopefully be addressed in future versions. This will prevent you from changing the keyboard focus from component to component in the reverse order. You can use any other modifier key (e.g. Ctrl or Alt) instead.

Acknowledgements

I would like to offer special thanks to Dr. David Cox, in Chemical Engineering at Virginia Tech. He gave me some valuable advice when trying out the alpha versions of the viewer. I would also like to thank Dr. Doug Bowman, in Computer Science at Virginia Tech, who gave me a few good ideas for the direct manipulation of the data set.

Download

Binaries are availble for 32-bit Windows systems. The source code is available under the GNU General Public License, and includes an MSVC++ 5 project file and a Makefile (that may require manual editing; if you want to write a more general Makefile, or just one for a specific platform, feel free to send it to me). If you use this program, or make modifications to the source, please drop me a line.

Current version: 1.05 (2001/08/19)

Win32 Binaries (~175K)
Mac OS X 10.4 (Tiger) Binary (~96K) (Contributed by Graeme Henkelman)
Source Code (.zip format) (~328K) (includes Win32 binaries)
Source Code (.tar.gz format) (~294K) (includes Win32 binaries)
Sample data file (~647K)
Sample data file (.zip format) (~114K)
Sample data file (.tar.gz format) (~105K)

Comments or questsions? Send them to tterribe@users.sourceforge.net