Read Me

OpenThermo v.1.0 Beta 2
Tokarev Konstantin and others (C) 2007-2009

   Contents:
=================
1. Introduction
2. Conditions of Use
3. System Requrements
4. Installation
5. Execution of OpenThermo
6. Migration from Older Versions
7. Keywords Description
8. Troubleshoot
9. Getting More Help
10. Collaboration


1. Introduction

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 are able 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.

Main OpenThermo 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
[root@localhost openthermo]#

  molecular geometry, list of vibrational frequencies and description of
  internal rotations;
- treatment of rotations as free or hindered in quantum or classic approaches;
- automatical symmetry analysis for molecule and internal rotors;
- automatic Fourier interpolation of discreetly defined potential bariers;
- calculations with anharmonic correction (require anharmonic (experimental or
  scaled) vibrational frequencies);
- verbose log file makes thermodynamic calculation more transparent to user.



2. 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 3 of the License, or (at your 
option) any later version. 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 at 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.



3. System requirements
Almost nothing. OpenThermo works sufficiently fast on very old machines,
larger amount of time is required only for huge molecules, and for calculation
of energy level for quantum rotors if large grid is used. Binaries are
available for M$ Windows, Linux (deb, rpm), users of other operating systems
are encouraged to compile OpenThermo from sources (modern C++ compiler such as
GCC 4.x is preferable).



4. Installation 

4.1. Microsoft Windows
To install from zip-archive simply unpack it to desired folder. After installation 
you may manually create link for 'thermo.exe' file in installation directory on 
your desktop. Alternatively, you may copy 'thermo.exe' to folders, containing your 
input files.

To install OpenThermo from sources (tar.gz or tar.bz2) you need C++ compiler 
installed in your system. For example, you can use MinGW or its flavours such as 
Bloodshed Dev-C++ Integrated Development Environment, freely available on 
http://sourceforge.net/projects/dev-cpp. To compile, create new project and add all 
source files to it.. To extract source archives you can use, for example, WinRar 
program or freely available 7Zip archiver (http://www.7-zip.org). If you are using 
other compiler than MinGW, you must either explicitly link OpenThermo with Cygnus 
library (GNU libm) or comment string

#define LIBM

in file 'thermo.h'.

If your compiler doesn't support "unix" slashes ("/") in paths, uncomment

#define WINDOWS

in file 'thermo.h' or compile with -DWINDOWS option.

4.2. Linux and other Unix-like systems

To compile and install executable file of OpenThermo, go to the directory containing 
downloaded archives and run following commands (replace //version// with exact version 
of package):

tar -xzf openthermo-//version//.tar.gz    # or 'tar -xjf' for .bz2 archive
cd openthermo-//version//
make
make install

where last command must be executed as root. Program files will be installed to the 
directory '/usr/local/bin/openthermo', and simlink 'thermo' will be placed in '/usr/bin'

If you experience difficulties, check if you have working g++ compiler (it should be 
installed by default on most Linux systems). To compile on Ubuntu you must have package 
'buid-essential' package. To install it run

sudo apt-get install build-essential

You can also compile OpenThermo with freeware Intel C++ Compiler for Linux, available on 
http://software.intel.com/en-us/articles/non-commercial-software-download/. For successful 
compilation you must slightly modify Makefile (more details see in Makefile itself).

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's 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 first 
'make' command. So, you should run

tar -xzf openthermo-//version//-bin.tar.gz
cd openthermo-//version//
make install
 

where last command requires root access. Alternatively, you may use OpenThermo locally without 
installation, but this is less convenient.

If you've downloaded statically linked binary package, you should do the same except third 'make' 
command. So, you should run

tar -xzf openthermo-//version//.tar.gz
cd openthermo-//version//
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_//version//_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-//version//-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.



5. Execution of OpenThermo

5.1. Microsoft Windows
To run OpenThermo, double click on its icon or executable 'openthermo.exe' itself. 
Dialog window will rise to ask for input file name. Than user will be asked for 
thermodynamic functions calculation conditions: pressure and temperature interval. 
(In case they were not specified in input file. Such option is also available and 
will be described further.) Calculated thermodynamic properties will be written to 
the output file with the same name as an input one, but with the '*.out' extension. 
All intermediate results and a lot of information about molecule will be available 
in the '*.log' file.

If there are any errors detected in input file error messages will be printed in the 
program's window. The details about errors will be available in a '*.log' file. 
Besides, the program can display warnings on some non-critical errors. 

Also OpenThermo can be executed from the command line (cmd.exe). To simplify the 
operation executable file 'openthermo.exe' can be copied to the folder containing 
input file(s). OpenThermo can be started with or without parameters as described 
below.


5.2. Linux and other Unix-like systems

If the OpenThermo is installed globally (from binary package or via make install 
command), or the route to binary is contained in PATH variable, openthermo command 
can be used in every directory where user have write permissions. The syntax is:

openthermo [input_file_name]

Otherwise, the program can be called using the full path to the openthermo binary.
If input_file_name is not specified, user will be invited to input file name. If 
input file was successfully read, user is asked for thermodynamic functions 
calculation conditions: pressure and temperature interval. (In case they were not 
specified in input file. This option is also available and will be described later) 
Calculated thermodynamic properties are written to the output file with the same 
name as an input one, but with the '*.out' extension. All intermediate results of 
calculations and a lot of information about molecule become available in the '*.log' 
file which is being updated during execution.

If there are any errors detected in input file error messages or 'Segmentation fault' 
will be printed to stderr. The details about errors will be available in a '*.log' file. 
Besides, the program is able to display warnings on are some non-critical errors. 


5.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 *nix-like
systems it's created in a $HOME 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 come with more elements.

When thermo is executed, it also generates file 'tmp' in current directory (or
/tmp/openthermo for *nix-like systems). If file with the same name is present,
it'll be overwritten.



6. Migration from Older Versions

New format of input file, used in OpenThermo 1.0, differs significantly
from format of previous versions. Follow "Getting Started" manual published
on http://openthermo.sourceforge.net, and "Kewords Description" section
of this document for more information.

To convert your old files to the new format, replace group header [geometry]
with <geometry> in the beginning and </geometry> at the end of geometry
specification. Similarly replace [freq] with <freq> and </freq>. There is
no counterpart for [options] group. The next table shows how that options
are to be set for use with OpenThermo 1.0.

freqscale = _scale_		<freq scale=_scale_>
freqstyle = _style_		<freq style=_style_>
freqstyle = anharmonic	<freq type=anharm>
range = N				      ---
sigma = s				<geometry sym=symgroup>

						<rotors>
rotors = N				 <rotor ...
rotors' descriptions	 ...
						</rotors>

Note that now spaces between '=' symbol and paramer's name and value doesn't
matter. Also note that there are a lot of new configurable parameters in
OpenThermo 1.0 which weren't available in the previous versions.



7. Keywords Descrption




8. 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.

 

9. Getting More Help

This document is not intended to be a tutorial. If you don't belong to.
that category of users who hate manuals and learns on their own experience,
download 'Getting Started' tutorial from official site of OpenThermo
(http://openthermo.sourceforge.net)

If you still have questions, or if you'd like to report a bug or request
a feature, feel free to do it in the site or send them to e-mail
annulen@users.sourceforge.net



10. 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.