<\body> \; |<\doc-note> |||<\author-address> Department of Chemistry University of Fribourg, ch. du Musée 9 Fribourg 1700, Switzerland >|||<\doc-author-data> \; > <\table-of-contents|toc> |.>>>>|> 1Introduction |.>>>>|> 2Features of PyVib2 1.0 |.>>>>|> 3Installation Guide |.>>>>|> 4User's Guide |.>>>>|> Input files |.>>>>|> > Preparing input files |.>>>>|> > DALTON |.>>>>|> > Gaussian |.>>>>|> > Overview : what can be done with PyVib2 |.>>>>|> > Quick Start Guide |.>>>>|> > Opening a file |.>>>>|> > Summary of the available data |.>>>>|> > Exploring structure and vibrational motion |.>>>>|> > Plotting spectra |.>>>>|> > Raman / ROA generation |.>>>>|> > Starting PyVib2 |.>>>>|> > Troubleshooting |.>>>>|> > Main window |.>>>>|> > Menu bar |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Button toolbar |.>>>>|> > Thumbnails pane |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Isotopic composition dialog |.>>>>|> > |.>>>>|> > |.>>>>|> > PyVib2 settings dialog |.>>>>|> > |.>>>>|> > Molecule window |.>>>>|> > Menu bar |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Button toolbar |.>>>>|> > 3D render widget |.>>>>|> > Vibrational toolbar |.>>>>|> > Navigation toolbar |.>>>>|> > Geometry toolbar |.>>>>|> > Status line |.>>>>|> > Molecule window settings dialog |.>>>>|> > |.>>>>|> > |.>>>>|> > Save vibrations dialog |.>>>>|> > Save animation dialog |.>>>>|> > Snapshot dialog |.>>>>|> > Correlate vibrations interface |.>>>>|> > Wizard |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Correlation results window |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Simultaneous window for two vibrations |.>>>>|> > |.>>>>|> > |.>>>>|> > Raman / ROA generation interface |.>>>>|> > Top panel |.>>>>|> > Button toolbar |.>>>>|> > Molecular invariants tab |.>>>>|> > ACP tab |.>>>>|> > Vibration tab |.>>>>|> > Define groups dialog |.>>>>|> > |.>>>>|> > |.>>>>|> > IR / VCD generation interface |.>>>>|> > Plotting Spectra |.>>>>|> > Raman / ROA / Degree of circularity spectra for a single molecule |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Spectra settings dialog (single molecule, see section ) |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Single vibration window |.>>>>|> > Raman / ROA / Degree of circularity spectra for several molecules |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Spectra settings (several molecules, see section ) |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > Raman / ROA / Degree of circularity spectra of a mixture of conformers |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > IR / VCD spectra for a single molecule |.>>>>|> > Spectra settings dialog (single molecule, see section ) |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > |.>>>>|> > IR / VCD spectra for several molecules |.>>>>|> > Spectra settings dialog (several molecules, see section ) |.>>>>|> > IR / VCD spectra of a mixture of conformers |.>>>>|> > The pyviblib class library |.>>>>|> > Overview |.>>>>|> > Example session |.>>>>|> > PyVib2 resources |.>>>>|> > pse.dat |.>>>>|> > isotopes.dat |.>>>>|> > .pyvib2rc |.>>>>|> > 5Theoretical background |.>>>>|> Vibrational motion |.>>>>|> > Overlaps and similarities of vibrational modes |.>>>>|> > Nuclear and Group Coupling Matrices |.>>>>|> > Atomic and Group Contribution Patterns |.>>>>|> > Spectra |.>>>>|> > 6Acknowledgements |.>>>>|> |.>>>>|> |.>>>>|> |.>>>>|> This is a documentation for the PyVib2 program, a program for analyzing vibrational motion and vibrational spectra, version 1.0, February 2007. The program is released under the terms of the GNU General Public License (GNU GPL). For downloading, please visit . Supplementary material will be soon available on . The main idea of the program was to create a simple and efficient tool for the automatic correlation of vibrational motions of molecules, exploring their Raman, Raman optical activity (ROA), infrared (IR), and vibrational circular dichroism (VCD) spectra. PyVib2 is supposed to be an open source ``all-in-one'' solution available to the international community of scientists, working in the field of vibrational and vibrational Raman optical activity (VROA) spectroscopy. <\itemize-dot> Extraction of the VROA data from results of calculations with the DALTON and Gaussian quantum chemistry packages. Intuitive graphical user interface (GUI) which allows to handle several molecules simultaneously. Comprehensive range of supported output formats. The program is designed as a class library, which can be used independently of the GUI. Versatile representation of vibrational motion : <\enumerate-alpha> cartesian excursions and vibrational energy distribution represented as shaded spheres; usual arrow representation; animation with the possibility to save in the animated GIF or Autodesk Animator FLI formats; Automatic correlation of the normal modes of molecules with the possibility of removing translational and rotational contaminations. Visualization techniques for vibrational intensities : <\enumerate-alpha> Nuclear and Group Couling matrices (NCMs and GCMs) for the individual Raman/ROA invariants or the differential cross-sections; Atomic and Group Contribution Patterns (ACPs and GCPs); Publication quality Raman/ROA/Degree of circularity as well as infrared vibrational absorption/VCD spectra in the stick and curve representations. The program is implemented in pure Python. Make sure that you have Python 2.3 or later (). Once the Python environment is operational, one has to install packages on which PyVib2 depends : <\itemize-dot> (Pmw), refer to . A library for a flexible GUI building, based on Tkinter (Python's de-facto standard GUI package). , refer to . The fundamental package for scientific computing. (Visualization ToolKit), refer to . A high-level 3D rendering library. , refer to . A 2D plotting library for producing publication quality figures. Do not forget that the administrator privileges are required in order to succeed the installation. The user of a Debian-based Linux distribution can profit from the utility, since all the required packages are already in the Debian repository. To install e.g. , execute\ <\code> $ apt-get update && apt-get install python-matplotlib The PyVib2 program itself can be installed on your system using the standard Distribution Utilities for Python (distutils) : <\itemize-dot> Download the program archive from . Unpack it e.g. by executing in the command prompt : <\code> $ tar xvfz pyvib2-1.0.tar.gz Change to the installation directory, created in the previous step : <\code> $ cd pyvib2-1.0 Execute the setup.py script as follows : <\code> $ python setup.py install After that, the script, which starts the program, should be accessible from the command prompt. It is usually placed by distutils in under Linux and in under Windows ( is a directory where Python is installed). To produce PDF files must be installed. If the user desires to create animations of vibrations in the animated GIF or Autodesk Animator FLI formats, the installation of additional utilities is needed. For the former choice, install the and the packages. For the latter choice, install . As these utilities are primarily designed for Linux/Unix, Windows users might want to install in order to be able to use them. PyVib2 can directly extract all the required data from outputs of VROA calculations conducted with DALTON 1.x or 2.0 . The program can also get the data from Gaussian98 and Gaussian03 via formatted checkpoint (FCHK) files, which can be created with the formchk utility program available in the Gaussian package. VOAView files can likewise be handled. A partial support for MOLDEN files is provided, from which only the normal modes can be extracted. XMol XYZ files can be opened for viewing the structure. It is briefly described in this subsection how to request a ROA and a VCD calculation with DALTON 1.x or 2.0 and Gaussian 03. The results of such calculations can be directly opened with PyVib2. It is assumed here, that the user has already an optimized geometry of a molecule of interest. As an example, let us consider methyloxirane. Earlier versions of DALTON required several files as input. The input specification has been changed in DALTON 2.0, but the old format is still supported for the backward compatibility. The user is instructed bellow on how to perform a calculation with DALTON 2.0 using input files produced for the older version. Discussing all the details is far out of the scope of this manual, for explanation refer to the documentation . The so called molecule specification file has to contain the geometry of a molecule and a basis set for a calculation. Save the following input as (coordinates are given in atomic units i.e. bohrs): \; <\samp> BASIS aug-cc-pVDZ IR/VCD or Raman/ROA for methyloxirane @ TDHF/aug-cc-pVDZ. \; \ \ \ \ 3 0 0 \ \ \ \ \ \ \ \ 8. \ \ \ 1 O001 \ \ \ \ 1.5654116200 \ \ \ -1.4893215100 \ \ \ -0.4579504440 \ \ \ \ \ \ \ \ 6. \ \ \ 3 C002 \ \ \ \ 1.9701227300 \ \ \ \ 1.1644266000 \ \ \ -0.1106471260 C003 \ \ \ -0.2917697530 \ \ \ -0.0707325890 \ \ \ \ 0.9160939940 C004 \ \ \ -2.8519480600 \ \ \ \ 0.1876438060 \ \ \ -0.2808812160 \ \ \ \ \ \ \ \ 1. \ \ \ 6 H005 \ \ \ 3.5401090600 \ \ \ \ \ 1.6542116000 \ \ \ \ 1.1409732900 H006 \ \ \ 1.8079463500 \ \ \ \ \ 2.3036101900 \ \ \ -1.8285083400 H007 \ \ -0.2907700570 \ \ \ \ -0.4889270930 \ \ \ \ 2.9449531000 H008 \ \ -2.6780158100 \ \ \ \ \ 0.6093702210 \ \ \ -2.3041524100 H009 \ \ -3.9227199200 \ \ \ \ \ 1.7180365500 \ \ \ \ 0.6308719600 H010 \ \ -3.9382721200 \ \ \ \ -1.5697562300 \ \ \ -0.0679279775 \; In the so called DALTON input file, the user has to specify the type of the calculation. To request a VCD calculation at the TDHF/aug--cc-pVDZ level of theory, save the following input as : \; <\samp> **DALTON INPUT .RUN PROPERTIES .PRINT 1 **WAVE FUNCTIONS .HF *ORBITAL INPUT .AO DELETE 1.0D-07 **PROPERTIES .VCD .VIBANA *VIBANA .HESFIL **END OF INPUT \; Do *not* request a verbose output with = 2>. The keyword specifies, that the hessian in the hes format is passed to DALTON. Rename the hessian file to (case-sensitive) and make a gzipped tarball from it (the name is arbitrary) : \; \; One can generate automatically both molecule input and hessian file from a Gaussian formatted checkpoint file () with the utility distributed with DALTON. The following command creates and files from (passed *without* extension): \; \; The VCD calculation can be started as follows : \; \; Note, that *all* the input files are passed *without* extensions ! After the calculation has been successfully finished, the output file can be opened with PyVib2. To request a ROA calculation, the user can use the following DALTON input file : \; <\samp> **DALTON INPUT .RUN PROPERTIES .WALK .MAX IT \ \ \ \ \ 200 .PRINT \ \ \ \ \ 1 *WALK .NUMERI .DISPLACEMENT \ \ \ \ \ 0.001 **WAVE FUNCTIONS .HF *ORBITAL INPUT .AO DELETE \ \ \ \ \ 1.0D-07 **START .VROA *ABALNR .THRESH \ \ \ \ \ 1.0D-08 .FREQUE \ \ \ \ \ 1 \ \ \ \ \ 0.08564539532 **EACH STEP .VROA *ABALNR .THRESH 1.0D-08 .FREQUE \ \ \ \ \ 1 \ \ \ \ \ 0.08564539532 **PROPERTIES .VROA .RAMAN .VIBANA *RESPON .THRESH \ \ \ \ \ 1.0D-06 *ABALNR .THRESH \ \ \ \ \ 1.0D-08 .FREQUE \ \ \ \ \ 1 \ \ \ \ \ 0.08564539532 *VIBANA .HESFIL **END OF DALTON INPUT \; Wavelength of the incident light is set to be 532 nm. To request a VCD calculation at the B3PW91/aug-cc-pVDZ level of theory, save the following input as : \; <\samp> %chk=meox_B3PW91_aug--cc-pVDZ_vcd.chk # B3PW91/aug--cc-pVDZ FREQ=VCD \; IR/VCD for methyloxirane @ B3PW91/aug-cc-pVDZ. \; 0 1 8 \ \ \ 0.828380 \ \ -0.788115 \ \ -0.242337 6 \ \ \ 1.042544 \ \ \ 0.616188 \ \ -0.058552 6 \ \ -0.154398 \ \ -0.037430 \ \ \ 0.484776 6 \ \ -1.509186 \ \ \ 0.099297 \ \ -0.148636 1 \ \ \ 1.873345 \ \ \ 0.875371 \ \ \ 0.603777 1 \ \ \ 0.956724 \ \ \ 1.219018 \ \ -0.967605 1 \ \ -0.153869 \ \ -0.258729 \ \ \ 1.558402 1 \ \ -1.417145 \ \ \ 0.322465 \ \ -1.219305 1 \ \ -2.075814 \ \ \ 0.909146 \ \ \ 0.333843 1 \ \ -2.084044 \ \ -0.830679 \ \ -0.035946 \; Start the calculation (the environment variables for Gaussian should be set up properly) : \; meox_B3PW91_aug-cc-pVDZ_vcd.in \ meox_B3PW91_aug-cc-pVDZ_vcd.out> \; After the calculation has finished, produce a formatted checkpoint file : \; \; The file is now ready to be opened with PyVib2. To request a ROA calculation, use the following input file : \; <\samp> %chk=meox_B3PW91_aug--cc-pVDZ_roa.chk # B3PW91/aug--cc-pVDZ FREQ=ROA CPHF=RDFREQ \; Raman/ROA for methyloxirane @ B3PW91/aug-cc-pVDZ. Wavelength of the incident light is 532 nm. \; 0 1 8 \ \ \ 0.828380 \ \ -0.788115 \ \ -0.242337 6 \ \ \ 1.042544 \ \ \ 0.616188 \ \ -0.058552 6 \ \ -0.154398 \ \ -0.037430 \ \ \ 0.484776 6 \ \ -1.509186 \ \ \ 0.099297 \ \ -0.148636 1 \ \ \ 1.873345 \ \ \ 0.875371 \ \ \ 0.603777 1 \ \ \ 0.956724 \ \ \ 1.219018 \ \ -0.967605 1 \ \ -0.153869 \ \ -0.258729 \ \ \ 1.558402 1 \ \ -1.417145 \ \ \ 0.322465 \ \ -1.219305 1 \ \ -2.075814 \ \ \ 0.909146 \ \ \ 0.333843 1 \ \ -2.084044 \ \ -0.830679 \ \ -0.035946 \; 532nm \; Note, that Gaussian calculates also VCD if the user requests a ROA task ! For details refer to . \; The following diagram summarizes what can be done with PyVib2 : |eps>|*1/2|*1/2||||>|What can be done with PyVib2.> To show the base possibilities of PyVib2, let us analyze the results of the ROA calculation on methyloxirane with Gaussian as described in section . The final file can be downloaded from or produced from the input. This file contains all the required data such as the geometry, hessian, Raman/ROA as well as IR/VCD tensors. In order to follow the instructions given bellow, start the program by executing script in the command prompt. Once the main window of PyVib2 appears, use the menu to open a file. Locate and press the Ok button. Since the hessian is present in this file, it is possible to perform the vibrational analysis for an arbitrary isotopic composition of the molecule. The program enables the user to do it in a dialog (for details see section ), which is popped up after the file has been opened. Press the Ok button to use the default isotopic composition. After that, a thumbnail of the opened molecule should appear in the main window as shown on the following figure : |jpeg>|*5/8|*5/8||||>|Main window of PyVib2 with opened methyloxirane.> Note, that other formats currently supported by PyVib2 (see section ) do *not* contain the hessian and so the user will see opened files immediately after specifying their location (provided that the data were considered to be valid). After a file has been successfully opened, the program examines which data are actually available in that file. The menu, located at the top of each thumbnail, shows the visualization options. The content of the menu for our test example is given on the following figure : |jpeg>|*5/8|*5/8||||>|Molecule menu for methyloxirane.> For further details, refer to section . The user can explore the structure of the molecule and its vibrational motion (if the normal modes are available) by choosing menu item. The following window should appear for our test example : |jpeg>|*5/8|*5/8||||>|Window for exploring structure and vibrational motion of methyloxirane.> \; The visualization options are discussed in detail in section . For theoretical explanation of the representation of vibrational motion refer to sections and . If the submenu of the menu is present, the user can plot the Raman/ROA and/or IR/VCD spectra by choosing correspondent menu item. The Raman/ROA spectra for our test example are shown on the following figure : |jpeg>|*5/8|*5/8||||>|Raman/ROA spectra of methyloxirane.> The visualization options for the spectra are discussed in detail in sections and . For theoretical explanation refer to section . This menu item is present if the Raman/ROA data are available for the molecule. The user is offered to use the visualization techniques for Raman/ROA intensities such as e.g. group coupling matrices (GCMs) and atomic contribution patterns (ACPs). For our test example the following window should appear :