Pteros  1.0
Welcome to Pteros!

Contents

What is Pteros?

Pteros is a C++ library for molecular modeling. It is designed to simplify the development of custom programs and scripts for molecular modeling, analysis of molecular dynamics trajectories and implementing new simulation and analysis algorithms. Pteros provides facilities, which are routinely used in all such programs, namely input/output of popular file formats, powerful and flexible atom selections, geometry transformations, RMSD fitting and alignment, etc. Pteros also contains powerful facilities for parsing command-line arguments in custom programs and for running several analysis tasks in parallel, utilizing the power of modern multi-core processors.

Pteros supports writing analysis programs in either C++ or Python programming languages.

Is Pteros for you?

Pteros library is for you if:

Pteros is not for you if:

Motivation

So, why yet another molecular modeling library? First of all because I didn't find any C++ library for molecular modeling which satisfies my needs. Existing libraries are either too complicated or has clumsy and counterintuitive API. Of course all this is the matter of personal preference, but I have a feeling that many other researchers also desperately look for simple and clear library, which can simplify tedious routine tasks in molecular modeling.

There are several molecular modeling programs, which could be controlled by the scripting languages. Such scripting is often used to perform non-standard analysis tasks. This is perfectly acceptable if the execution time is not an issue, however any computationally intensive algorithm will run ridiculously slow in the scripting language like Python or TCL. Pteros is designed as a replacement of such scripting extentions to existing molecular modeling software. With Pteros one can easily write very fast compiled programs in C++ using the same high-level concepts, which are provided by the scripting extentions.

Pteros contains bindings for Python language. They come handy when one need small throw-away program or in prototyping the algorithms.

Features

Some less widely used features include:

Development status

Pteros is currently very close to what could be called a stable release. The librray is quite stable and usable, but API (especially in the part of Python bindings) is still subject to small changes, error reporting is still incomplete and many features are not implemented yet. You are wellcome to participate in pteros development - there are a lot of things to do!

In its final form Pteros will consist of the following components:

Installation and linking with pteros

Portability

Pteros is being developed on Linux with gcc and clang compilers. New versions are tested periodically on Windows under MinGW gcc compiler (see Installing Pteros on Windows). Other compilers and operating systems are not tested because we have no other systems in possession. Design decisions are made with portability to Windows and MacOS in mind. Other systems are not 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.

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

Intel ICC compiles Pteros on Linux, but gives poor performance. Compiling with Intel MKL works, but gives broken Python bindings. Any help in these issues is appreciated!

Dependencies

The prerequisites for compilation of Pteros are the following:

If you are using Debian or Ubuntu it should be enough to run the following command in the terminal to install all dependencies:

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

Installation of dependencies on Windows is described here Installing Pteros on Windows.

Note
Starting from May 2014 Pteros has moved to C++11 standard. As a result it can only be compiled with sufficiently modern C++ compilers. We are aware that many workstations and computational clusters still has ancient versions of compilers, which do not support C++11. For such situations an older C++98 version of Pteros is preserved in a separate repository (see below).

Building Pteros

Getting the code

Get the latest source code could from the Git repository. If you want the stable branch use the following command:

git clone git://git.code.sf.net/p/pteros/code pteros-code

This will create a directory named "pteros-code" in you current working directory and will download the latest stable branch of Pteros source code into it.

You can also get the latest development branch (named "experimental"), which is the bleading-age of Pteros development but may contain some bugs and unstable features:

git clone -b experimental git://git.code.sf.net/p/pteros/code pteros-code

If you need older version, which does not contain C++11 features, use the "optional_cpp11" branch:

git clone -b optional_cpp11 git://git.code.sf.net/p/pteros/code pteros-code
Warning
Currently the stable branch is considered significantly outdated and it is advised to use experimental branch for new projects. This may change in the future. The optional_cpp11 branch is completely outdated and will never get new features. It is preserved only for compatibility with ancient compilers.

Compiling

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

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

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

The first 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 add the following lines to your .bashrc file:
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:<path to Pteros>/lib"
export PYTHONPATH="$PYTHONPATH:<path to Pteros>/python"
export PATH="$PATH:<path to Pteros>/bin"
------------------------------

Copy suggested lines and add them 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).

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

-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++

Testing installation

Run the following command:

pteros_analysis.py --help all

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

Note
This will only work if you are building with Python support!

Troubleshooting

The most common problems during installation arise from bugs in Boost or in the compilers and from the wrong versions of the libraries, which are found by CMake. In general Google is your best friend in solving any problem. If you are stuck write to yesint4(AT)yahoo.com and attach error messages and the system configuration (versions of all required libraries and compiler).

The list of known problems:

Enabling SASA code

Pteros can perform 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 comment in the file src/core/sasa/power_sasa.h for details. This license is NOT Open Source and imply many restrictions! Please read it carefully. If you agree with this license and performed all required steps than use the following flag when invoking cmake:

-DPOWERSASA="ON"

By default this code is NOT compiled. Pteros dosn't support SASA computations without it.

Linking with Pteros

It is recommended to use CMake for all projects, which use Pteros. You can use autoconf/automake or custom Makefiles, but this will never be officially supported. The "template" subdirectory of the source tree contains the skeleton of CMake project, which could be used to link you own program with pteros libraries.

Building Pteros without Python

Pteros could be build without Python. If now Python libraries are found in the System the compilation of Python bindings and plugins is disabled and only the core libraries are built.

If the Python is installed, but you don't want to use it add the following flag to CMake invocation:

-DPYTHON_BINDINGS="OFF"

Compiled analysis plugins, which are written in C++, will be also missing in this case because they are built 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 invocation:

-DSTANDALONE_PLUGINS="ON"

If you want to build plugins as the standalone programs AND as python extensions at the same time you'll need to compile twice:

cmake <usual options> -DSTANDALONE_PLUGINS="OFF"
make
make install
cmake <usual options> -DSTANDALONE_PLUGINS="ON"
make
make install

The first compilation will build and install plugins as python extensions, while the second one will compile them as the standalone programs.

Third-party software integrated into Pteros

The sources of all these libraries are included into the source tree of Pteros, so you don't need to install them separately.

What level of C++ knowledge is required?

In order to develop you own programs with Pteros you need to know C++ reasonably well. However, you don't need to be a guru. Here is the basic list of things, which you should understand:

In addition you should be familiar with Eigen vector/matrix library. Fortunately, it has an excelent documentation.

In order to modify internals of Pteros you should also be familiar with some Boost libraries, namely Boost.thread, Boost.bind, Boost.signals2, Boost.multiarray and Boost.python.

Benchmarks

We compared performance of three small test programs in Pteros and VMD. The first program fits all trajectory frames to the reference structure and computes their RMSD with the reference. The second program finds atoms in two selections, with the distance between their centers less then 0.25 nm. The third program creates atom selections for each residue in the system on each loaded frame, which gives good estimate of the raw speed of selection parsing. In VMD the bigdcd script was used to process frames one by one without loading the whole trajectory into the memory. The MD trajectory of human tyrosyl-tRNA sinthetase, which contains 10744 atoms was used. First 1000 frames of trajectory where analyzed. Results of comparison are shown below:

Table 1. Execution time (in seconds) of three benchmark programs in Pteros and VMD.

# Benchmark Pteros VMD Ratio VMD/Pteros
1 Fitting and RMSD calculation 1.6 5.1 3.18
2 Finding contacting atoms 3.9 7.4 1.9
3 Creating selections for each residue 63.1 2900.0 45.9

Since VMD scripts for these benchmarks are very simple and call low-level built-in routines for the most of their work, the overhead of the TCL interpreter is rather minimal in our test. Any larger script, which performs complex computations and data manipulations, will have much larger overhead in comparison to compiled code. However, even these small scripts run significantly slower then compiled programs, which use Pteros. The parsing of atom selections in VMD is dramatically (46 times) slower then in Pteros, despite almost identical selection syntax. This introduces large performance penalty for any code in VMD, which creates many selections in the course of execution. Due to parallel execution of analysis tasks in Pteros running them simultaneously increases execution time only by few percent, while in VMD the execution time of all tasks is summed up (data not shown). Source code of the benchmark programs is included into the Pteros distribution and located in “examples” directory.