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

    Na -1.19 0.0 0.0
    Cl 1.19 0.0 0.0

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
    elf.pl sodiumchloride.wfn
    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.

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
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.

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).