===============================================================

ValleyRide.py Manual

Version 1.0

Copyright (c) 2019 Sanha Lee, Jonathan M. Goodman
University of Cambridge

This documents is adapted from 'Rapid Route-Finding for Bifurcating
Organic Reactions' Supporting Information

===============================================================

CONTENTS
1) Requirements and Setup
2) Usage
3) Example Usage

===============================================================

1) REQUIREMENTS AND SETUP

The script is currently set up to run on Python version 2.7. The following Python modules must be installed before the script can be run:
- numpy
- argparse
- os
- math
- sys
- rdkit
- bisect
- pprint

The python script is designed to analyse Gaussian output files from Gaussian 16 only.

The script will only recognise the Gaussian output file if the frequency calculation is run independently. Do not run the calculation with 'opt' and 'freq'  keywords at the same time. The following freqency keyword must be included in the calculation 'freq=(hpmodes,intmodes)'.  

The python script requires the Gaussian output files to be in .mol file format.
It is possible to convert the frequency output files to .mol file using Gaussview.


2) CORRECT USAGE

The .mol files and .out files must be inputed in the following order.

python ValleyRidge.py TS1molfile.mol TS2molfile.mol P1molfile.mol P2molfile.mol TS1freq.out TS2freq.out

TS1molfile.mol - geometry of the first transition state in .mol file format
TS2molfile.mol - geometry of the second transition state in .mol file format 
P1molfile.mol - geometry of the first product in .mol file format
P2molfile.mol - geometry of the second product in .mol file format
TS1freq.out - Gaussian16 frequency calculation output file for the first transition state
TS2freq.out - Gaussian16 frequency calculation output file for the second transition state

The key output will be in the following format:
- files corresponding to the major and minor product are stated
- the two μ and λ values which decides the alignment type are given 
- the length of vector |g| and the angle φ (angle between the reaction vector and vector g_ is stated


The algorithm will create a log file and print out
- whether the rdkit object was successfully created
- vectors p1_, p2_ and the imaginary eigenvector
- φ: angle between the imaginary eigenvector, a_, and vector g_ (displacement of TS2 from TS1)
- dot products, angles and magnitude of the key vectors
- uncommon bonds the algorithm has used for the selectivity prediction
- returns a warning sign for large |g_| and when the predicted selectivity is low


3) EXAMPLE USAGE

The following files are provided for this section
- testP1freq.mol
- testP2freq.mol
- testTS1freq.mol
- testTS1freq.out
- testTS2freq.mol
- testTS2freq.out

Test the code on the example Gaussian output files given: 
python ValleyRidge_Final.py testTS1freq.mol testTS2freq.mol testP1freq.mol testP2freq.mol testTS1freq.out testTS2freq.out

The Gaussian output files were generated by optimising the bifurcating reaction published by Houk et al in 2007 (N. Celebi-Olcum, D. H. Ess, V. Aviyente and K. N. Houk, J. Am. Chem. Soc., 2007, 129, 4528-4529). The correct execution should print out the following output.

**** Analysis Completed ****
Major product is testP2freq.mol
Minor product is testP1freq.mol

mu1_ = -0.289922296441
mu2_ = 0.252770629844
lambda1_ = 1.08759940557
lambda2_ = 0.973437730557
|g_| = 0.476703235778
phi = 61.702486369

Product Ratio Calculation Completed:
Major Product : Minor Product ratio
80.3 : 19.7

****************************

The algorithm should also create a log file called 'ValleyRidge_testTS1freq.log' with all the key information