ELF with TopMod

About this document

Last updated 18/Oct/2000.

Written by Dr. Alex M. Clark (email: aclark@reedgroup.ucr.edu)

This document describes how to use the TopMod suite of programs, available from http://www.lct.jussieu.fr/pagesperso/silvi, in order to prepare and visualise ELF (Electron Localisation Function) data.

What you need

Linux, or other Unix variant. This document has less, if any, relevance to other operating systems. You will need to be running X-windows to view the output.

The TopMod packages, topmod.tar.gz and sbfv5d.tar, can be downloaded at no cost from http://www.lct.jussieu.fr/pagesperso/silvi. These are distributed as Fortran source and makefiles, and are responsible for doing the hard work of the calculations.

elf.pl (optional). This Perl script makes the process of running the ELF calculations somewhat less painful by automating the bulk of the procedure.

vis5d-5.0.tar.Z, the visualisation program suitable for examining the ELF data. This is freely available (GPL) from http://www.ssec.wisc.edu/~billh/vis5d.html - you can find a link to it from Bernard Silvi's page around the same time you acquire the TopMod programs.

A Fortran compiler (for TopMod) and a C compiler (for Vis5D). The standard GNU compilers that are always present with any Linux distribution, and available for every other brand of Unix, work without problems.

Gaussian 94 or 98. This is unfortunately a commercially available program, so you need to either spend money or be lucky enough to work somewhere that has a site license. Alternatively, GAMESS is capable of generating the requisite wavefunction file.

Assumptions: You need to be familiar with Unix to the extent of being able to compile programs, edit text files, etc.; not necessarily a guru, but familiar with routine useage and installation. You must also be able to operate Gaussian or GAMESS with some proficiency, although this document will explain some of the steps involved for Gaussian in moderate detail.

Setting up

The TopMod programs are not especially difficult to install, and some rudimentary instructions are available with the package. First, unpack the file topmod.tar.gz into a directory of choice.

As is explained in the README file, copy Makefile.std to Makefile (for Linux, anyway), then run make.You should have several new files appear, most importantly the executables top_*.

Next, unpack sbfv5d.tar into the same directory. It will overwrite the existing Makefile, but you won't need that again anyway. Run make again, and you will get the executable sbf_to_v5d, which is important and necessary.

If you have a copy of elf.pl, you might want to make sure that it has the executable flag enabled, and if not, type chmod +x elf.pl.

Installing Vis5D is relatively well documented, so it will not be covered. You should end up with an executable file vis5d which you can install to a permanent location on your system, or just leave it sitting in a subdirectory from where you are keeping the TopMod programs.

Likewise, installing Gaussian or GAMESS is beyond the scope of this document (personally I would like to be able to use output from other programs, and may cater for this one day, but not just yet).

Generating a Wavefunction file

The Electron Localisation Function (ELF) is based on molecular orbital wavefunctions, a suitable format of which can be output by Gaussian. Thus you must use an appropriate computational package to optimise the geometry, then run Gaussian to generate a text file suitable for use by TopMod. This file typically takes the extension .wfn.

Following is an example of a suitable Gaussian input file:

    # RHF/6-31G* Output=WFN SP

    Gaussian input file... generated by Xykron, see http://servus.ucr.edu

    0,1
    Na -1.19 0.0 0.0
    Cl 1.19 0.0 0.0

    sodiumchloride.wfn

Simply running this file through Gaussian (regardless of whether you choose to capture the general output) will cause the file sodiumchloride.wfn to be created, which is a formatted text file. This file contains everything you need for the ELF procedure.

The ELF Procedure

Make sure the Wavefunction file (e.g. sodiumchloride.wfn) is in the same directory as the TopMod files. The procedure will eventually lead to a corresponding file with the extension .v5d. There are two ways to do this:

The easy way

Assuming you have elf.pl conveniently handy, type:

    elf.pl sodiumchloride
	        or
    elf.pl sodiumchloride.wfn
	        or
    perl elf.pl sodiumchloride

For a properly configured system, the above statements should have identical results; if you do not have the current directory listed in the $PATH environment variable, or do not have elf.pl set as an executable, try the last option. If you don't have Perl installed on your system, you're out of luck, and will need to do it the hard way.

If elf.pl works, it will do all the steps in the next section for you automatically, and you won't have to worry about any of it.

The hard way

Only one of the TopMod programs is necessary to build regular ELF output, and one more program to convert it to something viewable. The former is pure, portable Fortran 77, which means it can't even take command line parameters.

top_grid: Run the program, and get ready to type in various information. Press ENTER after answering each question, and do not be perturbed if nothing appears to be happening - that just means it's computing busily.

You will be asked for a Wavefunction file; enter 'sodiumchloride.wfn' or whichever file you wish to use.
Enter 'y' in response to outputting density.
You need to know the bounding size of the box you wish to compute - i.e. the space of the molecule to use for the ELF computation. Note that if you were using the elf.pl script, this would be determined for you automatically. In the sodium chloride example, a suitable bounding box is (-5,-5,-7) to (5,5,7), assuming that the linear, gaseous 'NaCl' molecule is centred at (0,0,0) and linear along the Z-axis. top_grid will prompt you for the origin of the bounding box, so enter '-5,-5,-7' for this example. The next question is the extent of the edges, which is the size of the box, not the endpoint coordinates - therefore, enter '10,10,14' (not '5,5,7').
The next question is the number of points on each axis. The more points you enter, the finer will be the grid - finer grids make for better looking output, but generate N³ larger files and longer computation times. For a rough calculation, 1 point per Angstrom will look better than you might expect; for better quality output, increase these numbers. Thus for this example, enter '10,10,14'.
This should be all - the program should inform you that Gaussian_elf.sbf and Gaussian_rho.sbf have been created.

sbf_to_v5d: This program is hybrid C and Fortran, and wants two command line parameters. The first has to be Gaussian_elf.sbf, which is the output file of interest from the previous step, and the last is the output filename of the Vis5D file, which in this example would be sodiumchloride.v5d, i.e.:

    sbf_to_v5d Gaussian_elf.sbf sodiumchloride.v5d

You will be asked whether your source is a syn or a bas file - enter 'syn'.
When prompted for the step size, enter '1', which works fine.
The program dumps core if there is an error, typically caused by the file being shorter than it was expecting, for whatever reason - this tends to mean that you must have made a mistake somewhere along the line! Go directly to jail, do not collect $200.

All going according to plan, sodiumchloride.v5d should now exist.

Viewing ELF

Once the ELF data has been converted to a Vis5D file, you will be unsurprised to know that you now run Vis5D in order to view it. You must have the executable file vis5d in the current path one way or another in order to proceed.

There is one minor flaw in execution of Vis5D, in that it doesn't automatically scale the boxes to the size you'd like them to be. Therefore if you type:

    vis5d sodiumchloride.v5d

... you get your molecule, but the dimensions will be skewed. However, immediately after building the Vis5D file, you will have been told to invoke the program with an additional command line parameter (the wording depends on whether you did it the hard way or the easy way). In this case, the preferred incantation is:

    vis5d -box 10 10 14 sodiumchloride.v5d

... which will scale the box to the appropriate size. The proportions are relative, so '5 5 7' would have the same effect. Note that if you used elf.pl, you will have another file - filename.sh, which contains parameters for running Vis5D. This saves you the effort of remembering the dimensions of each resulting graphics file.

Using Vis5D

Vis5D is a fairly complex program designed for more than just the simple uses we intend it for. Upon loading, it displays two windows. The main window contains a series of buttons, while the display window shows an empty cube.

Click on the display window with the left mouse button to rotate, middle mouse button to shrink/expand, right mouse button to move. This is not very interesting just yet, since it's just an empty wireframe box...

Near the bottom of the main window are 6 buttons all of which say ELF. This is not particularly informative, but clicking on any one of them turns a certain display property on.

The first button actives the overall electron density surface. Before you see anything, however, you must select a point on a slider in a window that appears, then press the button labelled 'OK', also on that window. Selecting a value of about 0.5 (halfway along the slider) is a good start. Once the OK button is clicked, the electron density surface appears in the display window. Rotating the box and altering the cutoff value (0 to 1) provides endless hours of amusement.
The second and third buttons activate planar contour maps (up to two of them are available, and by default they are orthogonal to one another). The maps are not much use unless you move them around within the box: on the main window there are several other buttons, one of which is highlighted and reads Normal. Below it is a button labelled Slice. Click on this, and you will be able to (with a bit of practise) move the contours around within the grid using the right mouse button.
The fourth and fifth buttons activate planar maps which are labelled by colour rather than contour.
The sixth button brings up something that looks cool, a three dimensional colour coded map of electron density - like the first button, but a 'shades of colour', rather than an actual surface with a particular cutoff value.

Undoubtedly there are a great many other features, but that should be enough to start with. The button near the top of the main window labelled SAVE PIC is suitable for capturing the on-screen image (recommend saving as a ppm file, as this particular bitmap format is well supported by various X programs).