Libra

This is the main page of the computational chemistry methodology discovery library, Libra The program website is here

Info

More:

• Training & Usage
• Autogenerated Documentation

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 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

• Installing WSL2: After reboot

• Installing Ubuntu on Windows 11

• Creating Conda environment for Libra

• Installing Libra

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

Next, all what we actually need:

conda install -y conda-build make
conda install -y anaconda::py-boost
conda install -y -c conda-forge gcc_linux-64=12.2.0 gxx_linux-64=12.2.0 cmake=3.24.2 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

Install Jupyter Lab or traditional Jupyter notebook as explainted here:

pip install -U jupyterlab

or 

pip install -U notebook

Install py3Dmol for viewing molecular structures:

pip install -U py3Dmol

Installation instruction of Scikit-learn from its official website:

pip install -U scikit-learn


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

Install PyTorch - since the current versions of Libra have a growing number of functions/modules written with PyTorch. The general instructions can be found here

As a simple (most common case, peraps), we install PyTorch for CPU on Linux with:

pip install -U torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

or

conda install pytorch cpuonly -c pytorch

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.

Useful notes:

1. 2/15/2025 (from Liz Stippell):

Notes on making Libra if you have python v3.7+ installed anywhere on your system (Linux): Although the libra environment is made with python 3.7, during the cmake ../ step it will search for any python, including versions outside of the libra environment. (Ex: my system kept finding python v3.9 in my Miniconda here: /path/to/Conda/Miniconda3/include/python3.9 instead of searching within the libra environment: /path/to/Conda/Miniconda3/envs/libra )

To avoid this issue, you can add the following lines in the CMakeLists.txt file in your libra source code directory around line 44:

""" set(Python3ROOTDIR "/path/to/Conda/Miniconda3/envs/libra") set(Python3EXECUTABLE "/path/to/Conda/Miniconda3/envs/libra/bin/python3") set(Python3LIBRARY "/path/to/Conda/Miniconda3/envs/libra/lib/libpython3.7m.so") set(Python3INCLUDEDIR "/path/to/Conda/Miniconda3/envs/libra/include/python3.7m") FIND_PACKAGE(Python3 3.6 REQUIRED COMPONENTS Development) """

This will force the make to search within the libra environment in the specified locations where you know the files exist.

2. 4/17/2025 (Alexey Akimov)

A good way to setup the conda environment to have Boost and Python version consistent is this:

conda install -c conda-forge boost=1.82 python=3.10

3. 4/17/2025 (Alexey Akimov)

Another useful recipe for setting up jupyter notebook specific to a selected Conda environment:

Step 1: Activate the environment

conda activate libra

Step 2: Install ipykernel and register the kernel

conda install ipykernel
python -m ipykernel install --user --name=libra --display-name "Python (libra)"

Now, in Jupyter, you'll see a new kernel called "Python (libra)". Select that in your notebook.

4. 7/31/2025 (from Daeho Han)

Here are some installationinstructions from Daeho Han that may be used as a good revised summary of the above installation instructions:

conda create -n libra
conda install -c conda-forge boost=1.82 python=3.10
conda install -y -c conda-forge numpy scipy matplotlib imageio

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 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

pip install -U jupyterlab
pip install -U py3Dmol
pip install -U scikit-learn
pip install -U torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

Developers and Contributors

• Dr. Alexey Akimov (University at Buffalo, link )
  The main developer and maintainer of the code

• Dr. Daeho Han (University at Buffalo) Implementation of the exact-factorization (XF) methods, quantum trajectories surface hopping (QTSH), validating and testing Ehrenfest dynamics and other internals, implementing some model Hamiltonians

• 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 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) 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 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 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 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 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 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 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