A user-friendly program for calculating isotope effects.

PyQuiver is an open-source Python program for calculating kinetic isotope effects (KIEs) and equilibrium isotope effects (EIEs) using harmonic frequencies and the Bigeleisen-Mayer equation. PyQuiver requires Cartesian Hessian matrices, which can be calculated using any electronic structure program.

• automatically read frequencies from Gaussian (g09/g16) and ORCA output files
• excellent performance for larger systems, with optional multi-threading
• custom isotopic substitutions and arbitrary temperature
• tunnelling corrections: Wigner, Bell infinite parabola, and Skodje-Truhlar
• command line or a clean Python API with structured (pandas-ready) results

PyQuiver requires Python 3.9+ and numpy. pandas is optional (only for to_dataframe()).

Install from PyPI:

pip install pyquiver-kie            # core (numpy only)
pip install "pyquiver-kie[pandas]"  # adds DataFrame output

The distribution is named pyquiver-kie on PyPI, but you still import it as pyquiver.

Or install from a checkout:

git clone https://github.com/ekwan/PyQuiver.git
cd PyQuiver
pip install -e .

PyQuiver has been tested on PC, Mac, and Linux platforms.

The pyquiver command still works but is deprecated in favour of the Python API below:

pyquiver demo.config gs.out ts.out            # gaussian by default; prints a deprecation notice

Add -v/-vv for logging, -s for the style (gaussian/g16/g09, orca, pyquiver), -j for threads.

Build the configuration in Python with Config.from_dict (or load a .config file with Config(path)), then run it on a ground- and transition-state file:

from pyquiver import Config, KIE_Calculation

config = Config.from_dict(
    isotopologues={"C1": [(1, 1, "13C")], "H/D": [(7, 7, "2D"), (8, 8, "2D")]},
    temperature=393, scaling=0.9614, imag_threshold=50,
)
calc = KIE_Calculation(config, "gs.out", "ts.out", style="gaussian")

print(calc)                       # human-readable table
calc.to_dict()                    # {name: {uncorrected, wigner, infinite_parabola}}
calc.to_csv("kies.csv")           # CSV text / file
calc.to_dataframe()               # pandas DataFrame (needs the pandas extra)
calc.results["C1"].wigner         # named access to each result

System objects hold a parsed geometry and Hessian, so you can read each file once and reuse it, which is handy for a parameter scan:

from pyquiver import System

gs = System("gs.out", style="gaussian")   # parse once
ts = System("ts.out", style="gaussian")
for T in (298, 350, 393):
    cfg = Config.from_dict(isotopologues={"C1": [(1, 1, "13C")]},
                           temperature=T, scaling=0.9614, imag_threshold=50)
    print(T, KIE_Calculation(cfg, gs, ts).results["C1"].uncorrected)

KIE_Calculation(..., n_jobs=N) parallelizes the per-isotopologue work across N threads (the heavy eigvalsh step releases the GIL). The default is serial; it pays off for large systems and many isotopologues.

The uncorrected, Wigner, and Bell corrections are reported automatically. For the Skodje-Truhlar correction, supply the reactant/product/TS single-point energies (it needs the barrier height):

# energies in hartree by default (or unit="J")
calc.skodje_truhlar(reactant_energy=E_sm, product_energy=E_pr, ts_energy=E_ts)
# -> {isotopologue: corrected_KIE}

To run one configuration over many structures, use batch with a {label: (gs, ts)} dictionary and get back one table:

from pyquiver import batch

results = batch("demo.config", {
    "b3lyp": ("b3lyp_gs.out", "b3lyp_ts.out"),
    "m06":   ("m06_gs.out",   "m06_ts.out"),
})
results.to_dataframe()        # label, name, uncorrected, wigner, infinite_parabola
results["b3lyp"]              # the KIE_Calculation for that pair

You normally build that dictionary from the files on disk, e.g. {f.removesuffix("_gs.out"): (f, f.replace("_gs", "_ts")) for f in glob.glob("*_gs.out")}. Pass energies={label: (reactant, ts, product)} to add a Skodje-Truhlar column.

PyQuiver logs through the standard logging module (logger name pyquiver) and raises exceptions on bad input; it never prints on import or calls sys.exit, so it is safe to use inside scripts and notebooks.

To learn how to use PyQuiver, please look at the tutorial.

• Technical Details (compatibility with QUIVER, how to invoke PyQuiver, .config files, input files, the PyQuiver Standard format, miscellaneous notes)
• Batch processing (how to run PyQuiver on many related files)
• Snipping Utility (how to "snip" out only the relevant parts of a Gaussian output file for publication or archiving purposes)

PyQuiver was written by Thayer Anderson and Eugene Kwan. Please email ekwan16@gmail.com with any questions. We will gladly try to help you.

We thank Gregor Giesen for writing the code to read ORCA output. We thank Gino Occhialini for the Skodje-Truhlar tunnelling correction. We thank Corin Wagen for miscellaneous optimization. We also thank Christoph Riplinger and Giovanni Bistoni for valuable discussions.

Anderson, T.L.; Kwan, E.E. PyQuiver, www.github.com/ekwan/PyQuiver (pip install pyquiver-kie)

This project is licensed under the Apache License, Version 2.0. See LICENSE.txt for full terms and conditions.

Copyright 2020 by Thayer L. Anderson and Eugene E. Kwan