Skip to content

Latest commit

 

History

History
148 lines (102 loc) · 10 KB

DETAILS.md

File metadata and controls

148 lines (102 loc) · 10 KB
Raw

Technical Details

Compatibility with QUIVER

The development of PyQuiver was inspired by the original Fortran program QUIVER. PyQuiver is designed to be as compatible as possible with the original QUIVER program, but to clarify some ambiguity in choice of masses, configuration files need to be updated for use with PyQuiver. See the Configuration section for detail.

How to Invoke PyQuiver

PyQuiver can be controlled from the command line or its Python API.

To run PyQuiver from the command line, issue the following command from the src/ directory:

python quiver.py config_file ground_state_file transition_state_file

For more details, run python quiver.py -h to display the following help message:

usage: quiver.py [-h] [-v] [-s STYLE] config gs ts

PyQuiver calculates KIEs and EIEs based on a ground and transition state file.

positional arguments:
  config                configuration file path
  gs                    ground state file path
  ts                    transition state file path

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         when the verbose flag is set debug information is
                        printed
  -s STYLE, --style STYLE
                        style of input files (g09, orca, or pyquiver)

This command will calculate the KIEs or EIEs associated with the isotopic substitutions specified in the configuration file. For details, see the tutorial above.

PyQuiver also has a Python API. The advantage of this interface is that it exposes the underlying Python objects. This allows you to run custom calculations, automate routine calculations, and inspect the internal data directly.

An IPython Notebook is provided as a demonstration. To try it out, move to the scripts/ directory and run the command ipython notebook. Then open the pyquiver.ipynb notebook file. An IPython Notebook skodgetruhlar.ipynb is also provided to calculate KIEs corrected with the Skodge Truhlar tunnelling equation. (see ref. 4)

.config Files

Calculations performed in PyQuiver require a configuration file to specify the parameters (such as scaling factor and temperature) and isotopologue substitution rules.

Each configuration file is a plain text file with the following properties:

  • blank lines and lines starting with # are ignored
  • anything after # within a line is assumed to be a comment
  • fields in directives are separated by spaces.

Valid configuration files have all of the following directives:

  • scaling: a linear factor by which to scale the frequencies
  • imag_threshold: the threshold (in units cm^-1) that defines the cutoff between small and large imaginary frequencies used to distinguish EIE from KIE calculations (typical value: 50)
  • temperature: the temperature in Kelvin
  • reference_isoto[pomer/logue]: possible values are none or the name of an isotopologue. If none is specified, the absolute KIEs will be reported. If the name of an isotopologue is specified, all KIEs will be divided the KIE values for this isotopologue.
  • mass_override_isot[pomer/logue]: possible values are "default" or the name of an isotopologue. If the value "default" is specified, the masses of the light isotopologue will be the defaults found in weights.dat. If the name of an isotopolgoue is given, then that isotopologue is then used to replace the default mass behaviour of PyQuiver at a particular atom. For example, if the isotopomer C2 replaces carbon 2 with 13C, then specifying mass_overide_isotopomer C2 will place carbon-13 at C2 for every KIE calculation.
  • isoto[pomer/logue]: the rule used for isotopic substitution. The expected fields are name ground_state_atom_number transition_state_atom_number substitution. The final field, substitution must correspond to a valid substitution weight. These weights are specified in weights.dat (e.g., 13C, 18O, 2D).

Input Files

PyQuiver assumes that the ground state file and transition state file are the outputs of a Gaussian09 freq job. To change this assumption PyQuiver can accept an additional command-line argument corresponding to the input file style.

Currently, PyQuiver can automatically read output files from the following formats:

  • Gaussian 2009. Style name: g09 (This also works with Gaussian 2016.)
  • ORCA. Style name: orca (Reads the .hess files generated by any frequency job.)
  • PyQuiver Standard. Style name: pyquiver

To specify a format other than g09 from the command line, run with the -s flag. For instance:

python quiver.py -s pyquiver ../tutorial/pyquiver/claisen_demo.config ../tutorial/pyquiver/claisen_gs.qin ../pyquiver/claisen_ts.qin

would execute the example PyQuiver job on the Claisen system using the PyQuiver standard input files. This allows you to adapt PyQuiver to other electronic structure programs. (We would be pleased to offer some advice on how to accomplish this.)

PyQuiver Standard

The PyQuiver Standard is a generic format for the output of an electronic structure program in plain-text outlined as follows:

  • The first line of a file contains the number of atoms (n).
  • The next n lines define the geometry. Each line should be of the form:
CenterNumber,AtomicNumber,XPosition,YPosition,ZPosition

The positions should be provided in units of Angstroms. The center number is the atom index (ranging from 0 and n-1, inclusive).

  • The next line should contain the lower triangular Cartesian Hessian matrix with no line breaks. In particular, if H is the Hessian matrix then H3p+i,3q+j corresponds to taking derivatives with respect to atom p moving in the i-th coordinate and atom q moving in the j-th coordinate (i and j run across the three cartesian coordinates). The entries in the serialized form should be separated by commas. The serialization should occur by stringing together the rows (truncated at the main diagonal). For example, suppose the following is the lower-right triangular form of the Cartesian Hessian for a one atom system:
1.0
2.0 3.0
4.0 5.0 6.0

then the PyQuiver would expect the following line:

1.0,2.0,3.0,4.0,5.0,6.0
  • Example PyQuiver standard input files are available in the tutorial/pyquiver/ directory. The files claisen_gs.qin and claisen_ts.qin are PyQuiver input files corresponding to the example Claisen system discussed in the tutorial.

If input files are provided in a known format other than the PyQuiver standard, PyQuiver can dump the appropriate PyQuiver input files. To do this load the appropriate system (ex. gs = System("./ground_state.g09")) and then run gs.dump_pyquiver_input_file() which will create the appropriate input file at the same path with the extension .qin.

Miscellaneous Notes

The internal workings of PyQuiver are relatively simple. Essentially, a KIE calculation involves parsing the Hessian, mass-weighting, diagonalization with np.eigvalsh, calculation of the reduced isotopic partition functions, substitution into the Bigeleisen-Mayer equation, and tunnelling corrections. The tunnelling corrections are expected to work well for heavy atoms, but poorly for hydrogen, especially when considering primary KIEs.

The frequencies can optionally be scaled (see ref. 3), but this will probably not help much (the harmonic approximation is usually quite adequate). Note that PyQuiver is recognizees linear vs. non-linear molecules and removes the appropriate number of small translational/rotational modes. (The frequency_threshold keyword has been deprecated and is now ignored.)

The performance of PyQuiver is generally excellent, even for large systems. This is largely because of the efficiency of the np.eighvalsh implementation. Note that when multiple isotopomers are calculated using the same configuration file, PyQuiver will recalculate the frequencies for the reference isotopomer repeatedly (i.e., once for every isotopomer). This should not be relevant for routine use. However, it could be avoided by using the PyQuiver API.

There is a known issue with getting PyQuiver to work on Cygwin systems due to a problem processing file paths correctly. Additionally it seems to be hard to get NumPy installed properly on such systems. We are working on a fix--please contact me if you require this urgently. (The program works properly on all other kinds unix/linux, as far as we know).

Please note that the verbose flag should be set in the Gaussian route card. For example: #p b3lyp 6-31g* freq=noraman This will ensure that Gaussian places the Hessian in the archive string at the end of the file. (Not including the verbose flag will cause an error.)

Tunnelling corrections work best for heavy-atom KIEs. H/D KIEs are more challenging (see the work of the Singleton and Truhlar groups for more details).

References

  1. Bigeleisen-Mayer theory:
  • Bigeleisen, J.; Mayer, M.G. J. Chem. Phys. 1947, 15, 261.
  • Wolfsberg, M. Acc. Chem. Res., 1972, 5, 225.
  • Wolfsberg, M. et al. Isotope Effects in the Chemical, Geological, and Bio Sciences
  1. QUIVER:
  • Saunders, M.; Laidig, K.E. Wolfsberg, M. J. Am. Chem. Soc., 1988, 111, 8989.
  1. Scaling Factors:
  • Wong et al. Chem. Phys. Lett. 1996, 256, 391-399.
  • Radom et al. J Phys. Chem. 1996, 100, 16502.
  1. Tunnelling Corrections:
  • Bell, R.P. Chem. Soc. Rev. 1974, 3, 513.
  • Skodge, R.T.; Truhlar, D.G. J. Phys. Chem. 1981, 85, 624-628
  1. Claisen Rearragenent KIEs:
  • Meyer, M.P.; DelMonte, A.J.; Singleton, D.A. J. Am. Chem. Soc., 1999, 121, 10865-10874.