APBS 1.0.0 User Guide

First, please look at Section 2.3.6, “System-specific notes” section of this document for appropriate compiler flags, etc. to be set via pre-configuration environmental variables. This section outlines generic installation procedures with default compilers and options.

There are a few directories you'll need to identify prior to installation. The first, which we'll call APBS_SRC, will contain the APBS and MALOC source code. This directory can be deleted after installation, if you wish. The second directory will be the permanent location for APBS and MALOC; we'll call this APBS_PREFIX. If you have root permission, you could pick a global directory such as /usr/local for this; otherwise, pick a directory for which you have write permission. The following commands set up the directories and environmental which point to them:

$ export APBS_SRC=/home/soft/src
$ export APBS_PREFIX=/home/soft
$ mkdir -p ${APBS_SRC} ${APBS_PREFIX}
					

You're now ready to unpack the source code:

$ cd ${APBS_SRC}
$ gzip -dc apbs-1.0.0.tar.gz | tar xvf -
					

If an optimized (vendor) BLAS library is available, it should be used with APBS since it will generally provide better performance. This can be enabled by the --with-blas=... option. The configure-make-install procedure is:

$ ./configure --with-blas='-L/path/to/blas -lblas'
$ make
$ make install
					

where /path/to/blas is the location of a library named libblas.a.

Python libraries and related tools can be enabled at configure-time. Currently, Python libraries compile on most Linux and Mac systems. Other systems are untested. The configure-make-install procedure is:

$ ./configure --enable-python --prefix=${APBS_PREFIX}
$ make 
$ make install
					

APBS uses MPI for parallel execution. In general, MPI support requires informing the APBS configure script about:

$ ./configure --prefix=${MPI_PREFIX} --with-fc=${F77}
						

$ export CC=${MPI_PREFIX}/bin/mpicc
$ export F77=${MPI_PREFIX}/bin/mpif77
$ ./configure --with-lam=${MPI_PREFIX} --prefix=${APBS_PREFIX}
$ make 
$ make install
						

$ ./configure --prefix=${MPI_PREFIX} ... --enable-f77
						

$ export CC=${MPI_PREFIX}/bin/mpicc
$ export F77=${MPI_PREFIX}/bin/mpif77
$ ./configure --with-mpich=${MPI_PREFIX} --prefix=${APBS_PREFIX}
$ make 
$ make install
						

$ export CC=${MPI_PREFIX}/bin/mpicc
$ export F77=${MPI_PREFIX}/bin/mpif77
$ ./configure --with-mpich2=${MPI_PREFIX} --prefix=${APBS_PREFIX}
$ make 
$ make install
						

In order to enable support for the finite element features in APBS, you must compile it against the FEtk libraries. Please use the same compilers for both APBS and FEtk. Let ${FETK_PREFIX} be an environmental variable pointing to the directory where FEtk was installed. In other words, ${FETK_PREFIX}/lib should contain the FEtk machine-specific library directories and ${FETK_PREFIX}/include should contain the FEtk header files. You'll first need to identify the appropriate library directory for your system in ${FETK_PREFIX}/lib. For the purposes of this example, let's suppose this directory is ${FETK_PREFIX}/lib/x86_64-unknown-linux-gnu. The configure-make-install procedure for APBS is then

$ ./configure --with-fetk-include=${FETK_PREFIX}/include --with-fetk-library=${FETK_PREFIX}/lib/x86_64-unknown-linux-gnu --prefix=${APBS_PREFIX}
$ make 
$ make install
					

We are happy to now provide native APBS command line binaries for Windows. The binary is probably the best option available, but if you would still like to compile your own binaries you will need to use either the Cygwin or MinGW environments. Binaries compiled under Cygwin tend to require Cygwin DLLs and thus can only be run on systems with Cygwin. Performance for the Windows binaries and all compiled systems will be fairly mediocre as they depend on the GNU compilers.

If you do choose to use Cygwin and compile your own code, compilation should be rather straightforward.

We are happy to now provide a Mac install package for Mac OS 10.4 (Tiger). Unfortunately this is the only binary for Mac that we have available, so users on OS 10.3 may have to compile binaries for themselves - you may want to examine the apbs-users mailing list which has a number of threads which discuss installation on Mac OS platforms. Alternatively you can try using Fink for the installation - please see Bill Scott's excellent guidelines at http://chemistry.ucsc.edu/~wgscott/xtal.

A few notes about compiling on Macintosh:

Finally, Dave Gohara has prepared a nice tutorial on building APBS from within Xcode to take advantage of its development and debugging features.

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.

The program tools/manip/born is a crude, non-optimal, buggy program (are you still reading?!?) 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.

This automatically sets up and performs a string of single-point PBE calculations to "focus" on a region of interest (binding site, etc.) in a system. It is basically an automated version of mg-manual designed for easier use. Most users should probably use this version of ELEC.

The keywords for this command (described in more detail in the Keywords section) are listed below. All keywords are required (no default values!) unless otherwise noted: dime , cglen , fglen , cgcent , fgcent , mol , lpbe or npbe or smpbe , bcfl , ion (optional) , pdie , sdie , chgm , usemap (optional) , useaqua (optional) , sdens , srfm , srad , swin , temp , calcenergy , calcforce , write , writemat

This calculation closely resembles mg-auto in syntax. However, it is basically designed to perform single-point calculations on systems in a parallel focusing fashion. While this method does provide support for decreasing the domain size from a coarse (large) global grid to a fine (smaller) global grid, it should not be used to look at subsets of biomolecules such as titration sites, etc. Such subset calculations require more complicated energy evaluation which is not yet supported by mg-para. However, since parallel focusing was designed to provide detailed evaluation of the electrostatic potential on a large scale, such subset calculations are better left to traditional focusing via the mg-auto keyword.

	Important
	Please note that some of the parameters change in meaning a bit for this type of calculation. In particular, dime should be interpreted as the number of grid points per processor. This interpretation helps manage the amount of memory per-processor -- generally the limiting resource for most calculations.

The keywords for this command (described in more detail in the Keywords section) are listed below. All keywords are required (no default values!) unless otherwise noted: dime , ofrac , pdime , async , cglen , fglen , cgcent , fgcent , mol , lpbe or npbe or smpbe , bcfl , ion (optional) , pdie , sdie , chgm , usemap (optional) , useaqua (optional) , sdens , srfm , srad , swin , temp , calcenergy , calcforce , write , writemat

This is the standard single-point PBE calculation performed by most solvers. The mg-manual calculation offers the most control of parameters to the user. Several of these calculations can be strung together to perform focusing calculations by judicious choice of the bcfl flag, however, the setup of the focusing is not automated as it is in mg-auto and mg-para calculations and therefore this command should only be used by more experienced users.

The keywords for this command (described in more detail in the Keywords section) are listed below. All keywords are required (no default values!) unless otherwise noted: dime , nlev , glen or grid , gcent , mol , lpbe or npbe or smpbe , bcfl , ion (optional) , pdie , sdie , chgm , usemap (optional) , useaqua (optional) , sdens , srfm , srad , swin , temp , calcenergy , calcforce , write , writemat

This is a single-point PBE calculation performed by our adaptive finite element PBE solver. It requires that APBS was linked to the Holst group FEtk finite element library (http://www.fetk.org) during compilation.

The finite element solver uses a "solve-estimate-refine" cycle. Specifically, starting from an initial mesh, it performs the following iteration:

until a global error tolerance is reached.

	Note
	These methods are most useful for a select set of problems which can benefit from adaptive refinement of the solution. Furthermore, this implementation is experimental. In general, the sequential and parallel focusing multigrid methods offer the most efficient solution of the PBE for most systems

The keywords for this command (described in more detail in the Keywords section) are listed below. All keywords are required (no default values!) unless otherwise noted: domainLength , usemesh (optional) , etol , ekey , akeyPRE , akeySOLVE , targetNum , targetRes , maxsolve , maxvert , mol , lpbe or npbe or lrpbe or nrpbe , bcfl , ion (optional) , pdie , sdie , chgm , usemap (optional) , useaqua (optional) , sdens , srfm , srad , swin , temp , calcenergy , calcforce , write , writemat

This allows users to write out dielectric, ion-accessibility, and charge distribution maps based on biomolecular geometry without actually solving the PB equation. The syntax is identical to mg-dummy.

The keywords for this command (described in more detail in the Keywords section) are listed below. All keywords are required (no default values!) unless otherwise noted: dime , nlev , cglen or grid , gcent , mol , lpbe or npbe or smpbe , bcfl , ion (optional) , pdie , sdie , chgm , usemap (optional) , useaqua (optional) , sdens , srfm , srad , swin , temp , calcenergy , calcforce , write , writemat

This is a list of keywords used in the ELEC statements of APBS. Note that not all keywords are used in every ELEC statement; see above.