vibAnalysis

Tools for performing vibrational analysis on molecular systems.

About vibAnalysis

vibAnalysis is a tool for aiding the interpretation of vibrational spectra using the Vibrational Mode Decomposition (VMD) paradigm. This is an alternative approach to the well-established Potential Energy Decomposition (PED) scheme implemented in software packages such as VEDA.

Under VMD, the movement associated with a vibrational mode is decomposed into a set of redundant internal coordinates. For each vibrational mode, the most prominent internal coordinates describing the atomic motions are listed, together with their respective weights. In vibAnalysis, we implemented three different "flavours" of VMD, which differ in the way such weights are determined:

Vibrational Mode Projection (VMP)
Vibrational Mode Linear Decomposition (VMLD), and
Vibrational Mode Automatic Relevance Determination (VMARD)

The latter of which is the default method used by vibAnalysis. VMP and VMLD are simple methods based on vector projection and linear least-squares regression, respectively. In its turn, VMARD uses the Automatic Relevance Determination (ARD) method, which is a variant of Bayesian Ridge Regression to better estimate the most prominent internal coordinates. This results on a much clearer picture of the internal coordinates describing the atomic motions.

Currently, vibAnalysis can perform VMP, VMLD, VMARD, as well as animate vibrational motions and displacements along internal coordinates.

System Requirements

vibAnalysis is written in Python 3, and should work in any modern system. Its only requirements are:

vibAnalysis has the ability to export the animation of vibrational modes and displacements along internal coordinates using the xyz format which can be easily opened using Molden.

How to Use

Assuming you have downloaded the va.py, have permissions to execute it, and it is in your executable PATH. If you run va.py without any argument, it will print its help on the terminal.

Usage: ./va.py [ Commands ] [ Options ] inputFile

Commands:
 --vmp     Perform Vibrational Mode Decomposition analysis.
 --novmp   Don't perform Vibrational Mode Decomposition (default).
 --vmld    Perform Vibrational Mode Linear Decomposition analysis.
 --novmld  Don't perform Vibrational Mode Linear Decomposition (default).
 --vmbld   Perform Vibrational Mode Bayesian Linear Decomposition analysis.
 --novmbld Don't perform Vibrational Mode Bayesian Linear Decomposition (default).
 --vmard   Perform Vibrational Mode ARD Decomposition analysis (default).
 --novmard Don't perform Vibrational Mode ARD Decomposition analysis.

Options:
 --linear         System is linear (3N-5 vibrational modes expected).
 --ts             System is a transition state 
                  (first vibrational mode included as reaction coordinate).
 --mwd            Use mass-weighted vibrational displacements (default).
 --nomwd          Don't use mass-weighted vibrational displacements.
 --mws            Use mass-weighted internal coordinate displacements.
 --nomws          Don't use mass-weighted internal coordinate displacements (default).
 --noouts         Don not generate out-of-plane internal coordinates
 --notors         Don not generate torsion internal coordinates
 --strictplanes   Restrict out-of-plane bending to co-planar atoms (default)
 --nostrictplanes Out-of-plane coordinates generated for all eligible 4 atom sets
 --ooptol f.ff    Tolerance (in degrees) for --strictplanes.
 --autosel        Automatic selection of internal coordinates.
 --addic FILE     Read additional or user-defined internal coordinates from
                  file FILE.
 --cut XX         Set the cutoff for presenting contributions:
                  'auto' - Automatic selection (default)
                  'all'  - All contributions are listed.
                  'd9'   - Always lists the top 90% most important contributions
                  'q1'   - Always lists the top 25% most important contributions
                  X      - List only contributions with relative weight above X%
 --delta f.ff     Use this value for the discete computation of S.
 --tol XX         Tolerance (in %) for determination of atomic connectivity.
 --input XX       Input format, and their expected sufixes:
                  'hess'      - Orca .hess file (default).
                  'g09'       - Gaussian09 output (log) file.
                  'mopac'     - MOPAC 2016 output (out) file.
                  'mopac2016' - MOPAC 2016 output (out) file.
 --vm XX          Animate vibrational mode XX 
 --ic XX          Animate internal coordinate XX 

 Format for additional coordinates (--addic):
 - Plain text file (extension is not relevant, but .ic is recommended)
 - Lines Containing a hash (#) are ignored as comments
 - One internal coordinate per line, as a tuple of characters and numbers:
   - First Entry: B A O, or T, for bond, angle, out-of-plane or torsion, respectively
	 - Following entries: the indexes of the atoms involved, starting with 1.
   - For B, you must define 2 atoms
   - For A, you must define 3 atoms, the second being the apex of the angle
   - For O, you must define 4 atoms, the second being the central atom
   - For T, you must define 4 atoms, the first and last being the extreme of the torsion
  Examples:
    B 1 2   -> Bond between atoms 1 and 2
    A 1 4 3 -> Angle formed betweem 4-1 and 4-3

Basic Usage

vibAnalysis can read from either the output of Gaussian09 or from the hess file generated by Orca (the latter being the default). The defaults are sensible enough for most uses. Thus, it can be invoked only as:

va.py myFreqRun.hess

for analysing the hess file from Orca. The results will be punched onto a file named myFreqRun.nma. If you prefer to use Gaussian for your calculations, you can use

va.py --input g09 myFreqRun.log

as before, the results will be saved on a file named myFreqRun.nma.

Animating Vibrational Modes and Internal Coordinates

You can animate one or more vibrational modes using vibAnalysis, just use the --vm option followed by a list of the modes to animate, for example:

./va.py --vm 11 12 acoh-hess.hess

will make the VMARD analysis and also punch the animation of vibrational modes 11 and 12 onto files named acoh-hess.v011.xyz and acoh-hess.v012.xyz. The numbering of the vibrational modes corresponds to those on the nma file, which may or may not correspond to the ordering read in the files generated by the Quantum chemistry packages.

In a similar manner, the motion along a single internal coordinate can be animated using the --ic option, for example:

./va.py --ic 11 12 acoh-hess.hess

will punch the animation along internal coordinates 11 and 12 onto files acoh-hess.i011.xyz and acoh-hess.i012.xyz, respectively. These files can be used to inspect the displacement along each internal coordinate, or can be used to perform Potential Energy Surface (PES) scans for the parametrisation of molecular force fields.

How to Cite

The VMARD method is described in J. Chem. Theory Comput, 2019, 15(1), 456-470. If you wish to publish your work using vibAnalysis, please please cite the above paper, using the following BibTeX entry:

@Article{Teixeira2018VMARD,
  author    = {Filipe Teixeira and M. Nat{\'{a}}lia D. S. Cordeiro},
  title     = {Improving Vibrational Mode Interpretation Using Bayesian Regression},
  journal   = {J. Chem. Theory Comput.},
  year      = {2019},
  volume    = {15},
  number    = {1},
  pages     = {456--470},
  month     = {dec},
  doi       = {10.1021/acs.jctc.8b00439},
  publisher = {American Chemical Society ({ACS})}
}

In addition to this, you may also want to put a reference to this gitHub repository, as the code evolves and new implementation features are added. The following BibTeX entry should provide you with all the needed information:

@Electronic{TeixeiraVibAnal,
  author    = {Filipe Teixeira},
  title     = {VibAnalysis - Tools for performing vibrational analysis on molecular systems},
  year      = {2017},
  date      = {2017-07-04},
  url       = {https://github.com/teixeirafilipe/vibAnalysis},
  urldate   = {2017-07-04}
}