goodvibes 4.0

A python program to compute corrections to thermochemical data from frequency calculations

GoodVibes computes quasi-harmonic thermochemical corrections from electronic structure calculations (Gaussian, ORCA, NWChem, QChem, xTB, ASE). It corrects the poor description of low-frequency vibrations by the rigid-rotor harmonic oscillator (RRHO) treatment using the approaches of Grimme and Truhlar.

Features

• Grimme quasi-RRHO (mRRHO) and Truhlar quasi-harmonic entropy corrections
• Head-Gordon quasi-harmonic enthalpy correction
• Variable temperature and concentration thermochemistry
• Automated vibrational frequency scaling factor lookup (~200 levels of theory)
• Single-point energy corrections (link jobs or separate files)
• Boltzmann-weighted populations and N-way stereoselectivity (--label)
• Potential energy surface analysis with YAML-defined pathways, stoichiometric sums (2*A + B), and Gconf corrections
• Structured JSON output (--json) for downstream pipelines
• Symmetry-corrected entropy via pymsym point-group detection
• Solvent standard-state concentration and free-space corrections
• JSON caching for fast re-analysis (--cache-save / --cache-read)
• Duplicate structure detection (--dedup) and energy-sorted output (--sort)
• Supports Gaussian, ORCA, NWChem, QChem, xTB, and ASE output files

Installation

Requires Python >= 3.9.

pip install goodvibes

Or with uv:

uv pip install goodvibes

Or from conda-forge:

conda install -c conda-forge goodvibes

For development (editable install):

pip install -e .

Quick Start

goodvibes <output_file(s)> -q

The -q flag applies quasi-harmonic corrections (Grimme entropy + Head-Gordon enthalpy). Use -h for the full list of options.

Supported Programs

GoodVibes reads output files from:

• Gaussian (09, 16) .log / .out -- optimization, frequency, single-point, link jobs, ONIOM, VPT2 anharmonic
• ORCA (5, 6) .out -- optimization, frequency, single-point, DLPNO-CCSD(T)
• NWChem .out -- optimization, frequency, single-point
• QChem (6) .out / .qcin -- optimization, frequency, single-point, linked jobs
• xTB .out -- frequency calculations (ORCA/xTB integration compatible)
• ASE (Atomic Simulation Environment) .extxyz -- extended XYZ format with energy & frequency data

The program is auto-detected from the output file contents. Additional file extensions can be registered with --custom_ext.

Documentation

Full documentation is available on Read the Docs.

Examples

Example 1: Grimme-type quasi-harmonic correction with a cut-off of 150 cm^-1

goodvibes examples/methylaniline.out -f 150

   Structure                    E        ZPE             H        T.S     T.qh-S          G(T)       qh-G(T)
   *********************************************************************************************************
o  methylaniline      -326.664901   0.142118   -326.514489   0.039668   0.039465   -326.554157   -326.553954
   *********************************************************************************************************

The output shows both standard harmonic and quasi-harmonic corrected thermochemical data (in Hartree). The corrected enthalpy and entropy values are always less than or equal to the harmonic value.

Example 2: Quasi-harmonic thermochemistry with a larger basis set single point energy correction link job

goodvibes examples/ethane_spc.out --spc link

   Structure                E_SPC             E        ZPE         H_SPC        T.S     T.qh-S      G(T)_SPC   qh-G(T)_SPC
   ***********************************************************************************************************************
o  ethane_spc          -79.858399    -79.830421   0.073508    -79.779414   0.027540   0.027542    -79.806954    -79.806956
   ***********************************************************************************************************************

This calculation contains a multi-step job: an optimization and frequency calculation with a small basis set followed by (--Link1--) a larger basis set single point energy. Note the use of the --spc link option. The standard harmonic and quasi-harmonic corrected thermochemical data are obtained from the small basis set partition function combined with the larger basis set single point electronic energy. In this example, GoodVibes automatically recognizes the level of theory used in the frequency calculation, B3LYP/6-31G(d), and applies the Truhlar group scaling factors of 0.991 (harmonic, used for H_vib and S_vib) and 0.977 (ZPE). Use -v 1.0 to suppress all scaling, or --zpe-vscal Y to override only the ZPE factor.

Alternatively, if a single point energy calculation has been performed separately, provided both file names share a common root e.g. ethane.out and ethane_TZ.out then use of the --spc TZ option is appropriate. This will give identical results as above.

goodvibes examples/ethane.out --spc TZ

   Structure                E_SPC             E        ZPE         H_SPC        T.S     T.qh-S      G(T)_SPC   qh-G(T)_SPC
   ***********************************************************************************************************************
o  ethane              -79.858399    -79.830421   0.073508    -79.779414   0.027540   0.027542    -79.806954    -79.806956
   ***********************************************************************************************************************

Example 3: Changing the temperature (from standard 298.15 K to 1000 K) and concentration (from standard state in gas phase, 1 atm, to standard state in solution, 1 mol/l)

goodvibes examples/methylaniline.out --temp 1000 --conc 1.0

   Structure                    E        ZPE             H        T.S     T.qh-S          G(T)       qh-G(T)
   *********************************************************************************************************
o  methylaniline      -326.664901   0.142118   -326.452307   0.218212   0.216559   -326.670519   -326.668866
   *********************************************************************************************************

This correction from 1 atm to 1 mol/l is responsible for the addition 1.89 kcal/mol to the Gibbs energy of each species (at 298K). It affects the translational entropy, which is the only component of the molecular partition function to show concentration dependence. In the example above the correction is larger due to the increase in temperature.

Example 4: Analyzing the Gibbs energy across an interval of temperatures 300-1000 K with a stepsize of 100 K, applying a (Truhlar type) cut-off of 100 cm^-1

goodvibes examples/methylaniline.out --ti '300,1000,100' --qs truhlar -f 120

   Structure               Temp/K                        H        T.S     T.qh-S          G(T)       qh-G(T)
   ******************************************************************************************************
o  methylaniline            300.0              -326.514399   0.040005   0.039842   -326.554404   -326.554241
o  methylaniline            400.0              -326.508735   0.059816   0.059596   -326.568551   -326.568331
o  methylaniline            500.0              -326.501670   0.082625   0.082349   -326.584296   -326.584020
o  methylaniline            600.0              -326.493429   0.108148   0.107816   -326.601577   -326.601245
o  methylaniline            700.0              -326.484222   0.136095   0.135707   -326.620317   -326.619930
o  methylaniline            800.0              -326.474218   0.166216   0.165772   -326.640434   -326.639990
o  methylaniline            900.0              -326.463545   0.198300   0.197800   -326.661845   -326.661346
o  methylaniline           1000.0              -326.452307   0.232169   0.231614   -326.684476   -326.683921
   ******************************************************************************************************

Note that the energy and ZPE are not printed in this instance since they are temperature-independent. The Truhlar-type quasi-harmonic correction sets all frequencies below 120 cm^-1 to a value of 100. Constant pressure is assumed, so that the concentration is recomputed at each temperature.

Example 5: Analyzing the Gibbs Energy using scaled vibrational frequencies

goodvibes examples/methylaniline.out -v 0.95

   Structure                    E        ZPE             H        T.S     T.qh-S          G(T)       qh-G(T)
   *********************************************************************************************************
o  methylaniline      -326.664901   0.135012   -326.521265   0.040238   0.040091   -326.561503   -326.561356
   *********************************************************************************************************

The frequencies are scaled by a factor of 0.95 before they are used in the computation of the vibrational energies (including ZPE) and entropies.

Example 6: Writing Cartesian coordinates

goodvibes examples/HCN*.out --xyz

Optimized cartesian-coordinates found in files HCN_singlet.out and HCN_triplet.out are written to GoodVibes_output.xyz

Example 7: Analyzing multiple files at once

goodvibes examples/*.out --cpu

   Structure                    E        ZPE             H        T.S     T.qh-S          G(T)       qh-G(T)
   *********************************************************************************************************
o  Al_298K            -242.328708   0.000000   -242.326347   0.017670   0.017670   -242.344018   -242.344018
o  Al_400K            -242.328708   0.000000   -242.326347   0.017670   0.017670   -242.344018   -242.344018
o  H2O                 -76.368128   0.020772    -76.343577   0.021458   0.021458    -76.365035    -76.365035
o  HCN_singlet         -93.358851   0.015978    -93.339373   0.022896   0.022896    -93.362269    -93.362269
o  HCN_triplet         -93.153787   0.012567    -93.137780   0.024070   0.024070    -93.161850    -93.161850
o  allene             -116.569605   0.053913   -116.510916   0.027618   0.027621   -116.538534   -116.538537
o  benzene            -232.227201   0.101377   -232.120521   0.032742   0.032745   -232.153263   -232.153265
o  ethane              -79.830421   0.075238    -79.750770   0.027523   0.027525    -79.778293    -79.778295
o  isobutane          -158.458811   0.132380   -158.319804   0.034241   0.034252   -158.354046   -158.354056
o  methylaniline      -326.664901   0.142118   -326.514489   0.039668   0.039535   -326.554157   -326.554024
o  neopentane         -197.772980   0.160311   -197.604824   0.036952   0.036966   -197.641776   -197.641791
   *********************************************************************************************************
TOTAL CPU      0 days  2 hrs 29 mins 28 secs

Wildcard characters (*) can be used to specify all output files in a directory.

Example 8: Entropic Symmetry Correction

goodvibes examples/allene.out examples/benzene.out examples/ethane.out examples/isobutane.out examples/neopentane.out --symm

   Structure                    E        ZPE             H        T.S     T.qh-S          G(T)       qh-G(T)  Point Group
   **********************************************************************************************************************
o  allene             -116.569605   0.053913   -116.510916   0.026309   0.026312   -116.537225   -116.537228          D2d
o  benzene            -232.227201   0.101377   -232.120521   0.030396   0.030399   -232.150917   -232.150919          D6h
o  ethane              -79.830421   0.075238    -79.750770   0.025831   0.025833    -79.776601    -79.776603          D3d
o  isobutane          -158.458811   0.132380   -158.319804   0.033204   0.033214   -158.353008   -158.353019          C3v
o  neopentane         -197.772980   0.160311   -197.604824   0.034606   0.034620   -197.639430   -197.639444           Td
   *********************************************************************************************************************************************

Example 9: Potential Energy Surface (PES) Comparison with Accessible Conformer Correction

goodvibes examples/gconf_ee_boltz/*.log --pes examples/gconf_ee_boltz/gconf_aminox_cat.yaml

   Structure                       E        ZPE             H        T.S     T.qh-S          G(T)       qh-G(T)
   ************************************************************************************************************
o  Aminoxylation_TS1_R   -879.405138   0.295352   -879.091374   0.063746   0.061481   -879.155120   -879.152855
o  Aminoxylation_TS2_S   -879.404445   0.295301   -879.090562   0.064366   0.061891   -879.154928   -879.152453
o  aminox_cat_conf212_S  -517.875165   0.200338   -517.662195   0.051817   0.049814   -517.714012   -517.712009
o  aminox_cat_conf280_R  -517.877308   0.200869   -517.664171   0.049996   0.048777   -517.714167   -517.712948
o  aminox_cat_conf65_S   -517.877161   0.200789   -517.664159   0.049790   0.048656   -517.713949   -517.712815
o  aminox_subs_conf713   -361.535757   0.095336   -361.433167   0.037824   0.037696   -361.470991   -361.470863
   ************************************************************************************************************

   Gconf correction requested to be applied to below relative values using quasi-harmonic Boltzmann factors

   RXN: Reaction (kcal/mol)       DE       DZPE            DH       T.DS    T.qh-DS         DG(T)      qh-DG(T)
   ************************************************************************************************************
o  Cat+Subs                     0.00       0.00          0.00       0.00       0.00          0.00          0.00
o  TS                           4.72      -0.46          3.53     -15.85     -16.37         19.39         19.90
   ************************************************************************************************************

Example 10: Stereoselectivity and Boltzmann populations

goodvibes examples/gconf_ee_boltz/Aminoxylation_TS1_R.log examples/gconf_ee_boltz/Aminoxylation_TS2_S.log --boltz --ee "*_R*:*_S*"

   Structure                       E        ZPE             H        T.S     T.qh-S          G(T)       qh-G(T)  Boltz
   *******************************************************************************************************************
o  Aminoxylation_TS1_R   -879.405138   0.295352   -879.091374   0.063746   0.061481   -879.155120   -879.152855  0.605
o  Aminoxylation_TS2_S   -879.404445   0.295301   -879.090562   0.064366   0.061891   -879.154928   -879.152453  0.395
   *******************************************************************************************************************

   Selectivity            Excess (%)     Ratio (%)         Ratio     Major Iso           ddG
   *****************************************************************************************
o                              20.98         60:40         1.5:1             R          0.25
   *****************************************************************************************

CLI Reference

Run goodvibes -h for the full list of options. Key flags:

Flag	Description	Default
-q	Apply quasi-harmonic corrections (Grimme entropy + Head-Gordon enthalpy)	off
-f FREQ	Frequency cut-off for entropy and enthalpy (cm-1)	100
--fs FREQ	Frequency cut-off for entropy only (cm-1)	100
--fh FREQ	Frequency cut-off for enthalpy only (cm-1)	100
--qs {grimme,truhlar}	Quasi-harmonic entropy method	grimme
--qh	Apply Head-Gordon enthalpy correction only	off
--temp TEMP	Temperature in Kelvin	298.15
--ti START,END,STEP	Temperature interval scan	--
--conc CONC	Concentration in mol/L (solution-phase entropy)	gas phase
-v SCALE	Vibrational frequency scaling factor	auto
--spc SUFFIX	Single-point energy correction (suffix or link)	--
--symm	Apply symmetry correction to entropy (pymsym)	off
--boltz	Print Boltzmann-weighted populations	off
--label NAME=PATTERN	N-way selectivity bucket (repeatable, fnmatch on basenames)	--
--selectivity FILE.yaml	Selectivity spec via YAML (alternative to --label)	--
--ee PATTERNS	(deprecated) Two-species selectivity, e.g. "*_R*:*_S*" — use --label	--
--pes FILE	YAML-defined reaction pathway analysis (legacy + true YAML auto-detected)	--
--lowest-only	PES tables: use only each species' lowest qh-G conformer	off
--json PATH	Write structured results (schema v0.4: thermo, selectivity, pes blocks)	--
--media SOLVENT	Solvent standard-state concentration correction	--
--freespace SOLVENT	Free-space correction for solvent cavity	--
--invert [THRESH]	Invert small imaginary frequencies to positive values	off
--bav {global,conf}	Moment of inertia for free-rotor entropy	global
--sort [energy|gibbs]	Sort output by energy	--
--dedup	Remove duplicate structures	off
--dp N	Decimal places for energy output	6
--cache-save FILE	Save parsed data to JSON cache	--
--cache-read FILE	Read parsed data from JSON cache	--
--custom_ext EXTS	Additional file extensions (comma-separated)	--
--exclude PATTERN	Glob pattern to exclude files	--
--check	Verify consistency across input files	off
--cpu	Print total CPU time	off
--xyz	Write Cartesian coordinates to .xyz file	off
--imag	Print imaginary frequencies	off
--output NAME	Output file base name	output
--vmm SCALE	Frequency scaling factor for ONIOM MM region	--
--nogconf	Disable Gconf correction in PES analysis	off
--graph FILE	Graph a reaction profile from free energies	--

Dependencies

• Python >= 3.9
• numpy -- numerical computations
• pymsym -- point group detection and symmetry numbers
• rich >= 13 -- console table rendering

Optional:

• ase >= 3.22 (goodvibes[ase]) -- only needed to parse .extxyz inputs
• pyyaml -- needed at runtime when reading new-style PES YAML or --selectivity FILE.yaml; included in the test extra

Build requires setuptools >= 64. See pyproject.toml for details.

Contributing

Install for development:

pip install -e .

Run the test suite:

pytest -v

Test data is organized by program:

• tests/g16/ -- Gaussian 16 output files
• tests/orca6/ -- ORCA 6 output files (full coverage)
• tests/orca5/ -- ORCA 5 output files (lightweight regression layer)
• tests/qchem6/ -- QChem 6 output files
• tests/xtb/ -- xTB output files
• tests/ase/ -- ASE (extended XYZ) test files

Test helpers in tests/conftest.py provide path resolvers (g16path(), orca_path(), orca5_path(), qchem_path(), xtb_path(), ase_path()) and categorized file lists (G16_FREQ_FILES, ORCA_FREQ_FILES, QCHEM_FREQ_FILES, XTB_FREQ_FILES, ASE_FREQ_FILES, etc.) used by parametrized tests.

Citing GoodVibes

Luchini, G.; Alegre-Requena, J. V.; Funes-Ardoiz, I.; Paton, R. S. GoodVibes: Automated Thermochemistry for Heterogeneous Computational Chemistry Data. F1000Research, 2020, 9, 291 DOI: 10.12688/f1000research.22758.1

References

1. Ribeiro, R. F.; Marenich, A. V.; Cramer, C. J.; Truhlar, D. G. J. Phys. Chem. B 2011, 115, 14556-14562 DOI: 10.1021/jp205508z
2. Grimme, S. Chem. Eur. J. 2012, 18, 9955-9964 DOI: 10.1002/chem.201200497
3. Li, Y.; Gomes, J.; Sharada, S. M.; Bell, A. T.; Head-Gordon, M. J. Phys. Chem. C 2015, 119, 1840-1850 DOI: 10.1021/jp509921r
4. Alecu, I. M.; Zheng, J.; Zhao, Y.; Truhlar, D. G.; J. Chem. Theory Comput. 2010, 6, 2872-2887 DOI: 10.1021/ct100326h
5. Mammen, M.; Shakhnovich, E. I.; Deutch, J. M.; Whitesides, G. M. J. Org. Chem. 1998, 63, 3821-3830 DOI: 10.1021/jo970944f
6. Pracht, P.; Grimme, S. Chem. Sci. 2021, 12, 6551-6568 DOI: 10.1039/D1SC00621E

---

License

GoodVibes is freely available under an MIT License