Package Overview

This page gives an overview of the binaries, tools, etc. distributed as part of the APBS software package. It is organized by directory; later chapters provide a more in-depth description on tools specific to particular applications.

The main APBS executable

As mentioned in the Installation and availability section, the main APBS binary, as well as our new Opal client, is installed in ${APBS_PREFIX}/bin where ${APBS_PREFIX} is the top-level directory you chose for the installation. Of course, you can move the binary to any directory you choose. APBS is invoked with a very simple syntax discussed in detail in the Running APBS section.

top

Other tools distributed with the APBS package

APBS contains a number of tools to facilitate the preparation of APBS runs and analysis of the results.

Note In addition to the tools provided with APBS, there are a number of other programs that are not distributed with APBS but which interoperate with our code. Please see the Running APBS section of this manual for more information.

top

Parameterization

Unfortunately, the majority of problems encountered during electrostatics calculations arise in process of taking a structure from the Protein Data Bank and transforming into a file that can be used by the APBS software. The PDB2PQR service was developed to address these issues. Additionally, APBS provides the ability to read plain PDB-format files and assign charges and radii from user-supplied parameter files. These featers are described in the READ parm command description.

APBS provides a few other miscellaneous tools for convertin and parameterizing structures:

tools/conversion/qcd2pqr.awk  Convert a QCD file (UHBD format for a molecule) to PQR format.

tools/conversion/amber2charmm.sh  A script which converts a PDB file with AMBER atom names to a PDB file with AMBER atom names.

tools/conversion/WHATIF2AMBER.sed  A sed script for converting a PDB file with WHATIF atom names to a PDB file with AMBER atom names. Written by Chiansan Ma.

top

Problem setup

In addition to parametrization of the molecule, there are several common operations which are performed to setup the calculation. This section reviews some of the tools available for these operations. Please note that PDB2PQR service also prepares APBS input files.

The following scripts help generate or transform APBS input files.

tools/manip/psize.py  Get the dimensions and center of a molecule in PQR format. Very useful for setting up input files (i.e., grid dimensions, lengths, spacings, etc.) for APBS calculations. Written by Todd Dolinsky and Nathan Baker.

apbs/tools/manip/inputgen.py  Generate an APBS input file from PQR format data using “suggested” parameters. Also can decouple a parallel calculation into a series of sequential (asynchronous) calculations to be performed on a single processor. Written by Todd Dolinsky and Nathan Baker.

tools/mesh/mgmesh  List acceptable grid dimensions/multigrid levels combinations for mg-manual calculations. Written by Nathan Baker.

top

Output data processing

The following tools perform typical analyses of the output data, usually in OpenDX format. These scripts are not meant to be comprehensive; instead, they provide templates for users to generate their own tools.

top

Conversion

The following utilities convert APBS grid output (e.g., potentials, accessibility functions, etc.) into a variety of other formats:

tools/mesh/uhbd_asc2bin  Converts UHBD format grid files from ASCII to binary. Contributed by David Sept.

tools/mesh/dx2mol  Converts OpenDX format data to MOLMOL format. Contributed by Jung-Hsin Lin with bug fixes by Fred Damberger.

tools/mesh/dx2uhbd  Converts OpenDX format data to UHBD format. Contributed by Robert Konecny.

top

Manipulation

The following utilities process APBS grid output in a variety of ways:

tools/mesh/mergedx and tools/mesh/mergedx2  Merge OpenDX format data from several domains (e.g., from a mg-para calculation into a single file). mergedx2 is easier to use and will eventually replace mergedx. Contributed by Steve Bond and Dave Gohara.

tools/mesh/smooth  Apply a very inefficient Gaussian filter to OpenDX format data from APBS. Written by Nathan Baker.

top

Data visualization

This section describes the data visualization tools provided with APBS. A more complete discussion of the various ways to visualize APBS output is presented in the Visualization section of this manual. Old tools for VMD have been removed since they are now completely replaced by OpenDX and APBS functionality available within VMD.

tools/visualization/opendx  This directory contains the OpenDX program files (.net) required to visualize APBS data with OpenDX. In particular, one can visualize single-file potential isocontours (pot.), single-file potential data mapped onto molecular surfaces (potacc.), or multiple-file potential data (multipot.).

top

Solvent accessibility

The main APBS executable calculates molecular volumes, surface areas, and other surface-based properties from PQR-format structural data. Such calculations are often used to determine apolar solvation contributions to binding events, etc. See the new APOLAR input file section for more documentation on this APBS feature. With the introduction of this new feature, we have deprecated and removed the stand-alone tools which used to perform these functions.

top

Coulomb's Law and Generalized Born calculations

top

Coulomb's Law calculations

These utilities are provided for occasional use and are definitely not optimized for speed.

The program tools/manip/coulomb calculates vacuum Coulomb law energies from a PQR file. It has a number of options which can be viewed by running the coulomb program with no arguments.

top

Generalized Born calculations

The program tools/manip/born is a crude, non-optimal, buggy program for calculating Generalized Born electrostatic energies. This is only intended for hacking and general comparison with Poisson-Boltzmann results.

The Python-based program tools/python/runGB.py is a test program designed to calculate generalized Born radii from APBS Poisson-Boltzmann calculations following the general methods of

Onufriev A, Case DA, Bashford D. Effective Born radii in the generalized Born approximation: The importance of being perfect. J Comput Chem, 23 (14), 1297-304, 2002. http://dx.doi.org/10.1002/jcc.10126

More information on this program can be obtained by running it from the command line with the –help option.

The Python-based program tools/python/readGB.py is a test program designed to use radii calculated from runGB.py (see above) and print out solvation energies. More information on this program can be obtained by running it from the command line with the –help option.

Both of these Python-based programs were written by Justin Xiang.

top

Eigenvalue analysis

If APBS is linked with ARPACK (see ./configure --help), the tools/arpack/driver routine will perform eigenvalue analyses of Poisson or Poisson-Boltzmann matrices produced by APBS.

top

Python development tools

There are a number of example Python tools and wrappers provided in the tools/python directory. These tools all make use of the APBS SWIG wrappers developed by Todd Dolinsky, Nathan Baker, Alex Gillet, and Michel Sanner. The SWIG wrappers are compiled by default during normal installation. The Python scripts which link to the wrappers (and thereby illustrate their use) include:

tools/python/main.py  Drop-in replacement for main APBS executable. Only permits sequential runs.

tools/python/noinput.py  Similar to main.py, but adds the ability to read input files and PQR files as Python strings and return energies and forces as Python lists. This makes it a very useful tool for working with APBS via Python without dealing with a great deal of file I/O.

tools/python/vgrid/  Python wrappers for Vgrid class to allow OpenDX format file I/O in Python scripts

top

Examples and tutorial

The APBS sub-directory examples contains several test systems which show how to use APBS for binding energy, solvation energy, and force calculations. The file examples/README.html contains descriptions of the test cases and links to anticipated results. Examples can be run and compared to expected results by running make test in each example directory.

Additional examples are provided as part of the APBS tutorial doc/html/tutorial/, described in more detail in the Documentation section.

top

Documentation

The APBS sub-directory doc contains guides for using APBS and developing code based on APBS libraries. The sub-directories include:

doc/html/user-guide/index.html  HTML-format User Guide

doc/html/programmer/index.html  HTML-format Programmer Guide

doc/html/tutorial/index.html  HTML-format APBS tutorial

top

Source code

The APBS sub-directory src contains the source code for the APBS libraries and main executable. These files are described in more detailed in the programming section.

top