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 for molecular modeling, analysis of molecular dynamics trajectories and implementing new simulation algorithms. Pteros provides facilities, which are routinely used in all such programs, namely input/output in 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.

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, but these bindings are not the major focus of its development. They come handy when one need small throw-away program or in prototyping the algorithms, but all computationally intensive tasks are supposed to be done in C++.

Features

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 as root to install all dependencies:

apt-get install g++ cmake cmake-curses-gui libboost-all-dev python-dev python-numpy git doxygen

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

Building Pteros

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

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

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

You may have to edit CMakeLists.txt file to set correct paths for the libraries. The most common problem is the non-standard location of the Boost libraries or too old version of Boost.

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.

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 us 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 recommented 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. Here is the minimal CMakeLists.txt file for building your own program, which uses Pteros with CMake on Linux (template directory contains a bit more complicated and standard-conforming example, which is usable on Linux and Windows):

cmake_minimum_required(VERSION 2.6)
project(example_program)

# Set these variables:
SET(PTEROS_INCLUDE_PATH "<your path>/pteros/include")
SET(PTEROS_LIB_PATH "<your path>/pteros/lib")

SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -msse2") 
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fPIC") 
SET(CMAKE_BUILD_TYPE Release)
find_package(Boost 1.48.0 REQUIRED thread)
include_directories(${PTEROS_INCLUDE_PATH} ${Boost_INCLUDE_DIRS})
link_directories(${PTEROS_LIB_PATH})
link_libraries(pteros pteros_analysis pteros_sim xdrfile ${Boost_LIBRARIES})

# Add your .cpp anf .h files here
add_executable(example_executable main.cpp)

Pteros uses the xdrfile library from GROMACS internally. The source of the xdrfile is included into the source tree of Pteros, so you don't need to install it separately.

Pteros relies on highly optimized vector/matrix library Eigen. Eigen is also included into the source tree and the headers are added automatically if you include Pteros headers.

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.