 |
Structural Bioinformatics Library
Template C++ / Python API for developping structural bioinformatics applications.
|
|
Structural Bioinformatics Library
Template C++ / Python API for developping structural bioinformatics applications.
|
Tutorial guiding the installation of the library.
The SBL consists of several software tiers:
Executables, scripts, python modules. The installation procedures described below mainly focus on installing the compiled executables and scripts, as well as the plugins for VMD, PyMOL, and web servers.
Documentation. The SBL documentation is accessible in two ways:
Note: Doxygen version 1.14.0 is required.
There are three main options to use the SBL:
C++ include files. Developers should git clone the sbl to reuse the C++ packages provides.
We deploy two packages, sbl and sbl-doc, to the Anaconda sbl channel. Using Pixi, you can install them easily. The sbl package contains the compiled executables and scripts, Python modules, plugins for VMD, PyMOL and the Web dashboard, and the header and CMake files needed by developers. The sbl-doc package contains the documentation source files, figures, examples and demos only.
Prerequisites
Install Pixi if you haven't already. Follow the official installation instructions, which provide one-line commands for macOS/Linux:
After installation, restart your terminal to ensure Pixi is available in your PATH.
Initial setup
Create a fresh Pixi workspace dedicated to SBL, for example:
Add the SBL package
The order of the channels matters and differs by platform:
OSX (macOS):
Linux 64:
Install and configure SBL
The last command installs the SBL plugins into the VMD Extensions menu and the PyMOL command line, and sets up a launcher for the Web plugins. It also updates your shell configuration files (e.g., .bashrc, .zshrc) to export the necessary environment variables so that SBL tools are available in future shell sessions.
Restart your terminal to apply these changes.
To launch the Web plugins dashboard, run:
Then open the URL printed in the terminal (typically http://127.0.0.1:8700/) in your web browser.
Initial setup
Create a dedicated Pixi workspace for the development build, for example:
Add the SBL dev package
As for the stable channel, the order of channels matters and differs by platform:
OSX (macOS):
Linux 64:
The remaining steps (installation, plugin setup, and web launcher usage) are identical to those described for the stable Pixi environment above.
Available upon request.
The section presents the dependencies required to install and compile the SBL. The following are two important remarks:
set(SBL_USE_LIBS CGAL MPFR GMP Boost Eigen cifpp)
These libraries provide classes implementing number types and the accompanying operations, allowing the development of algorithms with specific arithmetic requirements:
Note that GMP and MPFR are mandatory to use CGAL . For each library, if one of them is installed in a non standard location, the <LIBRARY_NAME>_DIR environment variable needs to point to the root directory of that library.
In the SBL, interval arithmetics is managed using the Boost library. However, in order to use multi-precision interval arithmetic, the library MPFI has to be installed. It is used in particular to compute the volume of unions of balls in SBL. When MPFI is used for the compilation of a program, the C++ macro SBL_WITH_MPFI is automatically defined, enforcing the use of MPFI rather than Boost for managing multi-precision interval arithmetic. If MPFI is installed in a non standard location, the MPFI_DIR environment variable needs to point to the root directory of the library.
The reference C++ Boost libraries provide various tools used throughout the library — see Boost home page for more details.
While the generic components of Boost are directly integrated in Core, the following non generic Boost packages are used in the applications:
If Boost is installed in a non standard location, the BOOST_ROOT environment variable needs to point to the root directory of Boost .
The Computational Geometry Algorithms Library (CGAL) provides various core geometric constructions. In particular, CGAL is used in large number of packages in Core. A number of libraries are provided with the CGAL library, as the GMP and MPFR libraries. A detailed explanation on how to install the CGAL library is provided on the CGAL installation guide.
Note that if the CGAL library is installed in a non standard location, the CGAL_DIR environment variable must point to the root directory of CGAL.
libcifpp provides the tools to parse PDB and mmCIF files.
The Eigen library is used for linear algebra, in particular to represent matrices and compute eigenvalues.
If the Eigen is installed in a non standard location, the EIGEN_DIR environment variable needs to point to the root directory of the Eigen library.
Ipopt (Interior Point OPTimizer; a.k.a. coin-or-Ipopt) is a library for non-linear optimization. It is used in the package Real_value_function_minimizer for finding local minima of real value functions. If the library is installed in a non-standard location, the IPOPT_ROOT environment variable needs to point to the root directory of the library.
LBFGS++ (Limited-memory BFGS) is a header-only C++ library that implements the eponym algorithm–see the Download or clone page. It is used in the package Real_value_function_minimizer for finding local minima of real value functions. Since it is header-only, it is easy to install and to use, making an easy alternative to the Ipopt library. If the library is installed in a non-standard location, the LBFGSPP_DIR environment variable needs to point to the include directory of the library.
The binary program lp_solve is used to solve the linear programs arising when comparing energy landscapes. The environment variable LP_SOLVE must be set to indicate the location of the binary.
Seqan is a C++ header-only library providing a collection of sequence alignment algorithms. It is used in the package Alignment_engines. If the library is installed in a non-standard location, the SEQAN_DIR environment variable needs to point to the include directory of the library.
FLANN (Fast Library for Approximate Nearest Neighbors) is a library offering a collection of approximate nearest neighbor algorithms and methods for peaking the best algorithm to use ependening on the input dataset. It is wrapped in the class SBL::GT::T_ANN_FLANN_wrapper of the package Spatial_search for comparing / replacing the other algorithms implemented in the package. If the library is installed in a non-standard location, the FLANN_DIR environment variable needs to point to the root directory of the library.
Gromacs is used for loading trajectories of conformations from XTC files in the package MolecularGeometryLoader. If the library is installed in a non-standard location, the GROMACS_DIR environment variable needs to point to the root directory of the library.
rapidxml is a header only C++ XML parser used in the SBL for loading force field parameters from XML files in the package Molecular_potential_energy . If the library is installed in a non-standard location, the RAPIDXML_DIR environment variable needs to point to the root directory of the library.
OpenMP is used to parallelize loops in the SBL. It is particularly used for parallelizing the run of collections of modules within workflows – see Modules when using workflows. When OpenMP is used for the compilation of a program, the C++ macro SBL_WITH_OPENMP is automatically defined, enforcing the use of OpenMP for parallelizing the for loops.
The source code is available from the following tarball.
It may also be obtained by cloning the read-only git repository as follows:
git clone https://sbl.inria.fr/git/sbl.git
In the sequel, we assume that the environment variable SBL_DIR points to the directory containing the source code.
We provide a Pixi configuration file to compile and install the SBL library from the source code:
Note: If you encounter the following error when running an SBL executable:
error while loading shared libraries: libboost_program_options.so.1.86.0: cannot open shared object file: No such file or directory
This occurs because the dynamic linker cannot locate the Boost shared libraries installed in the Pixi environment. To fix this, add the following line to the end of your shell configuration file (~/.bashrc or ~/.zshrc):
export LD_LIBRARY_PATH="$PIXI_ENV_DIR/lib:${LD_LIBRARY_PATH}"
Then restart your terminal or run source ~/.bashrc (or ~/.zshrc) to apply the changes.
To compile and install the library from this source code, CMake is used. The version 3.16 or later of CMake is recommended. Note that the following installation requires root privileges to install in a system related directory. If you do not have them, refer to section Non standard installation directory.
The installation runs through four steps:
By default, SBL executables, scripts, includes, Python modules, and plugins are enabled.
Note: On Linux machines, avoid using –parallel without a value, as this will use all available CPU cores; instead, pass an explicit limit such as –parallel 1.
Note: On Linux machines, avoid using –parallel without a value, as this will use all available CPU cores; instead, pass an explicit limit such as –parallel 4.
This last step compiles programs and copies files into standard locations under the chosen prefix (or into the directory pointed at by CMAKE_INSTALL_PREFIX; see below):
Note that if a new version of the library is available, the installation must be carried out again upon updating the git repository.
> cmake --build build_sbl --target uninstall
In this section, we show the various options for compiling the different parts of the library, and installing it.
When installing the SBL library, one may not have the root privileges, and/or may want to install the SBL into a local directory. Doing so merely requires setting the cmake variable CMAKE_INSTALL_PREFIX to your local install directory when running cmake:
> cmake -S \</path/to/sbl/directory\> -B build_sbl -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=\</path/to/local/install/directory\> > cmake --build build_sbl --parallel > cmake --install build_sbl
Given this target directory, executables are installed in the bin sub-folder of the install prefix, while Python modules are installed in lib/pythonX.Y/site-packages/SBL under that prefix.
> export PATH=$PATH:\</path/to/local/install/directory\>/bin > export PYTHONPATH=$PYTHONPATH:\</path/to/local/install/directory\>/pythonSimilarly, developers may directly address the python modules available in the cloned directory as follows:
export PYTHONPATH=${PYTHONPATH}:${SBL_DIR}/python/SBL
export PYTHONPATH=${PYTHONPATH}:${SBL_DIR}/python
Within a package from Core, integration tests can be viewed as short programs showing the basic functionalities provided in that package. To compile such programs, turn the SBL_INTEGRATION_TESTS to ON where running cmake.
In addition, unit tests can be used in such packages, by compiling and running short test programs checking various functionalities of the packages. For compiling all the tests of the SBL library, just turn ON the tags SBL_UNIT_TESTS when running cmake
> cmake -S \</path/to/sbl/directory\> -B build_sbl -DSBL_UNIT_TESTS=ON -DSBL_INTEGRATION_TESTS=ON > cmake --build build_sbl --parallel
Then, to exectue all tests (UNIT and INTEGRATION) for all the packages from Core, just run the them with the following command:
> ctest --test-dir build_sbl --output-on-failure
Note that the previous step does not require any installation step since the examples and tests are only compiled locally and only the sources of the examples are installed for documentation (in /usr/share/doc).
It is possible to compile the programs in Debug or in Release mode using the cmake variable CMAKE_BUILD_TYPE. However, since the SBL library is only made of headers and programs, we recommend the Debug mode only for the developers. For compiling in Debug mode, one can run the following command:
> cmake -S \</path/to/sbl/directory\> -B build_sbl -DCMAKE_BUILD_TYPE=Debug > cmake --build build_sbl --parallel
Note that by default, the Release mode is used. Note also that to debug symbols from other libraries, if these are not header-only, compiling them in Debug mode is mandatory.
It is possible to create static versions of the programs by setting to ON the cmake variable BUILD_STATIC_SBL:
> cmake -S \</path/to/sbl/directory\> -B build_sbl -DBUILD_STATIC_SBL=ON > cmake --build build_sbl --parallel
Note also that only the programs are compiled in static mode since the examples and tests are not installed. If one wants to compile static examples or static tests, such compilations should be done locally.
The SBL library provides VMD plugins for visualizing the output of the programs (details in section VMD (Visual Molecular Dynamics)).
It should be recalled that VMD plugins involve three ingredients:
To automatically install the VMD plugins, i.e. create or update the sblvmdplugins directory and create or update the .vmdrc file, proceed as follows with cmake:
> cmake -S \</path/to/sbl/directory\> -B build_sbl -DSBL_VMD_PLUGINS=ON > cmake --build build_sbl --parallel > cmake --install build_sbl
The installation of PyMOL's plugins requires the executables of the SBL to be available via on'e PATH environment variable – see above.
For PyMOL, plugins can be installed in two ways.
Installation with cmake. The SBL library provides also PyMOL plugins (details in section PyMOL (Python Based Molecular Visualization System)). The installation works as for the VMD plugins, but using instead the cmake variable SBL_PYMOL_PLUGINS :
> cmake -S \</path/to/sbl/directory\> -B build_sbl -DSBL_PYMOL_PLUGINS=ON > cmake --build build_sbl --parallel > cmake --install build_sbl
The previous command looks for a folder .pymol in one's home directory, creates it if necessary, and installs the plugins. It manages the directory architecture used by PyMOL and creates or updates initialization files if necessary.
Installation using PyMOL's plugin manager. The graphical user interface of PyMOL provides a Plugin Manager enabling the addition, removal, and inspection of installed plugins. This plugin manager is available from the tab Plugin/Plugin Manager in the horizontal menu. The option Install New Plugin offers three installation options:
The documentation is written in Doxygen format, and can be compiled as follows using the script sbl-doc-manager.py from the scripts directory at the root of the project. This script produces the documentation and prints out the path to the index.html file, to be opened with a web browser:
> sbl-doc-manager.py -w <path/to/sbl/directory> -d <path/to/output/directory>
Note that the option -w can be omitted if the environment variable $SBL_DIR is set.
Doxygen version 1.14.0 is required.
> cd \</path/to/installed/sbl/directory\>/share/doc/SBL; doxygen;In doing so, the files are generated in the current directory. The benefits of using the aforementioned script is that it also performs a number of house-keeping tasks (moving pictures, creating symbolic links, etc).
1.14.0