2. Usage¶

This section introduces how to use Shermo. If you do not have basic knowledge about calculation of molecular thermochemistry data, it is strongly suggested to check Appendix of this manual to gain related knowledge first.

2.1 Files in Shermo package¶

Shermo.exe: Executable file of Shermo in Windows
Shermo: Executable file of Shermo in Linux
settings.ini: The file containing running parameters of Shermo
Shermo_manual.pdf: Manual
"example" folder: Containing some output files of various quantum chemistry programs, most of them are involved in the examples in Section 3 of this manual.

2.2 Running Shermo¶

Shermo can run in both interactive mode and command-line mode.

Interactive mode In Windows, just double-clicking the Shermo.exe icon to boot up it. In Linux, inputting path of Shermo executable file to boot up it. After that, you should input the path of input file, then all thermodynamic quantities will be immediately outputted on screen.
Command-line mode In command-line environment, you can run Shermo like this
```
/sob/Shermo_2.0/Shermo /mol1/freq.out -T 250 -P 1.5
```
where /sob/Shermo_2.0/Shermois path of Shermo executable file,/mol1/freq.out is input file, the arguments request that the calculation is conducted at 250 K and 1.5 atm, see next section for detail.

All running parameters and various information about the present system are shown on screen prior to calculation, you should always carefully examine this information to ensure that the calculated data is what you need.

2.3 Running parameters¶

After booting up, Shermo will first load running parameters from settings.iniin current folder. If it does not exist, Shermo will then try to find this file in the directory defined by "Shermopath" environment. If it still cannot be found, default running parameters will be used. In command-line mode, the parameters in settings.ini or the default parameters can be overridden by the arguments in the running command.

The parameters in the settings.ini are described below

E: Electronic energy in a.u. If it is 0 (default value), then the electronic energy loaded from input file will be finally used in calculation of thermochemistry data
prtvib: Output contribution of each vibrational mode to various thermodynamic data.
- 1: Printing on screen
- -1: Printing to vibcontri.txt in current folder
- 0 (default): Do not print
T: Temperature (K) used in the calculation. Default value is 298.15. If you want to scan temperature to check variation of various thermodynamic data with respect to temperature, you should specify lower limit, upper limit and stepsize, for example, 50,200,10
P: Pressure (atm) used in the calculation. Default value is 1. If you want to scan pressure, you should specify lower limit, upper limit and stepsize, for example, 0.5,15,0.1
sclZPE: Frequency scale factor for calculating zero-point energy (ZPE). Default is 1.0
sclheat: Frequency scale factor for calculating heating contribution to internal energy (U), that is $U(T)-U(0)$ (the same as the scale factor for H(T) H(0)). Default is 1.0
sclS: Frequency scale factor for calculating entropy (S). Default is 1.0
sclCV: Frequency scale factor for calculating heat capacity (C_V or C_P). Default is 1.0
ilowfreq: Consideration of vibrational contribution of low frequencies to thermodynamic data, see Section 4.A for details
- 0: Harmonic approximation
- 1: Raising all lower frequencies to a specific value. All quantities related to vibrational frequencies are affected
- 2 (default): Grimme's entropy interpolation between harmonic and free-rotor models. This treatment only affects entropy. See Chem. Eur. J., 18, 9955 (2012)
- 3: The same as 2, but the interpolation is applied to both entropy and internal energy. In J. Comput. Chem., 44, 1807 (2023), Otlyotov and Minenkov showed that this scheme is better than 2 and thus more recommended to use
NOTE: When ilowfreq is set to 2 or 3, the partition functions printed in the output information are the same as those of ilowfreq=0, because no corresponding partition function is available for Grimme’s and Minenkov’s QRRHO models.
ravib: Raising lower frequencies to this value (cm⁻¹) when ilowfreq=1. Default is 100
intpvib: Vibrational frequency threshold (cm⁻¹) used in interpolation when ilowfreq=2 and 3. Default is 100, which is a good choice for all cases, but for specific systems, decreasing it to lower value such as 50 may result in better data
imagreal: Treat imaginary frequencies with norm smaller than this value (in cm⁻¹) as real frequencies. Only meaningful if used in combination with ilowfreq not equal to 0. Usually 50-100 is suitable. See Section A.4 on when this option may be useful.
imode: Mode of evaluating thermodynamic quantities. 0 (default): Consider all terms, namely translation, rotation, vibration, and electron transition contributions. 1: Ignore translation and rotation, thus suitable for solid systems
conc: When this is not the default 0, Shermo will calculate and print variation of Gibbs free energy ($G_{\rm conc}=RT\ln(c_B/c_A)$) due to concentration change from current state (c_A) to specific state (c_B), and finally add the G_conc to the reported Gibbs free energy. Note that this setting does not work if scanning temperature and/or pressure is requested. c_A is calculated as P/RT according to ideal gas formula, where pressure P and temperature T are those specified by corresponding parameters in settings.ini. c_B is specified by “conc”, the unit could be M (namely mol/L) or atm; for the latter case c_B will be evaluated according to ideal gas formula according to the pressure and present temperature. Example: conc= 1.5M and conc= 2.3atm.
outshm: Exporting .shm file after successfully loading output file of quantum chemistry program.
- 0 (default): Do not export
- 1: Exporting .shm file, with same name and directory as the input file
PGlabel: Point group. If set to ? (default case), then point group will be identified by Shermo according to current geometry. Examples of directly specifying point groups: Cs, Ci, C1, C3, D5, C3v, C2h, C3h, D2h, D3d, S4, T, F, Td, O, Oh, I, Ih, Civ, Dih.
defmass: When output file of quantum chemistry program is used as input file, this parameter determines how to assign default atomic masses.
- 1: Mass of element (e.g. Cl is 35.45 amu). This is in line with convention of ORCA and xtb
- 2: Mass of most abundant isotope (e.g. Cl corresponds to ³⁵Cl with mass of 34.96885 amu). This is in line with convention of Gaussian, GAMESS-US and NWChem
- 3 (default): Directly read masses from output file of quantum chemistry program
modmass: Modification on default atomic masses can be specified below this label. For example, at the end of settings.ini, if the content is
```
modmass
10 2.01410
14 13.0033548
```
Then mass of atoms 10 and 14 will be modified to 2.01410 and 13.0033548 amu, respectively.

If .shm file is used as input file, the atomic masses are always directly loaded from the .shm file, and thus "defmass" and "modmass" do not affect result.

It is important to note that atomic mass affects thermodynamic data because in principle it influences molecular mass, moments of inertia and vibrational frequencies. If you use "defmass" and "modmass" to modify mass definition or manually modify .shm file, only the former two will be accordingly changed, while vibrational frequencies are not affected since they are loaded from input file. Therefore, the only rigorous way to consider influence of atomic mass is properly defining isotopes in the input file of your quantum chemistry program.

In command line mode, the above parameters (except for “modmass”) can be directly specified by arguments, and the parameters specified in this way have higher priority. For example, you can run Shermo like this:

Shermo /Aqours/Yoshiko.out -sclZPE 0.98 -T 233 -ilowfreq 2 -prtvib -1

There is another argument “-noset”, if it is added, such as

Shermo C:\love\nico.out -sclZPE 0.9806 -conc 2M -noset

Then Shermo will not load any setting from settings.ini but only receive settings from argument, and default settings will be employed for parameters that not explicitly specified.

2.4 Input files¶

Output file of quantum chemistry program¶

Output files of four well-known quantum chemistry programs are supported by Shermo as input file. If optimization is also involved, the geometry of the final step will be loaded. Example output files of various program can be found in “example” folder of Shermo package.

Gaussian: Output file of "freq" or "opt freq" task. Gaussian 09 and 16 are formally supported.
ORCA: Output file of "freq" or "opt freq" task.
GAMESS-US: Output file of "RUNTYP=hessian", or "RUNTYP=optimize" with "$STATPT hssend=.T. $END"
NWChem: Output file "TASK xxx freq", or "TASK xxx optimize" with "TASK xxx freq", where xxx is type of theoretical method.
xtb: The g98.out file outputted by vibrational analysis task (--hess or --ohess) of xtb program is supported. However, because this file does not contain electronic energy, if you did not provide the energy by explicitly setting “E” in settings.ini, then during running Shermo, Shermo will ask you to input the path of output file of xtb (for example, the test.out generated by running xtb test.xyz -ohess > test.out), Shermo will try to load “total energy” printed last time in this file (while if you do not input the path but press ENTER button directly, electronic energy will be regarded as zero).
CP2K: Output file of "RUN_TYPE VIBRATIONAL_ANALYSIS" task with "PRINT_LEVEL MEDIUM". IMPORTANT NOTICE: If the calculated system is a crystal or adsorbate, you should set “imode” in settings.ini to 1 to remove translation and rotation contributions, since they should not occur in this situation; in addition, in this case point group will be automatically set to C1, since determining point group is meaningless when rotation contribution is not taken into account. Shermo loads all necessary information that needed by calculating thermochemistry quantities from the output file, including electronic energy, spin multiplicity, elements, and coordinates of all atoms, as well as harmonic frequencies (therefore, anharmonic frequencies will be ignored even if they are calculated).

The actually used electronic energy (E) can be directly specified by "E" parameter, however if it keeps default value (0), then the E loaded from output file will be used. For Gaussian and ORCA, the loaded E always corresponds to current calculation level, while for GAMESS-US and NWChem, DFT energy will be loaded if the calculation was conducted at DFT level (except for double-hybrid functionals).

For GAMESS-US and NWChem, if the theoretical method you employed is not DFT of normal functionals, the situation is more complicated, because in this case it is difficult to determine the energy of current level from the output file. Briefly speaking, when post-HF or double-hybrid functionals is employed, energy of reference state is loaded by Shermo. Of course this is not what you want, therefore you should simply ignore the sum of E and various thermal corrections printed by Shermo; alternatively, you can let Shermo output .shm file, then manually fill the actual post-HF energy into this file, and then use this file as input file. The situation of double-hybrid functional is similar to post-HF.

.shm file¶

There is a private format (.shm) defined by Shermo. This file contains everything that needed by Shermo calculation, thus it can also be employed as input file. The shm format is very concise and clear, thus you can easily edit it. An example of shm file is shown below, the blue texts are comments


*E  Electronic energy (a.u.)
        -91.6752090000
*wavenum  Wavenumbers (cm-1). Negative value means imaginary frequency
  952.5433
  952.5433
 2541.2397
 3915.9410
*atoms  Information of all atoms: Name, mass (amu), X, Y, Z (Angstrom)
H     1.007830    0.000000    0.000000     -1.569030
C    12.000000    0.000000    0.000000     -0.498995
N    14.003070    0.000000    0.000000    0.654010
*elevel  Relative energy w.r.t. ground state (eV) and level degeneracy
    0.000000   1

All data in the shm file are in free format. All frequencies, at least the real frequencies, must be presented. Information about all atoms must be given.

The *elevel field is particularly worth noting. The energy levels recorded in this field are with respect to ground state. Spin multiplicity should be equivalently represented by this field. For example, if a system is triplet, content of this field should be

0.0 3

or

0.0
0.0
0.0

Note that the default degeneracy is 1. Another example, a singlet molecule has a low-lying doubly degenerated excited states with excitation energy of 0.15 eV, then the *elevel field should be

0.0
0.15 2

or

0.0
0.15
0.15

The shm file can be directly generated by Shermo after loading output file of quantum chemistry program, namely setting "outshm" parameter in settings.ini to 1.

List file (.txt)¶

Shermo is able to calculate various thermodynamic quantities for a batch of conformations (or configurations); at the same time, Boltzmann weights of the conformers as well as conformation weighted data can be outputted. To realize this, you should prepare a file with .txt suffix, which contains paths of output files of quantum chemistry programs or .shm files. For example:

C:\mol\conf1.out
C:\mol\conf2.out
C:\mol\conf3.out

You can also directly specify the electronic energies (in a.u.) for each system used in the actual calculation of thermodynamic quantities. For example:

C:\mol\conf1.out;233.3333
C:\mol\conf2.out;233.4333
C:\mol\conf3.out;233.3733

In this case the electronic energies loaded from the three .out files will not be used.

See example 3.5 for illustration of the batch calculation. In this running mode, contribution of individual vibrational modes cannot be printed via the "prtvib" parameter, and scan of temperature and pressure is not supported.