Copyright (c) 1999-2002. Nathan A. Baker. All Rights Reserved.
Permission to use, copy, modify, and distribute this software and its documentation for educational, research, and not-for-profit purposes, without fee and without a signed licensing agreement, is hereby granted, provided that the above copyright notice, this paragraph and the following two paragraphs appear in all copies, modifications, and distributions.
IN NO EVENT SHALL THE AUTHORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE AUTHORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS PROVIDED "AS IS". THE AUTHORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
APBS was primarily written by Nathan Baker during his graduate work with J. Andrew McCammon and Michael Holst. APBS relies several libraries written by Mike Holst and members of the Holst group. These include PMG (multigrid solver for Cartesian mesh discretization), FEtk (provides finite element framework, error estimators, and solvers), and MALOC (hardware abstraction library for code portability).
Please acknowledge your use of APBS by citing: N. A. Baker, D. Sept, S. Joseph, M. J. Holst, J. A. McCammon. Electrostatics of nanosystems: application to microtubules and the ribosome. Proc. Natl. Acad. Sci. USA 98, 10037-10041, 2001. (Link to paper)
This version of the APBS code contains sequential and parallel fast multigrid Poisson-Boltzmann solver. Subsequent releases will include adaptive finite element technology. This release is primarily intended to allow users to get familiar with the code and break it. Before going too much farther in this guide, please view the License.
Prerequisites:
You will definitely need
Directories: These instructions will assume a local (home directory, etc.) installation of APBS. It may also be worthwhile to check out Machine-specific notes prior to starting the installation.
/home/nbaker/pbe. Using a Bourne-like shell (bash or sh), do:
# mkdir -p /home/nbaker/pbe /home/nbaker/pbe/dist
# TOP=/home/nbaker/pbe; export TOP
# FETK_INCLUDE=${TOP}/dist/include; export FETK_INCLUDE
# FETK_LIBRARY=${TOP}/dist/lib; export FETK_LIBRARY
or, using a C-shell-like shell (csh or tcsh), do
# mkdir -p /home/nbaker/pbe /home/nbaker/pbe/dist
# setenv TOP /home/nbaker/pbe
# setenv FETK_INCLUDE ${TOP}/dist/include
# setenv FETK_LIBRARY ${TOP}/dist/lib
The dist subdirectory will be used to store header files and libraries for APBS and MALOC.S
If you're planning on using MPI, you'll also need to set some additional environmental variables. The variable FETK_MPI_INCLUDE points to the directory where the MPI header files reside (mpi.h) and the variable FETK_MPI_LIBRARY gives the directory with the MPI libraries (either libmpi.a or libmpich.a). These variables need to be defined using commands like
# FETK_MPI_INCLUDE=/usr/share/mpi/include; export FETK_MPI_INCLUDE # FETK_MPI_LIBRARY=/usr/share/mpi/lib; export FETK_MPI_LIBRARYfor a Bourne-like shell and
# setenv FETK_MPI_INCLUDE /usr/share/mpi/include # setenv FETK_MPI_LIBRARY /usr/share/mpi/libfor a C-shell type of environment. Note that the paths given in the above example are system-dependent; your variable definitions will likely be different.
# cd ${TOP}
# gzip -dc maloc.tar.gz | tar xvf -
# gzip -dc apbs-0.2.1.tar.gz | tar xvf -
# cd ${TOP}/maloc
If you are not starting from a clean distribution (i.e., the tar file), you need to run make distclean now (and ignore any error messages). There are two common installation options that APBS users will need to choose from:
# ./configure --prefix=${TOP}/dist
# make
# make install
# ./configure --prefix=${TOP}/dist --enable-mpi
# make
# make install
Be sure to watch the output of the configure script for MPI-related issues; specifically, both mpi.h and libmpi.h or libmpich.a should be found. ${TOP}/dist.
# cd ${TOP}/apbs
If you are not starting from a clean distribution (i.e., the tar file), you need to run make distclean now (and ignore any error messages).
# ./configure --prefix=${TOP}/dist
# make
# make install
<font color="red">If you have vendor-supplied BLAS libraries for your platform, set the environmental variable BLASPATHto their location and use them with APBS by inkoving the
--with-blas=${BLASPATH} flag during configurationa.</font> ${TOP}/dist/bin/${triplet} directory, # make distcleanin the APBS or MALOC package directories and repeat the installation process.
Machine-specific notes Of course, every machine seems to behave a bit differently. Here are a few notes; if you encounter interesting configuration/compilation behavior, please let me know.
CC="gcc -O3 -ffast-math -m486 -funroll-loops"or, preferably, replace the GNU compilers with the Intel C and FORTRAN compilers.
CC="mpcc -bmaxdata:0x???????? -bmaxstack:0x10000000 \
-L/usr/local/apps/mass -lmass -O3 -qstrict \
-qarch=pwr3 -qtune=pwr3 -qmaxmem=-1 -qcache=auto"
Note that the actual command line declaration should contain no line breaks and continuations; these seem to screw up sed (used by configure) under AIX. The bmaxdata linker flag controls the amount of heap the program is allocated to allocate. It is a hexadecimal number representing the number of bytes available. The NPACI documentation suggests 0x80000000, which gives 2048 MB of heap space. While the Blue Horizon nodes do have 8 GB of memory available per 8-processor node, much of this is taken up by the OS. In practice, for 8 tasks per node, about 400 MB of heap space is available to each task (this means OS-related tasks take up nearly 5 GB of memory!) . In any case, -bmaxdata:0x18000000 seems to be a safe choice as it provides 384 MB heap space per task. The use of vendor-supplied BLAS is also recommended!
CC='ccc'; export CC
CXX='cxx'; export CXX
F77='fort'; export F77
It's also worthwhile to add the '-arch' flag.
Main executable
Right now, there is only one executable (${TOP}/dist/bin/${prefix}/apbs) for APBS, where ${TOP} is the top-level install directory (see Installation section) and ${prefix} is a machine/compiler/os-specific string to facilitate compilation across multiple platforms. The executable invoked with the syntax
apbs input-path;
where input-path is the path to a specially formatted input file (see Using the APBS executable for more information on the input file). Besides the output files specified in input-path (i.e., for visualization), APBS writes output to three places: io.mc (or io.mc_# for parallel runs, where # is the processor ID). This gives you detailed information about the progress of the run and is especially useful for monitoring the solver step of the calculation.
Test systems and examples
The directory apbs/examples contains several test systems and example scripts which show how to use APBS for binding energy, solvation energy, and force calculations. The file apbs/examples/README.html contains descriptions of the test cases as well as anticipated results.
Tools, scripts, and parameters
The apbs/tools directory contains several (hopefully) useful accessories for working with APBS:
gridcalc utility; run code with no arguments for instructions.
\section example-code
There is a more concise source-code-only driver for APBS in test/mg that should provide a starting point for those who wish to integrate APBS into their own applications. Such users should also become familiar with the APBS Programmer's Guide.
The only executable for APBS is located at ${TOP}/dist/bin/${triplet}/apbs, where ${TOP} is the top-level install directory (see Installation section) and ${triplet} is a machine-specific directory that allows the installation of multiple architechtures in the same directory. The executable is invoked as
apbs input-pathwhere
input-path is the path to a specially formatted input file. The syntax of this input file closely resembles UHBD input with a few significant changes and additions. Input is divided into sections of the form
READ
....
END
ELEC
....
END
PRINT
....
END
QUIT
where READ, ELEC, and PRINT designate the start of specific sections. Each section is ended by the END keyword and the entire input file is terminated by the QUIT keyword. The sections/commands currently available are: READ: Read in molecules ELEC: Perform electrostatics calculations (solve the PBE, calculate energies and forces, etc.) PRINT: Do some simple arithmetic on some of the properties calculated in other sections. PRINT requires ELEC and ELEC requires one or more READ sections. Sections can also be repeated; several READ statements may be used to load molecules and multiple ELEC sections would specify various electrostatics calculations on one or more molecules.
READ statements
One of these sections must be present for every molecule involved in the APBS calculation. Molecule and "map" IDs are assigned implicitly assigned for each molecule/map read, based on order and starting at 1. The sections have the following keywords:
mol format path pqr. The molecule file is in PQR format, which has the form
ATOM7d 4s4s5d lflflflflf
(note: there are no chain IDs) the columns are
)
)
)
) apbs/tools/conversion directory, and the Tools, scripts, and parameters section above for scripts to convert PDB files into PQR format. diel format path-x path-y path-z
mapped to a Cartesian mesh. The result is a map of values between the solvent and biomolecular dielectric constants. The values in this file have no units. Acceptable format keywords include: dx for OpenDX format kappa format path
map from the file path. The values in this file have units of
. Acceptable format keywords include: dx for OpenDX format charge format path e_c, the electron charge (i.e., they are unitless). Acceptable format keywords include: dx for OpenDX format
This section is the main component of all APBS runs. There may be several ELEC sections, operating on different molecules or using different parameters for multiple runs on the same molecule. Each of the ELEC sections begins with one of the following keywords:
mg-auto for automatically configured multigrid focusing calculations. 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.
mg-para for automatically configured multigrid parallel focusing calculations. 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, <font color="red">it should not be used to look at subsets of biomolecules such as titration sites, etc</font>. 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.
mg-manual for manually configured multigrid calculations. 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 calculations and parallel focusing (i.e., mg-para) is very difficult with this keyword. This is intended for more experienced users.
mg-dummy has exactly the same syntax as mg-manual, but simply sets up the problem and skips the solver step. This is useful for setting up charge, dielectric, etc. grids for use in other runs.
fem for adaptive finite element calculations. This function will not be (publically) available until the release of the Holst group's FEtk software package.
Manual multigrid calculation syntax (mg-manual)
This section always has the form
elec mg-manual ... endwhere the
... denotes the various parameter keywords listed below. To avoid confusion during run-time, there are no default parameter values. Therefore, unless otherwise indicated, all of the following keywords should be specified:
Automatic multigrid focusing calculation syntax (mg-auto)
This section always has the form
elec mg-auto ... endwhere the
... denotes the various parameter keywords listed below. This form of multigrid calculations is most useful for focusing; the user simply provides information about the coarsest and finest meshes desired and the code sets up the rest, including number of focusing levels, centers, dimensions, etc.
Automatic multigrid parallel focusing calculation syntax (mg-para)
PLEASE NOTE: In versions 0.2.1 and earlier, parallel focusing should not be used for energy calculations if the fine grid does not completely contain all atoms of interest!
This section always has the form
elec mg-para ... endwhere the
... denotes the various parameter keywords listed below. This form of multigrid calculations is most useful for focusing; the user simply provides information about the coarsest and finest meshes desired and the code sets up the rest, including number of focusing levels, centers, dimensions, etc.nlev keyword by the formula nx = c * 2^(l+1) + 1, where c is an integer. Use the program
apbs/tools/mesh/mgmesh to find the correct values of nx, ny, and nz. The most common values are 65, 97, and 161 (can be different in each direction); these are all compatible with nlev 4. If you happen to pick an "bad" value for the dimensions (i.e., mismatch with nlev), the code will adjust the specified dime to more appropriate values.
dime keyword; see discussion.
mol id | xcent ycent zcent} grid mol is used, * id must be the ID of a molecule read in a previous READ section. Molecule IDs are assigned in the order they're read, starting at 1. If just grid is used, the next three numbers should be the x, y, and z coordinates for the center of the grid.
). Several of these keywords can be present to describe a variety of ionic species in solution. Varying ion valencies and concetrations are taken into account in the mobile ion PBE term, however, only the largest ionic radius is used to determine the ion accessibility function.
) is defined using inflated van der Waals radii, the dielectric coefficient (
) is defined using the molecular (Conolly) surface definition without smoothing.
) is defined using inflated van der Waals radii, the dielectric coefficient (
) is defined using the molecular (Conolly) surface definition with a simple harmonic average smoothing.
) is defined using inflated van der Waals radii with the spline function and the dielectric coefficient (
) is defined using the standard van der Waals radii with the spline function.
diel
) -- this causes the srad parameter and the radii/location of atoms in the PQR file to be ignored kappa
) -- this causes the ion radius parameter to be ignored charge
) used to define molecular surfaces. Typically 1.4
(water).
) used to define surface-based properties. Typically 0.3
.
. <font color="red">This parameter is only used if forces are calculated but still must be present for other calculations.</font>
charge Write out the biomolecular charge distribution in units of e pot Write out potential in units of kT/e smol Write out solvent accessibility defined by molecular/Connolly surface definition (1 = accessible, 0 = inaccessible) sspl Write out spline-based solvent accessibility (1 = accessible, 0 = inaccessible) vdw Write out van der Waals-based accessibility (1 = accessible, 0 = inaccessible) ivdw Write out ion accessibility/inflated van der Waals (1 = accessible, 0 = inaccessible) lap Write out Laplacian of potential (kT/e/
) edens Write out energy density
, where
is potential
ndens Write out ion number density
, where
is potential (output in M) qdens Write out ion charge density
, where
is potential (output in e_c M) dielx Write out the x-shifted dielectric map of the dielectric function
for use in subsequent calculations (see read diel (unitless) diely Write out the y-shifted dielectric map of the dielectric function
for use in subsequent calculations (see read diel (unitless) dielz Write out the z-shifted dielectric map of the dielectric function
for use in subsequent calculations (see read diel (unitless) kappa Write out the map of the function
for use in subsequent calculations (see read kappa (units of
) dx for OpenDX format, avs for AVS UCD format, uhbd for UHBD format.
poisson Write out the operator
corresponding to Poisson's equation.
full Write out the linearization (functional derivative) of the full non-linear Poisson-Boltzmann operator
around the current solution
.
); may be different in each direction.
); may be different in each direction.
mol id | xcent ycent zcent} grid mol is used, id must be the ID of a molecule read in a previous READ section. Molecule IDs are assigned in the order they're read, starting at 1. If just grid is used, the next three numbers should be the x, y, and z coordinates for the center of the grid.
mol id | xcent ycent zcent} grid mol is used, id must be the ID of a molecule read in a previous READ section. Molecule IDs are assigned in the order they're read, starting at 1. If just grid is used, the next three numbers should be the x, y, and z coordinates for the center of the grid.
pdime npx npy npz
ofrac fraction
This is a very simple section that allows linear combinations of calculated properties to be written to standard output. It has the format print keyword id op id op id ... end where spaces are important and the components are
energy print energy 3 - 2 - 1 endand be interpreted as "subtract the energy from ELEC statements #1 and #2 from the energy in ELEC statement #3" (i.e., a binding energy calculation).
NOTE: It is important to realize that, in the case of automatic focusing (mg-auto), PRINT works using ELEC statement numbers, not the calculation numbers which appear while APBS is running.
The following is a list of some of the bugs in APBS, a list of bugs in specific functions can be found here.
srfm 0, 1) for dielectric assignment, the accessibility evaluation routines slow the problem setup down considerably; especially during focusing. This is essentially a trade-off with being able to handle very large molecules. We don't ever assemble the Shrake and Rupley solvent-accessible surface due to the possiblity of this being very large for very large molecules. However, such a surface would allow us to build up the accessibility maps in O(number of atoms) time rather than O(number of grid points) time.
Problems can be reported to the APBS User mailing list at apbs-users@mccammon.ucsd.edu. To subscribe, simply send an e-mail to majordomo@mccammon.ucsd.edu with the body
subscribe apbs-users
However, while the code is in beta, you should also e-mail the problem to nbaker@wasabi.ucsd.edu.
More detailed information about APBS can be found in the following papers:
This documentation provides information about the programming interface provided by the APBS software and a general guide to linking to the APBS libraries. Information about installation, configuration, and general usage can be found in the User's Guide.
APBS was primarily written by Nathan Baker during his graduate work with J. Andrew McCammon and Michael Holst. APBS relies several libraries written by Mike Holst and members of the Holst group. These include PMG (multigrid solver for Cartesian mesh discretization), FEtk (provides finite element framework, error estimators, and solvers), and MALOC (hardware abstraction library for code portability).
Please acknowledge your use of APBS by citing N. A. Baker, D. Sept, S. Joseph, M. J. Holst, J. A. McCammon. Electrostatics of nanosystems: application to microtubules and the ribosome. Proc. Natl. Acad. Sci. USA 98, 10037-10041 2001.
APBS was developed following the Clean OO C style of Mike Holst. In short, Clean OO C code is written in a object-oriented, ISO C-compliant fashion, and can be compiled with either a C or C++ compiler.
Following this formalism, all public data is enclosed in structures which resemble C++ classes. These structures and member functions are then declared in a public header file which provides a concise description of the interface for the class. Private functions and data are included in private header files (or simply the source code files themselves) which are not distributed. When using the library, the end-user only sees the public header file and the compiled library and is therefore (hopefully) oblivious to the private members and functions. Each class is also equipped with a constructor and destructor function which is responsible for allocating and freeing any memory required by the instatiated objects.
As mentioned above, public data members are enclosed in C structures which are visible to the end-user. Public member functions are generated by mangling the class and function names and passing a pointer to the object on which the member function is supposed to act. For example, a public member function with the C++ declaration
public double Foo::bar(int i, double d)would be declared as
double Foo_bar(Foo *thee, int i, double d)where
VEXTERNC is a compiler-dependent macro, the underscore _ replaces the C++ double-colon ::, and thee replaces the this variable implicit in all C++ classes. Since they do not appear in public header files, private functions could be declared in any format pleasing to the user, however, the above declaration convention should generally be used for both public and private functions. Within the source code, the public and private function declarations/definitions are prefaced by the macros VPUBLIC and VPRIVATE, respectively. These are macros which reduce global name pollution, similar to encapsulating private data withing C++ classes.
The only C++ functions not explicitly covered by the above declaration scheme are the constructors (used to allocate and initialize class data members) and destructors (used to free allocated memory). These are declared in the following fashion: a constructor with the C++ declaration
public void Foo::Foo(int i, double d)
would be declared as
Foo* Foo_ctor(int i, double d)
which returns a pointer to the newly constructed Foo object. Likewise, a destructor declared as
public void Foo::~Foo()
in C++ would be
void Foo_dtor(Foo **thee)
in Clean OO C.
Finally, inline functions in C++ are simply treated as macros in Clean OO C and declared/defined using define statements in the public header file.
See any of the APBS header files for more information on Clean OO C programming styles.
Application programming interface documentation
The API documentation for this code was generated by doxygen. You can either view the API documentation by using the links at the top of this page, or the slight re-worded/re-interpreted list below:
1.2.8.1 written by Dimitri van Heesch,
© 1997-2001