mlcp

Multilayer CP-tensor format eigensolver for vibrational energy levels of molecules

https://github.com/phi-l-l-ip-thomas/mlcp

Repository

Multilayer CP-tensor format eigensolver for vibrational energy levels of molecules

README

########################################################################
#
### Instructions for setting up and running MLCP, version 'ML2e'  ###
#
########################################################################

1) MLCP comes with libraries included (in the 'lib') directory and is
   configured to be compiled using the gfortran compiler. To compile
   the libraries and the main code, one can use the convenience script

   $ bash install

   to compile and link everything. Alternatively, once can compile the
   libraries individually and modify the Makefile to compile MLCP using
   a different compiler (currently gfortran is supported for the CPU code
   and nvcc for the CUDA portion)

2) To run MLCP, two input files are read, as well as a number of 
   potential files, depending on the PES used:

   a) The file 'layers.inp' is used to enter the structure of the 
      multilayer tree:

      -In the $resort section, one chooses the order of the modes, where
       the numbering corresponds to that in the potential files
      -In the $basis section, one chooses the numbers of basis functions:
       first line: number of 1D harmonic oscillator functions
       subsequent lines: number of n-D eigenfunctions to keep in the 2nd,
       3rd, ... layers, which must not exceed the size of the direct product 
       basis of the previous layer
      -In the $layers section, the grouping of the coordinates is provided,
       beginning with the second layer

   b) The file "CP.inp" lists control parameters for the calculation:

      -System: five-character name 'XXXXX' of the PES to use. Potential
               files for the system must match the name given here.
               For more details on how To add a new PES, see section 3 below.
               -Systems 'dummy', 'Henon' (modified Henon-Heiles), and 'CpOsc'
                are available for testing and require no potential files.

      -NCPU: number of processors to use

      -red2D: type of rank-reduction to use for modes containing two 
              submodes. Acceptable choices are:
              SVD-singular value decomposition (recommended)
              ALS-alternating least squares
              SR1-successive rank-1 updates
              OPS-orthogonal rank-1 projections plus sorting

      -redND: type of rank-reduction to use for modes containing more
              than two submodes. Acceptable choices are:
              ALS-alternating least squares (recommended)
              SR1-successive rank-1 updates 
              OPS-orthogonal rank-1 projections plus sorting

      -psirank: target rank for the wavefunction

      -psinals: number of ALS iterations used in wavefunction rank reduction

      -solver: solver type to use. Acceptable values are:
               powr-power method
               cheb-Chebyshev-filtered power method
               pals-intertwined power method ("intertwining")
                    (for modes with D=2, setting red2D='SVD' implies
                    'powr' for those modes)

      -ncycle: number of cycles. One cycle implies npow power iterations
               + Gram Schmidt orthogonalization + vector updates

      -npow: number of power/Chebyshev/intertwining/PIST iterations per
             cycle

      -lowmem: memory-saving option to use with intertwining (solver=pals).
               Options range from 0 (fastest, most memory usage)
                               to 3 (slowest, least memory usage)

      -update: set to 1 to use vector updates (recommended). Setting to 0
               sorts vectors by Rayleigh Quotient instead of by eigenvalue

      -optimize PES: rotate PES to minimize terms which couple multiple DOFs
                     (recommended setting=F)

      -solvtol: solver tolerence; calculation exit earlier when
                (E_previous-iteration - E_this-iteration)/E_this-iteration < solvtol
                for ALL eigenvalues

      -resfile: name for files to write restart data to/read restart data from. Choose
                'none' to avoid generating restart files; otherwise the following
                files are generated:
                XXXXX_1_eigv.rst, XXXXX_2_eigv.rst (two copies of eigenvalues)
                XXXXX_1_oper.rst, XXXXX_2_oper.rst (two copies of operators)
                XXXXX_1_psi.rst, XXXXX_2_psi.rst   (two copies of wavefunction blocks)
                XXXXX_CP.rst                       (copy of CP.inp used in run)
                XXXXX_layers.rst                   (copy of layers.inp used in run)
                (two copies of eigv, oper and psi are generated in case of system
                failure during a write, which would result in a corrupt file)

   c) Once everything is set up, run the code using the command

      $ mlcp.x > output.out &

      Enjoy!

3) Adding a new PES

   Including a new PES requires following four steps:

   a) pick a five character name for the new PES, e.g. 'XXXXX'

   b) add the following files to the pes directory:
      f2XXXXX.dat (quadratic constants)
      f3XXXXX.dat (cubic constants)
        ...
      fnXXXXX.dat (n-th order constants)

   c) Modify the subroutine GetPotential() in source file Source/FFPES.f90
      by adding an 'ELSEIF' statement for the new PES. This includes a 
      call to  ReadFFHamiltonian(V,'XXXXX',n,divide), where n is the highest
      order for which terms are included. Setting the 'divide' parameter 
      to .TRUE. causes potential terms to be divided by Taylor series factors
      and then multiplied by degeneracy factors

   d) recompile MLCP

########################################################################
#  Instructions by Phillip Thomas 14 September 2023
########################################################################

Citation (CITATION.md)

# CITATION

## If you publish a manuscript using results obtained from running MLCP, please cite the following:

- “Using Nested Contractions and a Hierarchical Tensor Format to Compute Vibrational Spectra of Molecules with Seven Atoms,”
P. S. Thomas and T. Carrington. J. Phys. Chem. A, 2015, 119(52), 13074-13091.
[DOI:10.1021/acs.jpca.5b10015](https://doi.org/10.1021/acs.jpca.5b10015)

## Here are some other references relevant to the code and methodology:

- “Computing vibrational energy levels using a canonical polyadic tensor method with a fixed rank and a contraction tree,”
S. D. Kallullathil and T. Carrington, Jr., J. Chem. Phys., 2023, 158, 214102.
[DOI:10.1063/5.0149832](https://doi.org/10.1063/5.0149832)

- “Computing vibrational energy levels by solving linear equations using a tensor method with an imposed rank,”
S. D. Kallullathil and Tucker Carrington, Jr. J. Chem. Phys., 2021, 155, 234105.
[DOI:10.1063/5.0075412](https://doi.org/10.1063/5.0075412)

- “Using an Iterative Eigensolver and Intertwined Rank Reduction to Compute Vibrational Spectra of Molecules with More Than a Dozen Atoms: Uracil and Naphthalene,”
P. S. Thomas, T. Carrington, J. Agarwal, and H. F. Schaefer. J. Chem. Phys., 2018, 149, 064108.
[DOI:10.1063/1.5039147](https://doi.org/10.1063/1.5039147)

- “An Intertwined Method for Making Low-Rank, Sum-of-Product Basis Functions That Makes It Possible to Compute Vibrational Spectra of Molecules with More Than 10 Atoms,”
P. S. Thomas and T. Carrington. J. Chem. Phys., 2017, 146, 204110.
[DOI:10.1063/1.4983695](https://doi.org/10.1063/1.4983695)

- "Comparison of different eigensolvers for calculating vibrational spectra using low-rank, sum-of-product basis functions,"
A. LeClerc, P. S. Thomas, and T. Carrington, Jr., Molec. Phys., 2017, 115, 1740-1749.
[DOI:10.1080/00268976.2016.1249980](https://doi.org/10.1080/00268976.2016.1249980)

- “Calculating vibrational spectra with sum of product basis functions without storing full-dimensional vectors or matrices,”
A. LeClerc and T. Carrington, Jr., J. Chem. Phys., 2014, 140, 174111.
[DOI:10.1063/1.4871981](https://doi.org/10.1063/1.4871981)

GitHub Events