CCL Home Page
Up Directory CCL moplot.man
  **********************************************************************
      PROGRAM MOPLOT
  *********************************************************************

    The main purpose of this program is to generate quasi three-dimensio-
    nal drawings of MO's as obtained from ab-initio and semiempirical pro-
    cedures using only the s and p basis functions. The original code was 
    created by A. Schmelzer and E. Haselbach at the University of Basel
    in 1970 to run on a PDP 9 minicomputer. The authors outlined their 
    approach in  Helv. Chim. Acta 54, 1299 (1971).

    Adaptation to MS-DOS microcomputers including thorough debugging
    was effected by T. Bally, B. Albrecht and S. Matzinger at the
    University of Fribourg over the period of 1986-94. At the same time
    the capability was added to have a (rudimentary) display of normal
    vibrations.

    We found that the most efficient way to use the program is to run it
    on a PC connected via ethernet to theworkstation where the quantum
    chemical calculations are carried out. Ideally, the disks of the 
    workstation should be mirrored on the PC via NSF or an equivalent
    protocol so that file transfers can be avoided altogether.

    We wish to emphasize that MOPLOT should not be measured by the stan-
    dards of commercial software. Although it has gone through many sta-
    ges of debugging, some glitches remain. For example, for large mole-
    cules, lines may appear outside the dedicated square on the screen
    for some rotation or elevation angles. Also, the user interface is 
    not as polished as required by modern standards. Nevertheless the pro-
    gram has proven very useful in many labs and we hope that users will 
    continue to appreciate its simplicity and speed if compared to some of
    the much prettier (and quantitatively more accurate) MO plots produced 
    by the likes of Hyperchem, CaChe, Charm etc.

    Hardware and software requirements:
    -----------------------------------

      -  IBM or compatible PC under MS-DOS 3.1 or higher (preferably
         486 or 386 equipped with 80x87 or compatible math coprocessor)

      -  VGA graphics adapter (color or monochrome, but color is of course 
         nicer) and compatible monitor.
         (The program will also run on PC's equipped with EGA or Hercules
         graphics hardware as well as on Olivetti or AT&T PC's. However,
         the pictures will be more or less distorted on non-VGA equipment
         because these earlier standards do not have an aspect ratio
         [No. of pixels/cm in x- and y-direction] of 1.)

      -  ANSI protocol driver (ANSI.SYS on most computers. *Must* be in-
         stalled in CONFIG.SYS or cursor control will not work!)

      -  Postscript printer (preferable)  or

      -  Any device capable of interpreting simple HPGL (Hewlett Packard
         Graphics Language) commands.

      -  Microsoft Fortran compiler, version 5.0 or later (if the program
         requires adaptation; see also the section on this topic below).


     Input:
     ------
     The current version of MOPLOT takes its input directly from the output
     files (*.out) of the  Gaussian9x, GAMESS, Zindo, Vamp, PPP, MOPAC and
     AMPAC  program packages. It searches for the keyword line to find out 
     what options were specified and then goes to look for the corresponding 
     information (geometry, eigenvectors, normal vibrations). Some sample 
     outputs are provided in the self-extracting archive EXAMPL.EXE.

     Users who wish to adapt MOPLOT to other inputs should look into the
     module READER. It may also be that the output files of certain of the 
     above mentioned programs is not identical on all installations, so that 
     READER may need to be adapted. People who need to do this or who would
     like to change other thigs in the program should look into the section
     "Adaptation of MOPLOT" later in this manual.

     Old versions of MOPAC contain page breaks in the form of a "1" in the 
     first column in the middle of, say, the eigenvecors. This confuses the
     reader and such outputs should be run through the DEPAGER utility
     we provide (type: depager "filename").

     If disk space or transfer time is at a premium, a lot of information
     can be deleted from the original output (for example interatomic dis-
     tances or all the unneeded very low or high lying MO's), but one must
     of course remain aware of what the respecive READER module is looking 
     for! This can be found inthe source code for the READER's which is
     provided (cf.below)

     Once the program is in display mode (see below), a new file can be read
     by hitting "F" whereupon the user is prompted for a filename.


     Display:
     --------
     By default, the molecule is first displayed such that the z-axis
     runs vertical, the y-axis horizontal (from left to right) and the
     x-axis is facing the viewer. The viewpoint can be changed by vary-
     ing the Eulerian anges corresonding to elevation (ELV, towards the
     x-axis) and rotation (ROT, clockwise around the x-axis) until suitable
     values are found. Furthermore, ORI adjusts the orientation of the
     projected geometry in the screen/paper plane. Viewpoint changes can
     be effected interactively by hitting the following keys (no ENTER
     required):

           -   E/R/O    (for 15 degree increments) or
           -   e/r/o    (for 5  degree increments)
           -   +/-      for changing the direction of rotation or elevation
           -   K        for direct input of ELV, ROT and ORI via keyboard

     If none of this works, a possibility exists to define a new z-axis
     (by typing "V") through two points, each of which can be an atom or
     the midpoint between two or three atoms. Within this new defini-
     tion of the axes, ELV and ROT (bot not ORI) can again be adjusted.

     Normally, the drawing is continually rescaled to fit onto a square
     on screen. After typing "C", a new scaling factor (in cm/Angstrom)
     can be entered and is then kept constant throughout all subequent 
     operations.

     Initially a parallel normal projection is used to display the geometry.
     Upon hitting "T" the user is asked to enter a factor (the distance to 
     the molecule) whereupon the display changes to a central projection.
     This factor can be adjusted by choosing "T" again. Entering a factor
     or zero returns the display to a parallel projection.

     With "A", the atom numbers as they appear in the geometry definition
     of the calculation (without dummies) are displayed in little circles.

     Typing "M" brings up the MO drawing mode and the user is asked for
     the MO to be displayed. MOPLOT accepts different possibilities here:
     
     > typing a number will display the MO with this number. In case of
       a UHF wavefunction, the user is prompted to enter a for alpha or
       b for beta. This can be avoided by directly following the number
       by a or b (such as "13 a" or "27 b")

     > typing "h" will display the HOMO ("h a" for alpha HOMO & vice versa)

     > typing "l" will display the LUMO ("l b" for beta LUMO & vice versa)

     Once in the MO-display mode one can toggle through the MO by hitting
     the arrow-up and arrow-down keys. Alpha and Beta MO's can be toggled
     by pressing the tab-key.

     The "S/s" allows to change the scaling of the MO-spheres relative to
     the geometry in 0.15/0.05 unit increments. Note that ELV, ROT and ORI 
     can again be changed to optimize the viewing angle, but redrawing the 
     picture may take a little longer at this stage. By typing "d" you can 
     see how an MO-picture is built up from the back to the front by hitting 
     the Enter key repeatedly (this was created for debugging purposes but 
     left in there for fun). "D" gets you back to the normal (quick) display 
     mode.

     **************************** IMPORTANT ***************************

     Note that MOPLOT is *not* intended to give accurate representations 
     of ab-initio wavefunctions in the sense of electron density plots, 
     but only to convey a semiquantitative idea of the nodal structure
     and the relative AO-coefficients in a ZDO approximation.

     For example, the contributions of the inner and outer basis functions
     in double-zeta wavefunctions are simply summed up and therefore the
     degree of flexibility intrododuced by such basis setsis not expressed
     in a MOPLOT display.

     Similarly, ab-initio MO's containing d- and f-functions are read
     by the READER-Routines but only the s and p part is retained to
     build the graphical representation. This is usually not a bad appro-
     ximation for first and second row atoms, but fails of course for ele-
     ments with d- or f-valence electrons. We may incorporate the display
     of d- and f- valence AO's in a future version of MOPLOT

     *******************************************************************

     Typing "N" brings up the normal coordinate display mode (of course,
     normal coordinates must have been read in for this to work). "S/s"
     scales the displacement vectors relative to the the geometry. Once
     this mode is entered one can toggle thru the vibrations by hitting
     the arrow-up and arrow-down keys.

     By typing "Y" a set of cartesian coordinates corresponding to the
     endpoints of the currently displayed displacement vectors of a 
     normal coordinate is written to disk. This option is useful for 
     example if a new geometry optimization with lower symmetry has to
     be carried out (i.e. following the reaction coordinate down from
     a transition state or for exploring Jahn-Teller type distortions)

     Bye typing the "W" key, a subprogram for evaluating selected geo-
     metrical parameters (distances, angles, dihedral angles) goes into
     action. The user is prompted to indicate two (for distances), three
     (for angles) or four points (for dihedral angles). Each of these
     points can be an atom or the midpoint between two atoms. Help is
     available for this option via the "H" command. 
 
     Bye typing the "F1" key the geometry optimization analyser is invoked.
     This subprogram, which works only for GAUSSIAN type outputs, permits
     you to read every cycle of the geometry optimization. Displacement-
     vectors indicating the change to the previous step are displayed in
     red, and can be scaled using the "S/s" key. Each time this subprogram
     is invoked the next intermediate structure is read from the disk, 
     until the optimization is finished, when MOPLOT returns to its normal
     mode. 

     If you are in "A","M" or "N" mode, "G" brings you back to the normal
     geometry display.

     Hard output:
     ------------
     Typing "Z" brings up the HPGL-plot mode. Plotting occurs using the 
     current viewing and scaling parameters. If an MO is to be plotted,
     the user is asked whether the two phases should be distinguished
     by continuous and dotted lines or whether a pause should allow for
     a pen change after drawing all the positive (or negative) lobes.

     HPGL-plotting makes use of a hidden line algorithm coded by Andreas
     Schmelzer (routine NOHOPE) which we never succeeded to debug comple-
     tely. Try to avoid ROT and ELV around multiples of 90 degrees or the 
     program may quit unexpectedly with a "zero divide" message (the prin-
     ter output described below does not use NOHOPE because the picture is
     built up by overlaying which is of course not possible on a plotter).

     With "L", Postscript output is invoked. First, the user is asked
     whether he wants to create a normal Postscript file which he can
     send directly to a printer or whether he wants to import the dra-
     wing into some graphics program (such as CorelDraw) capable of
     reading Encapsulated Postscript (EPS) files for further workup.
     In both cases a file name (without extension) must be given.

     Secondly, one must specify the size of the square boxes into which
     the drawings are fitted (give a floating point number between 2.0
     and 18.0 cm). The program will reply by informing the user how many
     of theses boxes will fit onto one page (more for small boxes). 
     After hitting any key, the current view is drawn into the first box
     which will be placed into to upper left corner of the page. Subse-
     quently, other pictures can be added at will (when a page is full,
     the next one will be started in the same mode). Good choices for
     the box size are 4.5 cm (gives 5 x 4 boxes) or 5.5 cm (4 x 3 boxes).

     On every subsequent invoking of "L", the user is asked, if the EPS-
     (Postscript) file should be finished. If the reply is "y" then the
     current view is *not* added to the picture. Thus, if you are done
     with drawing, or if you want to make drawings in different size 
     boxes call up "L" once again to close the EPS file. If you leave the 
     program, any open files will be closed automatically.

     Help and miscellaneous:
     -----------------------
     Typing ? brings up a little help menu on the right half of the
     screen which summarizes the above commands. Any operation leads 
     back to the main menu (for reading in a new file), with Q the
     program may be exited.

     Adaptation to other environments:
     ---------------------------------
     The graphics part of the program is implemented by means of the
     graphics library modules that come with version 5.1 of Microsoft
     FORTRAN. Users who prefer to use other FORTRAN compilers should
     look for appropriate replacements for the graphic function calls.

     Since all information is mapped onto a screen with an aspect ratio
     of 1, one would actually have to draw ellipses rather than circles
     to get circles on screens with a different aspect ratio (this is
     a possible field of action for users who do not have VGA hardware).

     People who are unhappy with our choice of colors should look into
     the routine MCOLDEF where all definitions are conveniently assembled

     Adaptation of MOPLOT
     --------------------
     Some aspects of MOPLOT can be customized by users who have MS Fortran
     5.0 (or later). This concerns in particular the READER modules which
     are provided in a self-extracting archive file SOURCE.COM, which con-
     tains also the module MOCOLDEF.FOR where all the colors are defined.

     Once extracted, any of these .FOR files can be edited. After this 
     they can be recompiled and linked with the object modules provided
     in the self-extracting OBJECT.EXE library, using an appropriately
     modified version of COMPILE.BAT. If people write new READER modules
     we would very much appreciate to participate in these new develop-
     ments and be able to distribute them to other colleagues.

     If someone thinks he needs to modify other parts of MOPLOT, he should 
     contact us (bally@cfruni52.bitnet or Thomas.Bally@unifr.ch) and we
     will discuss the modalities of releasing other parts of the source
     code (usually this poses no problem)
                                        
     Copyright
     ---------
     There are no formal copyright clauses attached to MOPLOT. However,
     the authors would very much appreciate if, instead of freely distri-
     buting daughter and granddaughter copies of MOPLOT, interested col-
     leagues would be encouraged to contact us directly and obtain a
     primary copy of the latest version. Users who are "registred" in
     this way will also be kept aware of new developments. Please write to:

                         Thomas Bally
                         Institut de Chimie Physiqe
                         Uni Fribourg, Perolles
                         CH-1700 FRIBOURG
                         Switerland

                Tel:     (41) 37 826-489
                FAX:     (41) 37 826-488
                E-mail:  BALLY@CFRUNI52 (later: Thomas.Bally@unifr.ch)

     Finally, anyone is welcome to play with the program. Again, we would
     be very glad if we would be informed of new developments (adaptation
     to new hardware, fixed bugs etc.) so we and other users may profit
     from them.
                                               Have fun!

                                            Thomas & Stephan

 ************************************************************************
Modified: Tue Aug 29 16:00:00 1995 GMT
Page accessed 6360 times since Sat Apr 17 21:34:54 1999 GMT