Libra: An open-source "Methodology Discovery" Library

General installation instructions

These instructions are developed on my (AVA) system and may not work in all other cases, but the hope is that they will stay valid most of the time (provided one can suitably customize them). These instructions are now working on the WSL, but can be ported to other systems, like Linux.

1. Get a miniconda installer and install the miniconda. In the home directory (/home/alexey) do the following

   mkdir Conda
   cd Conda/
   wget https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh .
   sh ./Miniconda2-latest-Linux-x86_64.sh
             

   The miniconda will be installed into "/home/alexey/miniconda2". You will be prompted to add this path to the .bashrc file. If you do this, you don't need the do the next step.
2. [optional] If you select not to include the conda path to your PATH variable, you can create an alias which you'll need to invoke before you call conda. In the .bashrc file, you'l add:

   alias c='export PATH=${HOME}/miniconda2/bin:$PATH'
   

   You'll have to reload the terminal for the changes to take effect, or you could simply:

   source .bashrc 
   

   It may help sometimes to restart your terminal after this step!

3. After you've added the alias:
   Create conda environment (name it "py37") and activate it

   c       [Skip this command, if you have skipped step 2]
   conda create -n py37
   source activate py37
             

   In this example, the environment will be created at: "/home/alexey/miniconda2/envs/py37". In the following steps, we'll need to know it.

   Analogously, you can also create another environment - the one with Python2 (e.g. 2.7) being the major Python version. This idea is probably not so good after 2020, when Python 2 will be deprecated. Then, one can switch between the two environments and compile Libra for corresponding Python version and then use the suitable Python environment.

4. Install all the dependencies into the presently active conda environment ("py37" in this example, but you may have called it differently)

   conda install python=3.7
   conda install conda-build
   conda install gcc_linux-64
   conda install gxx_linux-64
   conda install make
   conda install boost
   conda install cmake
   conda install git
   conda install -c anaconda h5py
             

   Make sure you are in the "py37" (or whatever you called it) environment. You can check it by seen the name of the environment in the very left of you terminal prompt, in parenthesis. If you do the instructions above while being in another environment (such as "base" - meaning the system-wide settings), the packages you request to install will be installed into that environment in which case you may find some steps (e.g. compilation or during the run-time) not working properly when you activate the environment you thought you have installed all the needed packages to.

   For some reason, it is best to do the installations one by one, not all together. When I tried all packages in one command, I had some problems with the compilation later.

5. [Optionally] (not needed to compile Libra itself, but may be required for some examples), install the following packages:

   conda install -c conda-forge matplotlib
   conda install -c rmg py3dmol
   conda install -c anaconda scipy 
             

6. Download the code source files from: here

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

7. [ Optionally ] When you cloned the code, the "master" branch will be the default one. Note this branch is updated only periodically, so you may need to switch to a suitable more recent branch. Usually, this will be the "devel" (development branch). Do this by:

   git checkout devel
             

   If you want to use a specific version of the code (yes, we have started tagging!), you can also checkout a particular tag - this may be a better way to be consistent in terms of which code version you are using, but may be not the best option for the development/contribution purposes. Do this by:

   git checkout v3.0.0
             

8. Navigate to the root of the Libra code (the one with the folders like: src, tests, and so on), create the folder for binary files (results of compilation and linking). Prepare the make files (it is important to pass two variables to cmake: DCMAKE_PREFIX_PATH, which should point to the correspondingly used prefix, and the other one, DCMAKE_AR, which should be set to the presently used archiver (needed for creating static libraries)) In the following instuctions, assume the source code is located in: /mnt/c/cygwin/home/Alexey-user/Programming/Project_libra not just in "Libra" as in the example above, so please adjust accordingly.

   cd /mnt/c/cygwin/home/Alexey-user/Programming/Project_libra
   mkdir _build3 
   cd _build3
   cmake -DCMAKE_PREFIX_PATH=/home/alexey/miniconda2/envs/py37 -DCMAKE_AR=${AR} ../
   make 
             

   In the case you decide to compile Libra for both Python2 and Python3 and want to switch between them, I recommend to make two directories: _build2 and _build3 and use each one to "host" the corresponding version of the code (you'll of course need to adjust the paths variables accordingly - see the instructions below)

   Sometimes, the cmake can not find the Boost installation, in this case the error message will suggest you to set up the BOOST_ROOT. For intstance, this occurs on our CCR cluster where the search finds the older boost version by default, but that version doesn't have developer's stuff (.h, .so, tc.). So my workaround it is point the cmake to find a specific version of the boost by the following change in the CMakeLists.txt:

   FIND_PACKAGE(Boost 1.67.0 REQUIRED)
             

   Please, make sure that this is the version that is insalled in your prefix (py37) by the instructions above. Then, I have to call the cmake command with the BOOST_ROOT set to my prefix, which for the CCR system is:

   cmake -DBOOST_ROOT=/user/alexeyak/Soft/Conda/miniconda2/envs/py37 ../
             

   This is where I have installed my all the necessary packages. Yours is likely different.
9. Add the following environment variables in .bash_profile

   export PYTHONPATH=/mnt/c/cygwin/home/Alexey-user/Programming/Project_libra/_build3/src:$PYTHONPATH
   export LD_LIBRARY_PATH=/mnt/c/cygwin/home/Alexey-user/Programming/Project_libra/_build3/src:$LD_LIBRARY_PATH
             

   Load the settings so the changes take effect

   source .bash_profile

10. Activate the environment and use the code

    c   [Skip this command, if you have skipped step 2]
    conda activate py37
              

11. If you have updated your Libra installation and the only changes made to the code concern Python files (e.g. in the libra_py folder), the only build instructions that are needed are (from within the _build directory)

    cmake ../
    make copy-libra-py
    

    Which will merely copy the Python files from the /src directory in the root to the /src in the build folder.

Operation system specific instructions

Linux

Pretty much as written above

Windows (via WSL)

The most straightforward way to install Libra on Window is via the Windows Subsystem for Linux (WSL) which is now available on Windows 10. To install the WSL, follow these instructions

Then follow the instructions above

Windows (via Cygwin)

I haven't yet figured out how to install Libra on Cygwin with the conda support You can build Libra without conda, in which case the instructions will look like:

1. Edit the CMakeLists.txt in the Libra rood directory as:

   #  ADD_DEFINITIONS("-Wall")       # comment this line
   ADD_DEFINITIONS("-Wall -DCYGWIN") # uncomment this line
             

2. Assuming you are in the Libra root directory, create the "_build" folder (can be named otherwise), switch into it and run cmake and make

   mkdir _build
   cd _build
   cmake ../
   make          
             

   Occasionally, you may need to tell cmake where to look for the Boost and Python include and library files. For Python, this is taken care of by the -DPYTHON_INCLUDE_DIR and -DPYTHON_LIBRARY options to cmake. For instance, on my (AVA) system the libraries (python.2.6.exe and libpython.2.6.dll) are located in /home/Alexey_2/Soft/python2.6/bin , whereas the include files (such as Python.h ans bunch of other files) are located in /home/Alexey_2/Soft/python2.6/include/python2.6 So, for the cmake to generate a proper Makefile, I would call the cmake with the corresponding arguments:

   cmake -DPYTHON_INCLUDE_DIR=/home/Alexey_2/Soft/python2.6/include/python2.6 -DPYTHON_LIBRARY=/home/Alexey_2/Soft/python2.6/bin ../
             

   The same situation applies to Boost libraries and include files.
3. Add the following environment variables in the (Cygwin) .bash_profile

   export PYTHONPATH=/home/Alexey-user/Programming/Project_libra/_build/src:$PYTHONPATH
   export LD_LIBRARY_PATH=/home/Alexey-user/Programming/Project_libra/_build/src:$LD_LIBRARY_PATH
             

   Load the settings so the changes take effect

   source .bash_profile

   You are ready to use the code

Content of the root directory

The root directory contains the following items:

• cmake - the cmake scripts for finding some necessary packages - not yet fully functional, will be taken care of later

• developments - the examples of scientific projects (often, published works) developed with the help of Libra package. This folder also includes some of our current developments and scientific-oriented studies.

• docs - the directory containing some documentation and theory regarding the methods implemented in Libra

• notebooks - the directory containing a lot of examples as Jupyter norebooks. These examples highlight various capabilities of Libra.

• py2cpp_code - former Python implementations that have been implemented on the C++ side and re-exposed to Python again. So, this code is removed from the libra_py, but may be still useful as a building/testing/debugging blocks. So, instead of fully removing it from the package, we'll keep this "legacy" code here.

• src - this is the directory containing the source code to be compiled

• tests - this directory contains a collections of what I call test-tutorials. Each test-tutorial both helps the developer to verify and validate the implementation, so it is usually created along the way of implementing the new feature of the Libra code. Once finished by the developer, the resulting testing script becomes a tutorial script - showing a new user the implemented features and how to use them. Along the way, other features of the Libra package maybe showcased, contributing to further learning of the new user.

• unittests - this directory contains a number of formal unit test modules to verify various features of Libra. The codes can be quite useful for learning how to use various Libra functions and data types.

• .gitignore - we use GIT tool to control the versioning of the code and keep track the history of the development. This file simply excludes some types of the files we may have in the development directory (here and in all deeper levels). Usually, these are object files or other large and temporary files (e.g. output of test calculations, etc.). By listing these types of files in the .gitignore, we are telling th git system to not worry about tracking of the changes of these files. The dot in the beginning of the filename makes this file "invisible" (hides it) on the Unix-type systems. This minimizes the chances you delete it unintentionally.

• CMakeLists.txt - this is the main file that defines how to build the Libra code using the cmake utility. It defines all external packages, setups, options, etc. You need to customize it for your particular environment.