Installation

Table of Contents

• Portability
• Dependencies
  • Prerequisites
  • Managed dependencies
    • Required dependencies
    • Optional dependencies
  • Installing on Ubuntu
• Building Pteros
  • Getting the code
  • Compiling
    • Choosing compiler
  • Controlling searching and donwloading of dependencies
  • Testing installation
  • Gromacs support
  • Python support
    • Compiling without python
    • Installing as a python module
  • Building standalone analysis plugins
  • Building without OpenMP
  • SASA code
• Reporting bugs
  • Known problems

Portability

Pteros is currently being developed on Linux Mint with gcc and clang compilers. Design decisions are made with portability to Linux, Windows and MacOS in mind but no testing on Windows and MacOS are made. Other systems were never considered. The code itself should be 100% portable providing that the dependencies are available for your system, but expect platform-dependent quirks and issues, which are common to all complex C++ programs, not only to Pteros.

Note

If you managed to compile Pteros on MacOS, please share your experience because we have no Mac machines to perform the tests.

You are wellcome to provide a guide for compiling Pteros on Windows. I maintained such guide some time ago but now I have no interest in this since I'm not doing any development on Windows.

Warning

Intel ICC compiler was tested in the past on Linux, but was giving poor performance. Compiling with Intel MKL worked, but gave broken Python bindings. No testing with recent versions was performed.

Dependencies

Current version of Pteros is 3.x. It depends on C++17 features and requires sufficiently modern compiler. If you are still limited by old compiler use branch v2 which is outdated but requires only C++11.

Prerequisites

These core dependencies should be installed separately:

• Standard-conforming C and C++17 compilers (tested with gcc>=9.0, clang>=10.0).
• cmake 3.10 or higher.
• boost 1.50 or higher.
• Git for getting the source code.
• Python 3.5 or higher (optional, needed for compiling dynamic plugins and python bindings).

Managed dependencies

Pteros is able to download and compile most of its dependencies automatically, but could also used pre-installed libraries if they are found in the system. By default Pteros searches for pre-installed libraries first and if not found downloads and compiles them itself. This could be configured precisely if needed (see below).

Required dependencies

• Eigen linear algebra library (>=3.2).
• fmt Formatting library.
• spdlog Logging library.
• Pybind11 binding generator library (optional, only needed for python bindings).

Optional dependencies

• Gromacs version 2016.x or higher (for reading Gromacs TPR files and using Gromacs topologies).
• OpenBabel version 2.4 or higher (for reading MOL2 and PDBQT files, performing substructure search, determinign molecular symmetry).
• Doxygen for building documentation.
• Sphinx for building documentation for Python bindings.

Installing on Ubuntu

If you are using latest Ubuntu or other debian-based system it should be enough to run the following command in the terminal to install basic dependencies:

sudo apt-get install g++ cmake libeigen3-dev libboost-all-dev python3-dev python3-numpy pybind11-dev git doxygen python-sphinx

Warning

It is \i not recommended to use Gromacs and OpenBabel installed from repositories when compiling Pteros because they are not discovered correctly and may lead to weird errors, which are very hard to track. Use -DTRY_SYSTEM_GROMACS=OFF -DTRY_SYSTEM_OPENBABEL=OFF. Pteros will download and compile them itself.

Building Pteros

Getting the code

Get the latest source code from the Git repository:

git clone https://github.com/yesint/pteros.git pteros

This will create a directory named "pteros" in you current working directory and will download the source code into it.

Note

Use branch v2 if you need older version which compiles by C++11 compilers.

Compiling

Create a separate build directory (for example 'pteros_build'). Go to this directory and issue the following commands:

cmake <path to Pteros source directory> -DCMAKE_INSTALL_PREFIX=<where to install Pteros>
make
make install

Note

Other available CMake options are discussed below.

Warning

The 'make install' command may require root access if you are installing into the system-wide location.

The cmake command will print something like this:

------------------------------
IMPORTANT!
In order to be able to link with` Pteros and to use Pteros Python modules
you have to source the pterosrc file in your bash shell:
source /home/user/programs/pteros/lib/pterosrc
------------------------------

Copy suggested line and add it to your .bashrc file (it is assumed that bash shell is used. If it is not the case use the syntax of your actual shell instead).

Choosing compiler

If you want to compile with alternative compiler (for example Clang), add the following flags to cmake invocation:

-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++

Controlling searching and donwloading of dependencies

The following CMake variables could be used:

Variable	Meaning
WITH_PYTHON	Build python bindings and compile analysis plugins as Python modules. Default: ON
WITH_OPENMP	Use OpenMP parallelization. Default: ON
WITH_OPENBABEL	Link to OpenBabel to read pdbqt files and for substructure search. Default: ON
WITH_GROMACS	Link to Gromacs to read tpr files. Default: ON
WITH_TNG	Link to TNG_IO library to read tng files. Default: ON
WITH_POWERSASA	Use bundled POWERSASA code. Default: ON
TRY_SYSTEM_DEPENDENCIES	If OFF disables the searach for pre-installed libraries and downloads all dependencies.Default: ON
DOWNLOAD_DEPENDENCIES	Allow downloading and compiling dependencies. Default: ON
TRY_SYSTEM_EIGEN	Try using system Eigen. Default: ON
TRY_SYSTEM_FMT	Try using system fmt. Default: ON
TRY_SYSTEM_SPDLOG	Try using system spdlog. Default: ON
TRY_SYSTEM_PYBIND11	Try using system pybind11. Default: ON
TRY_SYSTEM_GROMACS	Try using system Gromacs. Default: ON
TRY_SYSTEM_OPENBABEL	Try using system OpenBabel. Default: ON
GROMACS_SOURCE_DIR	Location of Gromacs sources in the system
GROMACS_BINARY_DIR	Location of Gromacs binaries in the system

Combining these variable one can control how each of dependencies is discovered in the system and downloaded if not found.

Testing installation

Run the following command:

pteros_analysis.py --help all

If you see any errors then Pteros can't load plugins or something elese went wrong.

Note

This is only applicable if you are building with Python support!

Gromacs support

Pteros could be linked against Gromacs. In this case it can read Gromacs TPR files and make advantage of Gromacs topologies.

Unfortunately Gromacs developers are changing the public API from one version to the other, while Pteros still needs some low-level facilities which are now no longer exposed in the installed headers. There are also bugs in some Gromacs versions, which prevents it from being discovered and imported normally in CMake. Due to all these complications linking with Gromacs becomes a bit more involved than it should be.

You have two options:

• Let Pteros download latest Gromacs version from git, compile the minimal static library and link it automatically. This is the simplest and the most reliable way, but it takes significant time to compile. It is used by default.
• Use the pre-installed version of Gromacs. In this case in addition to normal Gromacs installation you need a source code matching \i exactly the version installed. You need to use the following CMake flags:

  -DWITH_GROMACS=ON -GROMACS_SOURCE_DIR=<path to gromacs source tree> -GROMACS_BINARY_DIR=<path to installed gromacs with the 'lib' folder inside>

Python support

If both Python 3.x and 2.7 are installed in your system the version 3.x will be used automatically (even if 2.7 if the system-default, like in some older Ubuntu versions).

Note

Make sure that you use correct python interpreter! Always use python3 with Pteros.

Compiling without python

Pteros could be build without Python by specifying the following flag:

-DWITH_PYTHON="OFF" 

In this case compiled C++ plugins are not built as python extension modules and python bindings are not built at all.

Installing as a python module

It is also possible to install Pteros in "pythonic" way using pip. In this case you get Pteros as a normal python module installed correctly as any other python package, but you have no control on the compilation process (unless you edit the setup.py script).

Run the following command from the Pteros directory:

pip3 install .

Warning

This method only works with python >= 3.8.

Building standalone analysis plugins

Analysis plugins, which are written in C++, are compiled as Python extensions by default. However, it is possible to build each plugin as a separate standalone program, which does not depend on Python, by adding the following flag to CMake:

-DSTANDALONE_PLUGINS=ON 

If you want to build plugins as the standalone programs AND as python extensions at the same time use the following flags:

cmake <usual options> -DWITH_PYTHON=ON -DSTANDALONE_PLUGINS=ON
make
make install

Note

In this case each plugin will be compiled twice, so expect longer compilation time.

Building without OpenMP

By default Pteros is compiled with OpenMP paralellization for many internal operations. However, on certain computational clusters the usage of OpenMP is prohibited. There are also other situations when you may want to disable OpenMP. Use the following flag to compile without OpenMP:

cmake <usual options> -DWITH_OPENMP=OFF

SASA code

Pteros performs the Solvent Accesible Surface Area (SASA) computatations using POWERSASA code developed in the Karlsruhe Institute of Technology. POWERSASA is licensed by specific and rather restrictive "Academic/Non-Profit SASA software license agreement". See the file thirdparty/sasa/LICENSE for details. This license is NOT Open Source and implies many restrictions. I contacted the authors of POWERSASA several times and asked for official permission to use their code but got no reply. It seems that the project is abandoned for a long time and nobody is concerned about the licensing of POWERSASA for many years. If you still don't want to use this code due to possible licensing concerns, you can swith it off:

-DWITH_POWERSASA=OFF

Reporting bugs

Use issues on Github to report bugs.

Known problems

• Linking with libopenbabel-dev installed from repositories fails in Ubuntu 16.x and 18.x due to corrupted headers in the package. Allow Pteros to download and compile OpenBabel instead.
• Clang compiler doesn't work with Boost < 1.52
• OpenMP in clang only works for clang++ >= 3.8 and if libomp is installed: sudo apt-get install libomp-dev
• If there are several Boost versions in the system CMake may find the right one for one library but the wrong one for the other, which causes very strange errors. The solution is to include the following flags to CMake invocation:

  -DBoost_NO_SYSTEM_PATHS=ON -DBOOST_ROOT="Correct path to boost" 

• All Pteros plugins have to be up to date with the main library, but CMake doesn't always ensure this if you pull new updates from the repository. If plugins suddenly stop working after update delete CMakeCache.txt and CMakeFiles and recompile.
• The error "trying to overwrite '/usr/include/spdlog/async_logger.h', which is also in package libspdlog-dev 1.6-1" occurs during installation. This happens if you have spdlog installed system-wide in Ubuntu from the package libspdlog-dev. This package is built in a wrong way and it lacks spdlogConfig.cmake file needed for correct library detection. That is why Pteros can't see it and tries to install its own bundled version of spdlog. Allow Pteros to download spdlog itself instead: -DTRY_SYSTEM_SPDLOG=OFF.