Read Me

OpenThermo v. 0.9.12
User's Manual


Tokarev Konstantin (C) 2008


1. Introduction

1.1. What is OpenThermo?
OpenThermo is a program package intended for calculation of thermodynamic functions from molecular data beyond the "rigid rotor - harmonic oscillator" (RRHO) approximation. Such calculations made in conventional way (“by hands”) require individual approach for every molecule, and their difficulty rapidly increase with taking more factors into consideration.
Modern quantum chemistry packages allow to calculate thermodynamic functions using computed frequencies, usually in RRHO model. However, making changes to partition function is often impossible. Moreover, sometimes it's difficult to understand, what approximations are used in such programs and how to interpret obtained values. Authors of these packages usually consider evaluation of thermodynamic properties as additional feature, staying behind quantum chemistry. There was no program package dedicated to statistical thermodynamics itself available for public, neither open source, nor commercial. Here is the first one.

1.2. Who needs OpenThermo?
Want to obtain thermodynamic properties in more precise way than RRHO, but have no idea how?
Breaking your mind with Pitzer's tables?
Evaluating huge statistical expressions with calculator?
Finding of ugly first and second derivatives of Q drives you crazy?
Still tolerate GAUSSIAN's slowlyness because of its thermodynamical capabilities?
No more!
If you want to know, what statistical thermodynamics really can, use OpenThermo!

1.3. OpenThermo 0.9.12 capabilities
- evaluation of heat capacities CV(T) and Cp(T), entropy S0(T), energy U0(T)-U0(0), enthalpy H0(T)-H0(0), free energy F0(T)-F0(0), free enthalpy G0(T)-G0(0) and zero-point vibrational energy (ZPVE) from molecular geometry, list of vibrational frequencies and description of internal rotations;
- treeatment of internal rotations as free or hindered (in harmonic approximation of potential curve, only height of the barrier is required);
- automatical symmetry analysis for molecule and internal rotors;
- calculation of partition function as discreet sum for rotations of symmetric molecules and internal rotors;
- calculations with anharmonic correction (require anharmonic (experimental or scaled) vibrational frequencies);
- verbose log file makes thermodynamic calculation more transparent to user.

Future enhancements of OpenThermo include:
- convenient and extensible XML input file format;
- possibility for user to change internal threshold values without modification of code and recompilation;
- taking into account influence of internal rotations on inertial moments of molecule and rotors;
- treatment of hindered rotations with more complex potential curves described analytically or numerically;
- more ways to describe anharmonicity (e.g., from VSCF calculation);
- different algorithms for fitting of vibrational frequencies and ZPVE;
- atomic weights for whole Periodic table available by default;
- portable Graphical User Interface (GUI).

1.4. Conditions of use
OpenThermo is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 
OpenThermo is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program (see COPYING); if not, see http://www.gnu.org/licenses.
If you found OpenThermo useful and want to support its development, please make a donation on http://openthermo.sourceforge.net.
Permission is granted to copy, distribute and/or modify this document  under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. Names and brands mentioned in this document may be claimed as the property of others.

1.5. System requirements
Almost nothing. OpenThermo works fast on very old machines, sufficient amount of time is required only for huge molecules. Binaries are available for MS Windows, Linux (deb, rpm and statically linked binary), users of other operatig systems may compile OpenThermo from sources.

1.6. Authors and contributors
OpenThermo was written by Konstantin L. Tokarev. You may contact him via  e‑mail: annulen@users.sourceforge.net
This program includes Brute force symmetry analyzer, written by Sergey Patchkovskii and modified by Konstantin L. Tokarev, and Newmat library written by Robert B. Davies.
I'd like to acknowledge several people for valuable advices and ideas:
Aleksander Kuznetsov
Aleksander V. Abramenkov
Andrey V. Stolyarov
Marat F. Fazylbekov

1.7. Collaboration
If you'd like to take part in OpenThermo development, write to e-mail annulen@users.sourceforge.net (Konstantin Tokarev), or look for posts in 'Help needed' section on SourceForge.


2. Installation 

2.1. Microsoft Windows
To install from binary package (.exe) simply run it and follow instructions. After installation you may manually create link for 'thermo.exe' file in installation directory on your desktop. 
To install OpenThermo from sources (tar.gz or tar.bz2) you need C++ compiler installed in your system. You can use Bloodshed Dev-C++ Integrated Development Environment, freely available on http://sourceforge.net/projects/dev-cpp/ or Open Watcom (project files are provided in source packages). To extract source archives you  can use, for example, WinRar program or freely available 7Zip archiver. Before compilation of main program you should compile Newmat library (instructions and project files are in 'newmat' folder).

2.2. Linux and other Unix-like systems
To compile and install main executable files, go to the directory containing downloaded archives and run following commands:
tar -xzf openthermo-0.9.12.tar.gz
cd openthermo-0.9.12
make
make install
where last command must be executed as root. Program files will be installed to the directory '/usr/local/bin/openthermo', and links 'thermo' and 'thermo_unh' will be placed in '/usr/bin'.

You likely want to check correctness of compiled binary. To do that, execute before installation
make test
than go to tests directory and see 'report' file. If you've compiled OpenThermo with g++, it should contain only file names. If you use Intel icc, it will contain lines of numbers, which may differ to each other no more than 1 in last digit.

If you've downloaded statically linked binary package, you should do the same except third 'make' command. So, you should run
tar -xzf openthermo-0.9.12.tar.gz
cd openthermo-0.9.12
make install
where last command requires root access. Alternatively, you may use OpenThermo locally without installation.
To remove OpenThermo in both cases run as root
make uninstall

To install OpenThermo from deb-package, run following command as root:
dpkg -i openthermo_0.9.12_i386.deb
Binary, documentation and man page will be installed to standard directories ('/usr/bin' , '/usr/share/doc/openthermo' and 'usr/share/man/man1/'). To uninstall run
dpkg -r openthermo

To install OpenThermo from rpm-package, run following command as root:
rpm -i openthermo-0.9.12-i386.rpm
Binary, documentation and man page will be installed to standard directories ('/usr/bin' , '/usr/doc/openthermo' and 'usr/man/man1'). To uninstall run
rpm -e openthermo

You can easily build deb or rpm package for your OS from source package. To do that, run in clean source directory (it's important)
make
make deb 
or
make 
make rpm
Resulting package will appear in the same directory.


3. Using OpenThermo

3.1. Preparing input file

WARNING: following version of OpenThermo will use XML format for input file!
To run OpenThermo, you should firstly write input file. Generally, it consists of three main parts: section [geometry], then [options] and last [freq]. Optionally, it may contain fourth section [comments]. You have 'input_example' file included in OpenThermo package.
Remember, that you can place any number of 'space' symbols (spaces, tabs, linebreaks) between two elements of input file (words or numbers or '=' and ':' symbols), but there should be at least one such symbol where they are placed in example. In other cases you will receive error message and OpenThermo will crash or give incorrect result.

3.1.1. Specifying geometry 
In section [geometry] you should place standard XYZ matrix for target molecule. You can simply copy standard XYZ structure file into this section, but you shoul erase any information between number of atoms and XYZ matrix. So, for benzene you should input something like this:
[geometry]

  12

C          0.0000000000       -1.4093958045        0.0000000000
H          0.0000000000       -2.4974474047        0.0000000000
C          1.2207784389       -0.7047658882        0.0000000000
H          2.1629743897       -1.2491008459        0.0000000000
C          1.2207784389        0.7047654737        0.0000000000
H          2.1629743897        1.2491008459        0.0000000000
C          0.0000000000        1.4093958045        0.0000000000
H          0.0000000000        2.4974474047        0.0000000000
C         -1.2207784389        0.7047658882        0.0000000000
H         -2.1629743897        1.2491008459        0.0000000000
C         -1.2207784389       -0.7047658882        0.0000000000
H         -2.1629743897       -1.2491011138        0.0000000000

[options]
...

3.1.2. Options
In this section you should specify number of internal rotations (if there aren't any you should use 0). For each internal rotation you should specify its type («free» or «harmonic»), then number of atoms in rotating group, then colon (:) (don't forget about space!) and then numbers of atoms rotating group consist of. Then type 'bond :' and numbers of atoms, which connect rotator and other part of molecule. After that, type 'sigma = ' and rotating number of this rotator (it's equal to order of symmetry axis going through atoms specified in 'bond').
If type of rotation is «harmonic» you should then type «barrier = » and height of potential barrier (in Hartree units). See 'input_example' for more details.
After descriptions of rotators (if any) rotating number of whole molecule should follow (in form 'sigma = ...' as described above). Next fields are 'freqstyle' (format of frequencies input; see below) and 'freqscale' (coefficient on which all frequencies will be multiplied; if no ideas it's safely to use '1' :)
If freqstyle is 'unhamonic' you should place 'range = ' and number of unharmonic frequencies before 'freqscale'.

3.1.3. Frequencies
This section starts with [freq] header. OpenThermo understands three formats of frequencies: 'std', 'molpro' and 'unharmonic'. One of this formats should be specified in 'freqstyle = ...' in options section.
Example of style 'std' :
[freq] 
3018 
2918 
1414 
1227
...
Example of style 'molpro':
[freq] 
        1                0.00 
        2                0.00 
        3                0.00 
        4                0.00 
        5                0.00 
        6                0.00 
        #7               17.49 
        #8               27.23 
        #9               40.83 
       10               44.62 
       11               47.04 
       12              145.15 
        1              178.43
        ...                 ...
In first column may be any numbers you wish, they aren't used by OpenThermo. Symbol '#' before number turn following frequency off, it may be useful when replacing low frequencies (which oftenly relate to rotations) with real free or hindered rotations. You mustn't place any spaces between '#' and number!
Example of style 'unharmonic':
[freq] 
7      16.65	14.87 
8      26.33	19.62 
9      41.34	35.86 
10      44.63	41.59 
11      46.58	45.18 
12      144.58	143.01 
1	177.72	176.14 
2	186.4	185.24 
3	210.36	209.54
This style is essentially the same as 'molpro' but there are two columns with frequencies. In first there are 'harmonic' frequencies and in second there are 'unharmonic' ones. Only first N frequencies will be used with unharmonic corrections, if N is a number in field 'range = N' in 'options' section.


3.2. Invocation of OpenThermo

3.2.1. Microsoft Windows
To run OpenThermo, double click it's icon or executable 'thermo.exe' itself. You will be prompted to input file name. Program can display warning messages if something is going wrong, e.g. if value of rotation number sigma you've entered mismatch with molecule's symmetry.  If file is successfully read, user will be asked for pressure and temperature interval. Calculated thermodynamic properties will be written to file with '.out' extension appended to input file name.
If there are any errors detected in input file program window will be closed immediately. You can find more details in file with '.log' extension.
 Also you can run OpenThermo from command line. To make operations simplier you can copy 'thermo.exe' to folder containing input files. In this case you can use instructions given below.

3.2.2. Linux and other Unix-like systems
If you've installed program (with 'make install' command) it will be availible with 'thermo' command. The syntax is
thermo [datafile]
If datafile is not given, user will be prompted to input file name. If file is successfully read, user will be asked for pressure and temperature interval. Calculated thermodynamic properties will be written to file with '.out' extension appended to input file name.
If there are any errors detected in input file error messages or 'Segmentation fault' will be printed to stderr. You can find more details in file with '.log' extension.
If program wasn't installed, you can type in the command line full path to the executable 'thermo' and then path to the file.

3.3. Setting of atomic weights
When started OpenThermo creates three files: files with extensions '.out' and '.log', and file 'elements.dat'. First two files are created in directory containing input file, placement of the third depend on your operating system: on Windows it's created in directory containing 'thermo.exe' file, on Unix-like systems it's created in a current directory. If 'elements.dat' already exists, it isn't being overwritten.
File 'elements.dat' contains atomic symbols, weights and values of nuclear spin. By default, OpenThermo generates file with atomic weights, recommended by IUPAC. If you want to calculate thermodynamic properties for isotopic pure molecules, you should modify 'elements.dat' by two ways: 1) you may add new line, e.g. 'C13  13.0  0.5' or 2) change values for existing elements.
Now default 'elements.dat' contain data for elements of first five rows of Periodic table, so, if you want use heavier elements or isotopes, you should add corresponding lines to this file. Next versions will contain more elements.
When thermo is executed, it also generates file 'tmp' in current directory. If file with such name is present, its content will be lost.


4. Troubleshoot
Q: How to reproduce thermodynamical results given by popular quantum chemistry packages? 
A: For PC GAMESS (maybe GAMESS-US too) 
Uncomment CLASSIC_ROTATION define in thermo.h. Do the same with NO_SPIN define and recompile program ('make' command). Remove from input file all frequencies which belong tointernal rotations but you shouldn't specify any rotors. Start OpenThermo and you'll get almost the same result as PC GAMESS .
For Molpro
Results are something close, but I don't know exactly how Molpro obtains them :)
For GAUSSIAN:
Sorry, we don't use that :)
Note 1: For energies (U,H,F,G) results will differ because PC GAMESS adds ZPVE to this values . 
Note 2: To give more correct result (mostly it affects entropy) you shouldn't follow this instructions and use default settings in thermo.h .
Note 3: Next versions will allow user to change this parameters without recompilation.
Note 3: Some quantum chemistry programs (for example, PC GAMESS) use monoisotpic atomic weights in calculation. But usually thermodynamic properties of substance with natural isotopic composition are of interest. OpenThermo uses IUPAC atomic weights by default (they can be changed in elements.dat file in directory containing input file) to reduce isotopic error. 

Q: I receive strange values of heat capacity: it doesn't grow monotonously and has a minimum (probably with negative value) 
A: OpenThermo use numeric derivation of partition function, and in some rare cases second derivative may be computed improperly. To solve this problem, open mathmodule.hpp and in line 
double Diff2 (double (*F)(double x, double y, double& d, ofstream & of), 
	double x0, double y0, double& d, ofstream & of, double dx=5e-3); 
change value of dx=5e-3 to another value
Note: Next versions will allow user to change this parameters without recompilation.