ELF with TopMod
About this document
Last updated 18/Oct/2000.
Written by Dr. Alex M. Clark (email: firstname.lastname@example.org)
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
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.
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
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
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:
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.:
- 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 N3 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 Gaussian_elf.sbf sodiumchloride.v5d
All going according to plan, sodiumchloride.v5d should now exist.
- 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.
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:
... 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.
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).
- 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.