# Libra

[![Build Status](https://travis-ci.org/Quantum-Dynamics-Hub/libra-code.svg?branch=master)](https://travis-ci.org/Quantum-Dynamics-Hub/libra-code)


This is the main page of the computational chemistry methodology discovery library, Libra
The program website is [here](https://quantum-dynamics-hub.github.io/libra/index.html)

## Info

More:

* [Training & Usage](https://github.com/compchem-cybertraining/Tutorials_Libra)
* [Autogenerated Documentation](https://quantum-dynamics-hub.github.io/libra-code/)


Due to the increased volume of technical questions about installing and using the 
Libra, Libra-X, Pyxaid and Pyxaid2 codes, I have decided to create a convenient 
[public forum](https://groups.google.com/forum/#!forum/quantum-dynamics-hub)
for all users with the intent:

 - to share my replies with not only a single user that have a trouble, but also other
   potential users who may found that information useful;

 - so that the users/developers who have had some experience with the code would be able to share their
   knowledge and skills with others;


## Installation Videotutorials (as of 5/16/2022)

* [Installing WSL2](https://ub.hosted.panopto.com/Panopto/Pages/Embed.aspx?id=02184b70-7745-4eb4-a776-ae92014c652a&autoplay=false&offerviewer=true&showtitle=true&showbrand=true&captions=false&interactivity=all)

* [Installing WSL2: After reboot](https://ub.hosted.panopto.com/Panopto/Pages/Embed.aspx?id=972aef79-e235-4a90-9ce1-ae92014d34db&autoplay=false&offerviewer=true&showtitle=true&showbrand=true&captions=false&interactivity=all)

* [Installing Ubuntu on Windows 11](https://ub.hosted.panopto.com/Panopto/Pages/Embed.aspx?id=31a63536-f333-4242-9b56-ae92015ece64&autoplay=false&offerviewer=true&showtitle=true&showbrand=true&captions=false&interactivity=all)

* [Creating Conda environment for Libra](https://ub.hosted.panopto.com/Panopto/Pages/Embed.aspx?id=d6ada23e-7e16-4b7a-b290-ae920188627c&autoplay=false&offerviewer=true&showtitle=true&showbrand=true&captions=false&interactivity=all)

* [Installing Libra](https://ub.hosted.panopto.com/Panopto/Pages/Embed.aspx?id=7f8dd8c4-9f58-4ca0-a8cb-ae930166b7ec&autoplay=false&offerviewer=true&showtitle=true&showbrand=true&captions=false&interactivity=all)



## Installation (as of after 3/23/2023)

### 1. Install miniconda (for Python 3.9) and activate Conda

#### 1.1 Download and install

    mkdir Conda
    cd Conda/
    wget https://repo.anaconda.com/miniconda/Miniconda3-py39_4.12.0-Linux-x86_64.sh .
    sh ./Miniconda3-py39_4.12.0-Linux-x86_64.sh -b -u -p <install_dir>

  Here, 

  * the `-b` option will accept the license agreement and will skip all the prompts
  * the `-u` option will tell the installer to do all the needed updates
  * the `-p` option followed by the installation directory path (will be created), tells
     the installed where to install the package.

  Test it is working by doing:

    which conda


#### 1.2 Update the conda

  Actually, let's not do this:

    conda update -n base -c defaults conda


#### 1.3 Activate the environment

  Add the following line to you `.bashrc` or `.bash_profile` scripts:

    eval "$(<path to bin/conda> shell.bash hook)"

  For instance, 

    eval "$(/projects/academic/cyberwksp21/SOFTWARE/Conda/bin/conda shell.bash hook)"

  Restart your terminal or reload the `.bashrc` script:

    source ~/.bashrc


  When you do this, your command line should show up the (base) in front, indicating that
  the base environment is ready

  Test it is working by doing:

    which conda



### 2. Create the environment equipped with all Libra needs 

#### 2.1 Create the `libra` environment 

  In fact, you can call it whatever you like:

    conda create -n libra python=3.7

#### 2.2 Activate this environment

    conda activate libra

This is very important step - when activated, all the installs will go into that folder. 

**In case you mess up with an environment**, you can remove it with:

    conda remove --name libra --all


#### 2.3 Now, equip your environment with the required packages

Do this **one by one, and in this order**, (should not matter too much, but who knows...)

    > To automate the below procedures, you can use `-y` option to accept prompts (sometimes this will override)
    > previous packages/conflicts, so be careful
    > 
    > You can also use `-q` to get rid of all the messages to the output, although i'd keep it to keep track of what's going on


First let's install the most general packages:

    conda install -y -c conda-forge numpy scipy matplotlib imageio jupyter_core
    conda install -y ipykernel
    conda install -y -c rmg py3dmol


Next, all what we actually need:

    conda install -y conda-build make
    conda install -y -c conda-forge gcc_linux-64=12.2.0 gxx_linux-64=12.2.0 cmake=3.24.2 boost=1.80.0 python-devtools llvm-openmp
    conda install -y -c conda-forge/label/gcc7 eigen mpfr
    conda install -y -c psi4/label/dev libint2=2.7.1
    conda install -y -c anaconda h5py gmp


Installation instruction of Scikit-learn from its official website:

    pip install -U scikit-learn

 
    >
    >  YES - IT GOT SMALLER AND MORE COMPACT !
    >


### 3. Download and build Libra

#### 3.1 Get it from the GitHub and choose the right branch

  Clone the repo from the GitHub

    git clone https://github.com/Quantum-Dynamics-Hub/libra-code.git libra

  and switch to the correct branch or tag - usually, it would be `devel` branch

    cd libra
    git checkout devel

#### 3.2 Create the build directory and make the Makefiles

   Then in the `libra` directory, create the build directory:

    mkdir _build
    cd _build
    cmake ../

#### 3.3 Compile the package
    
    make -j4


### 4. Make it ready to use

   Add the following exports to your `.bash_profile` file

    export PYTHONPATH=<path to the ppackage>/libra/_build/src:$PYTHONPATH


   Restart the terminal or source the bash profile and activate libra conda environment

    source .bash_profile 
    conda activate libra
    
   And you should be ready to use Libra.




## Developers and Contributors

  * Dr. Alexey Akimov (University at Buffalo, [link](https://akimovlab.github.io/index.html) )  
      The main developer and maintainer of the code

  * Mr. Brendan Smith (University at Buffalo) 
      Entangled trajectories Hamiltonian, NA-MD with spin-orbit coupling, NBRA workflows, BL-LZ NA-MD tutorials and examples, 
      Libra/DFTB+, Libra/QE, Libra/ErgoSCF, Libra/CP2K, and Libra/Gaussian interfaces
      
  * Mr. Mohammad Shakiba (Shahid Bahonar University of Kerman, Iran)
      Cube file processing scripts, Libra/CP2K and Libra/Gaussian, Libra/Libint2 interfaces

  * Mrs. Story Temen (University at Buffalo)
      Implementation and testing of the HEOM codes

  * Dr. Wei Li (Hunan Agricultural University)
      NA-MD with spin-orbit coupling

  * Dr. Kosuke Sato (Toyota Research Lab) 
      State reordering scripts, Libra/GAMESS interface (Libra-X)

  * Dr. Ekadashi Pradhan (York University) 
      Libra/QE interface, delta-SCF NA-M (Libra-X)

  * Dr. Amber Jain (Indian Institute of Technology Bombay, India)
      Implementation and testing of the HEOM codes

  * Dr. Xiang Sun (NYU Shanghai, China)
      Implementation and testing of the FGR codes

  * Dr. Sophya Garashchuk (University of South Carolina)
      QTAG theory development

  * Dr. Matthew Dutra (University of South Carolina)
      Implementation and testing of the QTAG codes

## References

This code is provided in the hope it will be useful. 

  If you use the code in your research, please cite the following paper(s):

  ### Papers that describe Libra or its features 

  * [The initial implementation](http://onlinelibrary.wiley.com/doi/10.1002/jcc.24367/full)
  Akimov, A. V. "Libra: An open-Source 'methodology discovery' library for quantum and classical dynamics simulations" 
  *J. Comput. Chem.*  **2016**  37, 1626-1649

  * [Phase correction, Ehrenfest dynamics details, basis transformations (see the SI)](https://doi.org/10.1021/acs.jpclett.8b02826)
  Akimov, A. V.; "A Simple Phase Correction Makes a Big Difference in Nonadiabatic Molecular Dynamics"
  *J. Phys. Chem. Lett.*  **2018** 9, 6096-6102

  * [Belyaev-Lebedev-Landau-Zener Surface Hopping within the Neglect of Back-Reaction Approximation](https://pubs.acs.org/doi/10.1021/acs.jpclett.9b03687)
  Smith, B.; Akimov, A. V. "Hot Electron Cooling in Silicon Nanoclusters via Landau-Zener Non-Adiabatic Molecular Dynamics: 
  Size Dependence and Role of Surface Termination" *J. Phys. Chem. Lett.* **2020** 11, 1456-1465

  * [HEOM implementation](https://pubs.acs.org/doi/10.1002/qua.26373)
  Temen, S.; Jain, A.; Akimov, A. V. "Hierarchical equations of motion in the Libra software package"
  *Int. J. Quant. Chem.* **2020**


  You may find the following papers useful examples
  ### Parers that utilize Libra

  * [Formulation of a fragment-based NA-MD](http://pubs.acs.org/doi/abs/10.1021/acs.jctc.6b00955)
  Akimov, A. V. "Nonadiabatic Molecular Dynamics with Tight-Binding Fragment Molecular Orbitals" 
  *J. Chem. Theory Comput.*  **2016** 12, 5719-5736

  * [Quasi-stochastic Hamiltonian for longer NA-MD](http://pubs.acs.org/doi/abs/10.1021/acs.jpclett.7b02185)
  Akimov, A. V.; "Stochastic and Quasi-Stochastic Hamiltonians for Long-Time Nonadiabatic Molecular Dynamics"
  *J. Phys. Chem. Lett.*  **2017** 8, 5190-5195

  * [Entrangled-trajectories Hamiltonian dynamics to capture quantum effects of nuclei](https://doi.org/10.1063/1.5022573)
  Smith, B. A.; Akimov, A. V. "Entangled trajectories Hamiltonian dynamics for treating quantum nuclear effects" 
  *J. Chem. Phys.* **2018** 148, 144106

  * [Inclusion of the Spin-orbit coupling in NA-MD](https://doi.org/10.1021/acsenergylett.8b01226)
  Li, W.; Zhou, L.; Prezhdo, O. V.; Akimov, A. V. "Spin-Orbit Interactions Greatly Accelerate Nonradiative Dynamics
  in Lead Halide Perovskites" *ACS Energy Lett.* **2018** 3, 2159-2166




