Pteros  2.0
Molecular modeling library for human beings!
 All Classes Functions Variables Friends Pages
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.

How to cite Pteros?

Any work, which uses Pteros, should cite the following paper:

  • Semen O. Yesylevskyy, "Pteros: Fast and easy to use open-source C++ library for molecular analysis", Journal of Computational Chemistry, 2012, 33(19), 1632–1636. doi: 10.1002/jcc.22989.

Is Pteros for you?

Pteros library is for you if:

  • You want to implement custom non-standard algorithms of molecular analysis.
  • Your task is computationally expensive and potentially reusable.
  • You want to run several "heavy" analysis tasks in parallel.
  • You are not satisfied by the speed and memory consumption of the scripting languages embedded into popular molecular analysis programs, such as PyMol or VMD.
  • You know C++ or don't mind learning this rather hard, but very powerful language.
  • You know Python or want to learn it. Python scripts in Pteros are good for "throw-away" one-time scripts and serious reusable programs alike.

Pteros is not for you if:

  • Your task requires extensive usage of molecular visualizer. Pteros doesn't have one currently.
  • You have no programming skills at all, or you don't want to learn C++ or Python.

Features

  • Reading/writing popular molecular structure and trajectory formats (PDB, GRO, MOL2, XTC, TRR, TPR, DCD, TNG).
  • Very simple and expressive syntax for selecting groups of atoms similar to one used in VMD, but more powerfull.
  • Selections can be manipulated in many different ways from simple translation to orientation by principal axes.
  • Various properties of selections could be queried ranging from center of masses to radius of gyration.
  • RMSD fitting and alignment.
  • Full support for arbitrary periodic boxes - periodic selections and distances, wrapping/unwrapping, removing jumps over boundaries, computing closest images and shortest vectors, etc.
  • Computing non-bonded interactions with any force field available in Gromacs format (GROMOS, CHARMM, AMBER, OPLS and more).
  • Ability to work with very large trajectories, which does not fit into the memory.
  • Asynchronous processing made easy. Many different analysis tasks could be run in parallel and simulataneously with trajectory reading.
  • Very powerful and flexible syntax of the command-line options for custom analysis programs and scripts.
  • Easy to use. API is very simple and intuitive.
  • Easy to extend. Pteros is writen in high-level C++.
  • Oriented to human beings (reserachers and students), not to programming gurus. The code is very well structured and documented.
  • Bindings for the Python language.
  • Plugin architecture, which makes writing C++ or Python code for asynchronous trajectory analysis trivial. You concentrate on the analysis algorithm itself, not on the technical details of managing files and trajectories.

Some less widely used features:

  • Elastic network model calculations.
  • Support for residue-level DFIRE potentials.

Development status

Pteros is a mature but evolving library. The librray is stable, but API (especially in the part of Python bindings) is still subject to small changes. There are bugs here and there, 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!

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 Linux, 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.

Note
If you managed to compile Pteros on MacOS, please share your experience because we have no Mac machines to perform the tests.
Warning
Intel ICC compiles Pteros on Linux, but gives poor performance. Compiling with Intel MKL works, but gives broken Python bindings. Any help with these issues is appreciated!

Dependencies

The prerequisites for compilation of Pteros are the following:

  • Standard-conforming C and C++11 compilers (tested with gcc>=4.8, clang>=3.1).
  • cmake build system.
  • boost 1.48 or higher.
  • Git for getting the source code.
  • Python 2.5 or higher (optional if you don't use dynamic plugins and python bindings)
  • Doxygen (only if you want to build documentation yourself)
  • Sphinx (only if you want to build documentation for python bindings yourself)

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 from the Git repository:

git clone -b experimental 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 source code into it.

You can also get the "stable" branch:

git clone git://git.code.sf.net/p/pteros/code pteros-code
Warning
Currently the stable branch is significantly outdated and not as stable as it should be. It is advised to use experimental branch for all projects. This may change in the future.

If you need an 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
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 separate 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
Warning
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 following 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 errors then Pteros can't load plugins or something elese went wrong.

Note
This is only applicable 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 completely write to yesint4(AT)yahoo.com and attach error messages and the system configuration (versions of all required libraries and compiler).

Known problems

  • Clang compiler doesn't work with Boost < 1.52
  • If there are several Boost versions in the system CMake may find the right one for one library (say, Boost.threads) but the wrong one for the other (say, Boost.python), 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.

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 use the following flag when invoking cmake:

-DPOWERSASA="ON"

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

Note
I contacted the authors of POWERSASA several times to ask for official permision to use their code but got no reply. It seems that nobody is concerned about the licensing of POWERSASA now. But you are warned :)

Linking with Pteros

It is recommended to use CMake. 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 your own program with pteros libraries.

Building Pteros without Python

Pteros could be build without Python. If no 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:

-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> -DPYTHON_BINDINGS="ON" -DSTANDALONE_PLUGINS="ON"
make
make install
Note
In this case each plugin will be compiled twice, so expect longer compilation time.

Third-party software integrated into Pteros

  • xdrfile library from GROMACS.
  • Eigen - highly optimized vector/matrix library.
  • POWERSASA code for Solvent Accesible Surface Area (SASA) computatations. Now inclided into SIMONA package.
  • dssp 2.0 code for secondary structure computations.
  • Molfile plugins from VMD for reading PDB, DCD, MOL2 and TNG files.

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:

  • Basic syntax
  • Classes and ingeritance
  • STL containers

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.

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 new algorithms.

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.