MOLCAS grid and geometry viewer: GV

MOLCAS Grid/Geometry Viewer/Editor (GV) is an OpenGL based code for visualization of molecular orbitals and densities, density differences and spin-densities, and visualization of molecular structures (with the possibility to manipulate them on the screen), and visualization of some properties.
The name should not be confused with gv (aka ghostview).

For installation GV requires headers and libraries for GLUT development. For Linux users we recommend to install libraries from http://www.mesa3d.org/. Alternatively you can try freeglut libraries. If you use GV in combination with MOLCAS, place the corresponding executable into  $MOLCAS/xbin/platform directory. Consult  xbin.cfg file for more information.

GV can operate with different kinds of files:

• grid files (usually with extension grid) (generated by the program GRID_IT from MOLCAS package),

• XYZ files,

• molden files, generated by MOLCAS.

If a file name is specified in a command line, GV will determine the type of the file, and switch to the appropriate mode. If no file is specified, GV will search the current directory for files with a known type.

 GV can run as a ordinary MOLCAS module (via command molcas gv filename), or as a stand alone executable.

Command line parameters for GV

The rest of command line parameters have meaning only for displaying grid files:

For an advance configuration of GV one can save the current configuration (see below), and edit the ASCII formatted configuration files. The configuration files are located in the subdirectory .molcasgv in user home directory. File gv.rc contains global settings, like colors, transparency, etc. File atoms.rc contains sizes and colors for each element.

The main control of GV can be done by the mouse: the left mouse button is used to rotate the grid or the molecule, right mouse button is used for the on-screen menu. The major operations from menus can also be performed by hot-keys. Note, that behavior of GV, e.g. on-screen menus and hot-keys is different for the different types of visualized files.

Some keys like PageUp/PageDown, plus/minus have different meaning in different modes, with a general rule - plus/minus changes a value, PageUp/PageDown changes a property of selected item.

Note for Mac users. To press functional keys (F1-F10) you have to use 'fn' button. Insert button (missing on Mac keyboard) can be emulated by 'I' key.

General HotKeys.

Hot keys in Grid Mode.

If GV is used to display a molecule, it is possible to make a selection of an atom, a bond, an angle, or a dihedral angle by clicking (by left mouse button) on the atom. First selected atom will be displayed with a blue colored net, the rest (for bond and angle) with a magenta colored net. Using hot keys it is possible to make modification of the selected part of the structure. In addition to selection (note that only 4 atoms can be selected), it is possible to mark a group of atoms. Marking is made either by mouse (is Shift button is hold), or by keyboard (F7 button). Marked atoms can be modified as a single unit - e.g. rotated, moved. To remove current selection - press middle mouse button or space. If user has both selected and marked atoms - the first press of space button will unselect 'selected', and the second one - unselect 'marked' atoms.

 GV can understand an extended syntax of XYZ file, and draw additional elements: axises, polygons, etc.

Hot keys in Coordinate mode.

Hot keys in if no atoms are selected

Hot keys in Selection mode (1 atom is selected)

Hot keys in Selection mode for bond (2 atoms are selected)

Hot keys in Selection mode for angle (3 atoms are selected)

Hot keys in Selection mode for dihedral angle (4 atoms are selected)

Hot keys in Molden mode for a orbital file (e.g. scf.molden)

Hot keys in Molden mode for a frequency file

Hot keys in Molden mode for a geometry file

Tutorial

Editing molecular structures using the GV program.

Program GV is used to manipulate molecular structures, build new molecules, etc. It is also used to show orbitals , densities, etc. Here, we shall exemplify how structures are manipulated.

To open a coordinate file, use command gv.exe Water.xyz, or to create a new file, use flag -n:  gv.exe -n Water.xyz. If a filename is not specified, GV  will open a first coordinate file in the current directory.

Some common hot keys are shown if F1 key is pressed. And extra menu are available via right mouse click.

In order to make modifications of coordinates we have to select one, two, three or four atoms. Selection is made by clicking on an atom. The first selected atom is covered by blue-colored net, the following selected atoms are covered by magenta-colored net. The number of selected atoms determines the behavior of GV. If only one atom is selected - any operations will refer to this atom, if two atoms are selected - any operations will be done for the bond, connecting these atoms, if three atoms are selected - operations will be performed for the angle, and finally, four atoms defines the dihedral angle. As a general rule - '+/-' changes the value of selected object, PageUp/PageDown changes the property, = (or F4) allows to set up the value.
To remove selection - use 'space' button, or click middle button on the mouse.Pressing + or - will modify the value, e.g. if a bond is selected, and user pressed '+' key, the bond length will increase, so the first selected atom will move away from the second atom.

Example of selected atom:



pressing F4 (or =) and typing O (note that you do not need to focus into 'edit' window), we change the H atom to O.


It is also possible to use PgUp and change the atom name from the list of of most common elements.

Backspace button can be used to Undo modifications.

If two atoms are selected - the bond length can be modified (using +/- or =/F4)

Note that first atom (blue) is moving during the operation.

Similarly, if three atoms are selected - a value of the angle will be modified, and if four atoms are selected the dihedral angle will be modified.

Pressing PageUp/PageDown will modify the 'property' of selected object. If only one atom is selected - it will change element name, if bond is selected - it will change the type of the bond (single, double, etc.), and for angle selected, it will change the angle to most common values.

F2 key can be used to save the coordinate file. The file name will be generated from the original name, by adding a counter. Shift-F2 will overwrite the original file.

If one atom is selected it is possible to use Delete or Insert key to delete or insert a new atom. Let make H₂O₂ molecule started from Water.xyz file.

• select a H atom

• press PageUp until the atom becomes oxygen.

• select another O atom

• 

• press F4 and type 1.474 followed by Enter

• press Space bar to un select atoms.

• select H-O-O

• 

• press F4 and type 94.8 followed by Enter

• press Space button

• select 'new' Oxygen atom

• press Insert to add H atom near selected atom

• select two oxygen atoms

• 

• press F4 and type 94.8

• select remaining hydrogen atom to select dihedral angle

• press F4 and type 111.5

• fix O-H bond lengths.

Now we will continue to edit the H₂O₂ molecule. If we select the O-O bond and change interatomic distance - only one atom will move. If we want to move a group (O-H), we have to mark this group first.

There are different ways to mark atoms into a group. One can do this manually, clicking on an atom with pressed Shift button. Or, it is possible to mark connected (bonded) atoms, in respect to a selected bond. Select an O-O bond and press F7 button. All atoms, which are connected to the first selected atom will be 'marked', and shown as cyan-colored. Finally, holding a Shift key, and dragging a rectangular area by mouse - all atoms inside this rectangle will become marked.

Now we can move all marked atoms simultaneously:

If you change the length of the O-O bond, all marked group will move accordingly. Note that unselection (Space key, or mouse middle click) will remove selection first, and the second use of unselect button will remove marking of a group.

The modified value (of a bond length or an angle) is shown on the information line of the screen. Sometime you would like to observe another value during a modification of coordinates. To achieve such behavior, select a bond, or an angle, and press F6 button. Now you can make another selection and make modifications in the geometry. But in this case originally selected value will be watched. Pressing Shift-F6 key switches off the watching mode.

GV contains a short list of molecular fragments, which can be added to a molecule. Press F3 key, to get a list of available fragments. Clicking on a picture with a fragment, you will add this fragment into your screen. If no atoms are selected, the fragment will be added somewhere around the current molecule. If one atom is selected, the fragment will be inserted near the selected atom. Note, that once a fragment has been selected, an Insert key will insert this fragment.

Example. Let's make mesitylene (1,3,5-trimethylbenzene).

• open Benzene.xyz file

• mark (not select) 3 hydrogen atoms

• Press Delete

  

• select C atom, press F3 and click on CH3 icon

• select another C atom, and press Insert

• select third C atom, and press Insert

To make modifications of coordinates via distances and angles, you might need dummy (reference) atoms. These dummy atoms can be set by End button. If there is no selected atoms, 'End' key will add dummy atoms located on X- Y- and Z- axis. If a bond is selected, the dummy atom will be placed in the middle of the bond. For example, if you have a planar molecule, but it is not oriented according to Cartesian axis, you can add dummy atoms on each axis, mark all atoms in the molecule, and select a dihedral angle between the plane of the molecule and desired plane, created by dummy atoms.

Program GV can recognize the symmetry elements of a molecule, or apply symmetry operations for all, or marked atoms in the molecule. If no selection is made, F8 key displays symmetry elements of the molecule (D_2h subgroup only).

If some atoms are selected, F8 key will apply a symmetry operation: in case of only one atoms being selected inversion, in case of a bond, translation or C₂ axis, and in case of an angle - a mirror plane. This feature can be used to construct symmetrical molecules.

Let us start from a benzene molecule. Delete two hydrogen atoms (in ortho positions), and select two carbon atoms (with broken bonds). Press 'v' to use  C₂  instead of translation. Pressing F8 key will duplicate the structure, creating naphthalene.

If, during such transformation coordinates of a new atom are very close to another atom - the average coordinates will be used. For example, if you have an almost planar molecule, you can flatten it, by applying a mirror plane symmetry. Let move one carbon atom in benzene out of plane for a small angle.



Now we can select 3 carbon atoms, and press F8 to mirror the molecule. Moved carbon atom will return into the plane.



Also note, that if a part of the molecule is marked, the symmetry operation will be applied only for marked part.
In the example below, we marked 2 atoms, and select 2 another. F8 will translate marked group into vector defined by selected atoms.

GV can be customized. Press F9 key to save current setting. It will create a directory .molcasgv in user HOME directory, with default settings for used colors, initial sizes etc. User can edit this files to reset the default values.

GV can remember a ViewPoint (the current orientation of the molecule) and save it to a file. Later this file can be used to rotate another molecule accordingly. Use keys (v/V) to save or restore Viewpoint.

In some occasions, user would like to change the order of atoms in XYZ file. Although the simplest way to do this includes usage of editor, GV provides some tools for resorting. If two atoms are selected, and # button pressed, selected atoms will exchange their order. Pressing # resorts atoms.

GV provides some possibilities to modify appearance of the picture. To highlight some part of the molecule,
user can mark a part of the molecule, and use '-' key to make these atoms looks pale. 'A' key changes the
look of atoms.

GV understands some extensions of XYZ file. At the end of XYZ file it is possible to add lines #sphe (followed by 2 coordinates), #axis (followed by 2 coordinates), #tria (followed by 3 coordinates) to add correspondingly a sphere, an axis, or a triangle. 

Visualization of orbitals with GV

To visualize orbitals and density by program GV you have to compute a grid file (.grid) first by using GRID_IT program from MOLCAS package.
Note that the quality of the picture depends on the keywords used in GRID_IT input.

Orbitals can be browsed by PageUp/PageDown key, or selected by a menu, invoked by the right mouse button. If you know the symmetry and number of an orbital, you would like to display, you can press F4 (or =) key, and press # followed by symmetry and orbital number, e.g. (# 1 3).

In order to change isosurface value, you can use + or - key, or press F4 key, and type a desired isosurface value.

Sometime you would like to filter orbitals, shown by GV. Pressing Delete key you can hide an orbital. All hidden orbitals will become visible if Insert key is pressed. Alternatively, you can apply a filter to hide some orbitals by a criteria: symmetry number (s), orbital energy (e), occupation number (o), or typeindex (i). Usage of filters is clear from the following example: Press F4 key and type #: followed by a filter command - #:s14 to display orbitals only from symmetry 1 and 4, #:e-2:1 to display orbitals in an energy range between -2 and 1.

When the grid file is loaded, GV displays subspaces (frozen, inactive, RAS1, RAS2, RAS3, secondary, deleted). User can modify the typeindex of the orbital, save (F2 key) the INPORB file (it will have an extension GvOrb), and use this file in the following RASSCF calculation without having to reorder the orbitals. In order to modify the index of the displayed molecule, user can use a menu, or press one of the keys: fi123sd. Pressing Space key (or middle mouse button) changes the typeindex in a loop.

It is possible to display all orbitals of the grid file simultaneously. Press F3 key to get the screen with all orbitals.

By default, the background (rainbow colors) for each orbital corresponds to the type index information. Clicking on an individual orbital you can use the same keys to modify it's type, or delete it from the screen. Pressing F3 button again, or Escape will close the multiview mode. Using PageUp/PageDown in multiview mode will increase/decrease the sizes of subscreens. These features of GV can be quite helpful for selecting the different orbital spaces in RASSCF calculations.

GV can also be used to compare densities from different GRID_IT calculations. A command gv.exe -a 1.0 scf.grid rasscf.grid will compute a density difference between two grid file. A bit more complicated procedure should be done if you would like to visualize a density difference between two interactive molecules. First, you have to make a BSSE-like calculation, adding dummy atoms (with or without basis) in order to produce identical (in space grids). Let say, we computed 3 grid files A.grid, B.grid, AB.grid. Run gv.exe -a 1.0 A.grid B.grid --out sum.grid. GV will create a file sum.grid which is a sum (due to -a 1.0) of densities. Now, run molcas gv.exe -a -1.0 AB.grid sum.grid to compute the difference AB - (A+B).