PyVCI Files

#=================================================================================#
#                                                                                 #
#              PyVCI - Python Vibrational Configuration Interaction               #
#                 Written by Marat Sibaev and Deborah Crittenden                  #
#             University of Canterbury, Department of Chemistry, 2015             #
#                                                                                 #
#=================================================================================#

#=================================================================================#
#                             Contents Summary                                    #
#=================================================================================#
This package contains:
-> code: python and cython source code, with subdirectories;
   -> force_field: force field parser code and force field data file/s
   -> change_endianness: cython code to alter format of binary data files
-> docs: LaTeX source and compiled manual, with pdf copies of tutorial input files
-> tutes: examples of how to use PyVCI, each in a separate subdirectory;
   -> tute_1a: interfacing with an ab initio program package to
              - perform normal mode analysis from supplied second derivative data
   -> tute_1b: interfacing with an ab initio program package to
              - generate a quartic force field via numerical differentiation
              - restart numerical differentiation and save a force field module
   -> tute_2: interfacing with text files containing:
              - normal mode derivatives (from PyPES library)
              - Cartesian derivatives and normal coordinate vectors (from PyPES)
   -> tute_3: performing a VCI calculation with normal mode derivatives from file
   -> tute_4: loading derivatives from a force field module, and then
              - performing a serial VCI calculation
              - performing a parallel VCI calculation
   -> tute_5: changing the endianness of a binary VCI matrix data file
Reference output data for each tutorial are included in reference subdirectories
for each tutorial.

#=================================================================================#
#                           Installation Instructions                             #
#=================================================================================#
Change into the code directory:
   cd code
Remove any old compiled module files (*.so), if existing:
   ./make_clean
Compile new module files from C source (requires Cython + C compiler):
   python setup_cyth.py build_ext --inplace
Add this directory to your path - example for Mac OSX given. Note that you
will need to be in superuser mode for this command to work. Or you can edit 
the appropriate system setup file for your machine manually.
   sudo su
   echo `pwd` >> /etc/paths
   exit
Restart your terminal/X-windows session

#=================================================================================#
#                Additional Optional Installation Instructions                    #
#=================================================================================#
If you will be transferring binary data files between different machines,
you may need to change the byte order in each word of memory (endianness).
If so, you will need to compile additional code to achieve this:
   cd code/change_endianness
   ./make_clean
   python setup_cyth.py build_ext --inplace
   sudo su
   echo `pwd` >> /etc/paths
   exit
Restart terminal/X-windows 

#=================================================================================#
#                               Usage Instructions                                #
#=================================================================================#
Change into a separate directory containing your/an example input file.
Invoke PyVCI using the following syntax:
   pyvci.py input_file output_file

#=================================================================================#
#                                  Running Tests                                  #
#=================================================================================#
Mandatory tests, commands to be issued in order starting from this directory:
   cd tutes/tute_1a
   pyvci.py example_1a.in example_1a.out
   cd ../tute_2
   pyvci.py example_2.in example_2.out
   cd ../tute_3
   pyvci.py example_3.in example_3.out
   cd ../tute_4
   pyvci.py example_4.in example_4.out
Optional test (if appropriately configured GAMESS install available - see manual):
   cd tutes/tute_1b
   pyvci.py example_1b.in example_1b.out
Optional test (if machines with different architectures used to produce binary intermediate files):
   cd tutes/tute_5
   change_endianness.py vci_matrix_N2H2_3_big.dat vci_matrix_N2H2_3.dat     <---- if your machine is little endian 
   change_endianness.py vci_matrix_N2H2_3_little.dat vci_matrix_N2H2_3.dat  <---- if your machine is big endian 
   pyvci.py example_5.in example_5.out  

#=================================================================================#
#                                   Licensing                                     #
#=================================================================================#
All code contained herein released under the MIT license, 
see MIT_license.txt in docs subdirectory for terms and conditions