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:

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

Command

Purpose

filename

: name of a grid file, or XYZ file, or molden file. If this parameter is omitted program will try to find a first relevant file in the current directory.

-h

display help information

-n filename

create an empty XYZ file

-d real

set an initial size for the molecule

-f filename

set the basename of output files (.xyz, .tga, .eps, .pov). By default the basename is taken from the filename.

-s integer

Set initial size for the screen.




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

Command

Purpose

-l real

: set initial isolevel value

-i real

: set increment value for changing isovalue

-t real

: set transparency level (between 0.0 and 1.0) for isosurfaces

-b color

: set initial background color ( white|gray|black)

-o integer

: set the number of initial orbitals (by default: display density)

filename2

: name of a second grid file to display a density difference

-a real

: a weight of second grid. The default is -1 (to calculate density difference).

--out filename

: specify output file name for a grid constructed with -a option.

--version

: print the version number



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.

Command

Purpose

Ctrl-Q

Quit

F10

Exit (exit implies possible back up of edited files).

Escape

unset different editing modes

F1

Display the help screen (with a list of hot-keys)

q/Q

decrease/increase quality of drawing

F2

save INPORB file or XYZ file

F9

Save current settings

Shift+F9

Edit colors for background, labels, orbitals and extra planes.

r/R/g/G/b/B

Interactively change RGB code for the background, labels, and orbitals (selected by Shift-F9 key)

F5

Print screen in tga format. The output files will be named as filename000.tga

Shift+F5

Print screen in PostScript format. The output files will be named as filename000.eps

P

Print screen in PostScript (level 2) format.

p

Save povray file.

z/Z

Zoom the grid or the molecule

x

Maximize the screen

v/V

Create/restore .ViewPoint file (viewing conditions)

Home

Move the molecule to the center of the screen

Up/Down/Left/Right

Move the position of the picture on screen (with shift - make bigger steps)

l

Switch to/from the mode: move the light position with the mouse.

w

Switch between grey-scale and colored picture

m

Start/stop animation

W

Switch to Tee time mode

Hot keys in Grid Mode.

Command

Purpose

+/-

increase/decrease the isosurface value (the step and initial value can be modified by command line parameters)

PageUp/PageDown

display next/previous orbital. In multiview mode (F3 has been pressed), use magnify glass.

t/T

change transparency level

f/i/1/2(a)/3/s/d

change the type of the current orbital to frozen, inactive, RAS1, RAS2, RAS3, secondary, deleted.

Space/middle mouse

change the type of the current orbital (by loop)

F2

save INPORB file (file will be saved as filename.GvOrb)

F3

Switch to/from multiview mode. In multiview mode the orbital type is shown by different backgrounds (rainbow colors). User can modify the type of orbitals, by pressing middle mouse button (or Space).

F4

Enter an isovalue (if a number was typed), or an orbital number (# n m - to display orbital with symmetry n and number m), or create a filter (for more information check tutorial for GV).

Delete

Hide the orbital from the list

Insert

Restore all hidden orbitals

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.

Command

Purpose

F2

Save coordinates (file will be saved as filename000.xyz)

Shift-F2

Save coordinates (overwrite the file)

left mouse

select an atom by clicking on it.

left mouse + shift

mark an atom

drag left mouse + shift pressed, followed by left click

mark atoms in the rectangular area

F3

display menu with molecular fragments.


Hot keys in if no atoms are selected

Command

Purpose

+/-

change a size of atoms and bonds

Insert

add an atom, or last inserted fragment

End

add dummy atoms (reference points) on the direction of axis.

a

Mark hydrogen atoms in the molecule

F8

analyze the symmetry of the molecule and display symmetry elements.

Delete

delete dummy atoms

Home

Move the molecule to the center of screen

*

Reverse the selection

#

if several atoms are marked, sort them, and place into the beginning of xyz file.


Hot keys in Selection mode (1 atom is selected)

Command

Purpose

Space/middle mouse

remove selection.

F3

display a menu with fragments, to be inserted close to selected atom

Insert

add an atom (or last selected fragment) near selected atom

Delete

delete selected atom

Home

place the origin to the position of selected atom

PageUp/PageDown

Change selected atom to one from the list (H,C,N,O,F,S,Cl)

F4 or =

invoke an edit box, where you can type an element name for selected atom.

F7

Mark atoms connected to the selected atom.

a

Mark all atoms which are the same elements as selected

F8

apply Inversion symmetry around selected atom

+/-

desaturate the color of the atom


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

Command

Purpose

Space/middle mouse

remove selection.

Insert

create a bond between selected atoms

Delete

delete the bond between selected atoms

PageUp/PageDown

change the type of the bond between atoms

+/-

change the distance between atoms. Note that first selected atom (blue) will move.

F4 or =

invoke an edit box, where you can type an interatomic distance

F7

Mark all connected atoms around the first atom in a selected bond into a group.

F8

apply translation by the axis specified by selected atoms.

F6

Watch the value of selected bond

#

Change the order of selected atoms

v

toggle behavior of F8: use C2 symmetry instead of translation


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

Command

Purpose

Space/middle mouse

remove selection.

+/-

change the angle between selected atoms. Note that first selected atom (blue) will move.

PageUp/PageDown

change the angle according to 'standard' angle values (by loop)

F4 or =

invoke an edit box, where you can type an angle value (or, you may type the value directly)

F8

apply mirror symmetry around an plain specified by selected atoms.

F6

Watch the value of selected angle

3

draw a triangle between points

4

Draw a plane

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

Command

Purpose

Space/middle mouse

Remove selection.

+/-

Change the dihedral angle between selected atoms. Note that first selected atom (blue) will move.

F4 or =

Invoke an edit box, where you can type a dihedral angle value (or, you may type the value directly)

F6

Watch the value of selected angle

F7

Mark atoms located at other side from the plane defined by selected atoms 2-3-4, in comparison to atom 1

F7+Shift

Use selected atoms as a cell, and mark atoms outside this cell

6

Draw a cell, using selected atoms as axis definition. First atom indicate the origin.



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

Command

Purpose

PageUp/PageDown

Display charges


Hot keys in Molden mode for a frequency file

Command

Purpose

PageUp/PageDown

Load next/previous vibration mode

F3

Draw graphical information in a separate window.

+/-

Change the speed of vibrations


Hot keys in Molden mode for a geometry file

Command

Purpose

PageUp/PageDown

Load next/previous geometry

F3

Draw graphical information in a separate window.

Home

Show initial structure

End

Show the resulting structure










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 H2O2 molecule started from Water.xyz file.

Now we will continue to edit the H2O2 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).

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 (D2h 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 C2 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  Cinstead 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).