MHM Program for deMon2k Trajectory Files

This appendix describes the compilation and input syntax of the "ttbin" implementation of the multiple histogram method (MHM) version 2.5. This program is intended to analyze the trajectory files created by the deMon2k software and will not work with trajectory files created by other programs. The program can be obtained directly from its author, Dr. José Manuel Vásquez Pérez (email: josemanuel_vasquez@uaeh.edu.mx).

Compilation

Change to the directory where the README.pdf file is located and locate the ttmake.sh script. Ensure that the gfortran compiler is installed and that the script is executable. To compile just type:

 ./ttmake.sh

The script will compile the source files producing the object files and the binary ttbin inside the newly created object directory. By default the script uses the gfortran compiler but you can switch to any FORTRAN compiler which supports the FORTRAN 90 standard by changing it.

Input File

The input file should indicate at least the number of atoms in the molecule or cluster and the file names of the trajectories to analyze. The "#" character may be used at the beginning of a line to comment it. The list of possible keywords in the input is given below:

ATOMS $<$Integer$>$
Number of atoms in the system. This keyword is mandatory, if omitted an error is indicated.

BINS $<$Integer$>$
This keyword sets the number of bins into which the energy interval is divided for the histogram construction. If the keyword is omitted the default is 1000.

TNODES $<$Integer$>$
This keyword sets the number of nodes into which the temperature interval is divided for the calculation of thermodynamic functions. If the keyword is omitted the default is 100.

TOLERANCE $<$Real$>$
This keyword sets the convergence tolerance for the MHM self consistent procedure. If the keyword is omitted the default is $10^{-9}$. The default value should be fine for most cases. You can tighten it if you suspect that convergence is not reached.

EGROUND $<$Real$>$
This keyword sets a reference energy such that all trajectory energies will be offset relative to it. This value should be set equal to the ground state energy of the system to be physically meaningful. If the ground state energy is unknown the special value LOWEST may be used, which sets this reference equal to the lowest energy found along the trajectory. The selection of this value will shift the absolute values of internal and free energies calculated by the program. If the keyword is omitted the default is LOWEST.

QUANTUM $<$Logical$>$
This keyword enables quantum corrections for the partition function. If enabled, the FREQS block must also be defined, otherwise an error is indicated. If the keyword is omitted its default value is FALSE.

CUMULATIVE $<$Logical$>$
This keyword enables an alternative integration method based on cumulative histograms for the MHM procedure. If the keyword is omitted its default value is FALSE.

READ $<$String$>$
This keyword specifies the intended energy to read from the trajectory. If omitted the default is the total energy. The possible values for this keyword are:

TOTAL Read the total energy (default)

POTENTIAL Read only the potential energy

KINETIC Read only the kinetic energy

FILES
This keyword opens a block to define the filenames of the trajectory files to analyze. After each filename you may indicate the first and last steps of each trajectory to be read. If you do not indicate the last step to read it is set to the last step in the trajectory. If you do not indicate neither the first nor the last step, they are set to the first and last step in the trajectory. The block must be closed with the END keyword. For example:

 FILES
 <filename> [<integer>] [<integer>]
 <filename> [<integer>] [<integer>]
 <filename> [<integer>] [<integer>]
 END

FREQS
This keyword opens a block to define the list of normal mode frequencies (in cm$^{-1}$), as calculated in a normal mode analysis of the system, to recover the correct quantum zero temperature limit of the partition function and its derivatives. The block must be closed with the END keyword. For example:

 FREQS
 <frequency>
 <frequency>
 <frequency>
 END

The following is a simple input example as found in the example directory of the MHM distribution:

 ATOMS 2
 EGROUND -108.662165418
 QUANTUM TRUE
 #BINS 1000
 #TNODES 100
 #READ TOTAL
 #CUMULATIVE FALSE
 #TOLERANCE 1.0E-9

 FILES
 N2_0500.trj    5001
 N2_1500.trj    5001
 N2_2500.trj    5001
 END

 FREQS
 2361.8
 END

Besides this input file the specified trajectory files along with the expected output files are also in the example directory of the MHM distribution.

Execution

Ensure that the ttbin binary is executable and run it in the same directory where the trajectory and input files are located by typing

 ./ttbin

The program will print the following messages during its execution:

 Reading trajectory file...

Printed as trajectory files are read.

 Solving self consistent equations...

Printed when the self consistent MHM procedure starts.

 Calculating thermodynamic functions...

Printed when the partition function derivatives calculation starts.

Additionally, several warnings and errors may be printed.

A script named ttplot.sh is also included in the MHM distribution. It will plot the free energy, entropy, internal energy and heat capacity curves. Make sure that it is executable and run it in the same directory where the output files are located by typing:

./ttplot.sh [<real> <real>]

It will create a gnuplot script named makeplots.gnu and, if gnuplot is installed, will create the postscript files f.ps, u.ps, cv.ps and s.ps that contain plots of the free energy, internal energy, heat capacity and entropy, respectively. By default the whole temperature range of the trajectories is plotted, but the script accepts two optional arguments to set the lower and upper temperatures of the plots.

Output Files

A successful execution of the program creates the following output files:

output
This file contains the settings and parameters used for the construction of the histograms by the multiple histogram method.

trj-data
This file contains statistics for each trajectory file. Internal energies and heat capacities are directly calculated from statistical fluctuations of the energy.

can-data
This file contains canonical properties as a function of temperature. It lists the free energy, $F$, entropy, $S$, internal energy, $U$ and heat capacity, $c_v$ as a function of temperature.

his-data
This file contains the energy histograms.