APBS installation and availability

From APBS software documentation wiki

Contents 1 Availability 2 Binary installation 3 Source installation 3.1 Prerequisites 3.2 Tested systems 3.3 Preparation for installation 3.3.1 Compiler variables 3.3.2 Installation directories 3.3.3 Unpacking the source code 3.4 Configuring, compiling, installing, and testing 3.5 APBS directory structure 3.6 System-specific notes 3.6.1 Using an external BLAS library 3.6.2 Python support 3.6.3 Parallel support 3.6.3.1 Shared memory (OpenMP) support 3.6.3.2 Distributed memory (MPI) support 3.6.3.2.1 LAM MPI 3.6.3.2.2 MPICH1 3.6.3.2.3 MPICH2 3.6.3.2.4 OpenMPI 3.6.4 FEtk support 3.6.5 Windows 3.6.6 Macintosh

Availability

The latest version of APBS can always be found at http://www.poissonboltzmann.org/apbs. APBS is available in both source code form and binaries for a variety of architectures.

Binary installation

We currently offer binaries for the RedHat Linux platform on a variety of architectures as well as command-line binaries for WinXP and Mac OS X. Binaries can be downloaded from the APBS download page. For all other systems, please install from source on your particular platform and feel free to contact the APBS users mailing list for more help and/or to request a binary for that system.

Warning If you are using APBS on a Windows system, you may not want to install it in a directory with spaces in the path name (e.g., C:\Program Files\) as this can cause problems with some visualization programs.

APBS binaries are provided in compressed tar format (*.tgz). On most systems, the binaries can be unarchived by simply double-clicking or opening the archive. This can also be accomplished on the command line by

   gzip -dc apbs-1.0.0-XYZ.tgz | tar xvf -

where XYZ is the particular architecture of the binary you downloaded. Note that this will expand into a directory called apbs-1.0.0-XYZ. The contents of this directory can be placed anywhere on your system that you prefer (and have access to). The specific sub-directory of this archive is described in the APBS directory structure section, which contains information about the location of documentation, examples, libraries, header files, and binaries. The APBS binaries do not contain dependencies on special data files, etc. and can be moved out of this directory structure without causing any problems for APBS execution.

Source installation

If you were unable to find the binary package for your system, or would like to compile APBS yourself, you'll need to read the instructions in this section.

Prerequisites

In order to install APBS from the source code, you will need:

• C and FORTRAN compilers
• The APBS source code (see above)

It may also be useful to have:

• A version of MPI (try MPICH) for parallel jobs. However, MPI isn't strictly necessary if the async option is used.
• A vendor-supplied version of BLAS for optimal performance. APBS will attempt to locate common BLAS libraries during the configuration process; if it cannot find one, it will use a generic set of BLAS routines.

Tested systems

Source-code-based installation has been tested on the following systems

• AMD 64 (Opteron) running Fedora Core 6 Linux
• IBM Power4 running RedHat Enterprise Linux 3
• SGI Itanium2 (Altix) running IRIX/Linux
• Apple PowerPC running Mac OS X
• Apple x86_64 running Mac OS X

However, the installation procedure is rather generic and generally works on most UNIX-based systems. System-specific installation notes and caveats are provided in the System-specific notes section.

Preparation for installation

In what follows, I'll be assuming you're using bash, a shell available on most platforms (UNIX and non-UNIX). The APBS installation process does not require bash, but it's easiest for outlining the installation procedure.

Compiler variables

First, please look at the 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.

Installation directories

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 variables which point to them:

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

Unpacking the source code

You're now ready to unpack the source code:

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

Configuring, compiling, installing, and testing

Before compiling/installing APBS, you need to configure the package with the included autoconf configure script. You can examine the various configure options by running configure with the --help option. For many platforms, no options need to be specified. Therefore, most users who want single-CPU (not parallel) binaries can configure as follows:

   $ cd ${APBS_SRC}/apbs
   $ ./configure --prefix=${APBS_PREFIX}

Other configuration options, including the compilation of parallel binaries and the use of machine-specific compilers and Python usage, are discussed in the System-specific notes section.

Assuming all has gone well with the configuration (you'll generally get an error message if configuration fails), you're ready to compile

   $ make all

and install APBS:

   $ make install

For those with obsessive-compulsive tendencies, you can also test the APBS binary you just compiled against a suite of benchmark jobs by running

   $ make test

You should be able to watch the various tests pass on your platform. If they don't pass, please let us know by posting to the APBS-USERS mailing list. These tests can also be run before make install is executed.

You can test the [Opal version of APBS] separately by typing

   $ make test-opal

This follows a similar set of tests as the normal make test described above. However, because of runtime dependencies, the make test-opal command must be run after APBS has been installed (i.e. after make install has been issued).

APBS directory structure

The APBS installation process (whether compiled from source or installed as pre-compiled binaries) will create several directories under ${APBS_PREFIX}:

bin

where the main apbs binary resides

share

contains the documentation (user guide, tutorial, programmer's guide) as well as a number of examples and test cases for APBS

include

contains header files for using APBS libraries with other applications

lib

contains library files for using APBS libraries with other applications

tools

which contains a number of "helper" applications for use with APBS.

At this point you are ready to use APBS; either by calling the binary directly or adding the above directory to your path. As mentioned above, there are also several tools provided with APBS that remain in the APBS directory; these are described in later portions of this manual. You may wish to copy these to a global location (or the same place as your APBS binary) at this time.

System-specific notes

Please note: If you have tips or tricks on improving APBS performance and/or installation on your machine, let us know!

This section provides tips on compiling APBS on specific platforms and outlines some of the basic options available for parallel execution, Python linkage, etc. Note that many aspects of this section have changed from previous releases. In particular, APBS now tries to detect the optimal compilers and BLAS libraries on most systems without user intervention.

As described above, the default configure-make-install procedure is

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

The configure script includes a number of generic options to manually set default compilers, link behaviors, preprocessors, etc. These can be reviewed by running

   $ ./configure --help

Using an external BLAS library

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 for a custom BLAS library is:

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

where /path/to/blas is the the path to a directory which contains a library named libblas.a.

Python support

Core APBS functionality can also be invoked via Python for inclusion in other applications and more complicated scripting environments. Python library support is enabled at configure-time. Currently, Python libraries compile on most Linux and Mac systems. Other systems are untested. The configure-make-install procedure for enabling Python extensions is:

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

Parallel support

Starting with APBS 1.2, we now support two different types of parallel execution. Parallel focusing is still supported through the distributed memory (MPI) support that has been available since very early versions of APBS. Information on enabling distributed memory support is available below. Additionally, we have begun to add shared memory support (OpenMP) into a subset of the algorithms in APBS; this support will expand in future versions of APBS. Shared memory support is enabled by default if a supported system configuration is detected. Information on supported systems and procedures for disabling OpenMP support is provided below.

Shared memory (OpenMP) support

Sarting with APBS 1.2, we now support shared memory parallel acceleration for a subset of the algorithms in APBS, including:

• Acceleration of boundary condition evaluation
• Acceleration of the Gauss-Seidel smoothing algorithm in the multigrid cycle

This support is enabled by default if one the following compilers are identified during configuration:

• Intel icc/ifort versions greater than or equal to 10
• GNU gcc/gfortran versions greater than or equal to 4.2

On average the numerical results change by less than 0.001%. Differences are caused by a change in the Gauss-Seidel smoother in the multigrid cycle: the serial implementation has been changed to parallel red-black.

OpenMP support can be disabled by adding the --disable-openmp flag during configuration; e.g.

   $ ./configure --disable-openmp

At runtime, users can specify the number of threads to use. By default all processors/cores will be used at runtime; however, this behavior can be changed via environmental variables. For example, under bash, you can type

   export OMP_NUM_THREADS=X

in your shell prior to running APBS. In this usage, X = the number of threads. Note: It is NOT a good idea to use a number for X greater than the number of available cores on your system. However, if hyperthreading is enabled, you can try running with twice the number of cores.

Distributed memory (MPI) support

Since very early releases, APBS uses MPI for parallel focusing calculations. In general, enabling MPI support requires informing the APBS configure script about:

• MPI compiler options. For most MPI implementations, you simply need to set the CC and F77 variables to point to the MPI-savvy C and FORTRAN compilers. However, it is occasionally necessary to manually specify compiler options by setting CFLAGS, CPPFLAGS, FFLAGS, and LDFLAGS environmental variables before configuration.
• MPI library/header file locations. As outlined below, paths to the library and header files for LAM, MPICH, or Open MPI implementations of MPI can be specified with the --with-lam, --with-mpich, or --with-mpich2 configure options. Other MPI implementations will require the CFLAGS, CPPFLAGS, FFLAGS, and LDFLAGS environmental variables to be set correctly before configuration to locate the required headers and libraries.

LAM MPI

It is important that you enable FORTRAN support and use the same compilers you will use to compile APBS when installing/compiling LAM MPI. For example, if your C compiler is set in the environmental variable CC and your FORTRAN compiler is set in the environmental variable F77, then you should configure LAM with the command

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

Let MPI_PREFIX be an environmental variable pointing to the directory where LAM MPI is installed. In other words, ${MPI_PREFIX}/lib should contain the LAM MPI libraries and ${MPI_PREFIX}/include should contain the LAM MPI header files. The configure-make-install procedure is then

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

This procedure was tested with LAM MPI 7.2.1.

MPICH1

It is important that you enable FORTRAN support and use the same compilers you will use to compile APBS when installing/compiling MPICH1. For example, if your C compiler is set in the environmental variable CC and your FORTRAN compiler is set in the environmental variable F77, then you should configure MPICH1 with the command

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

where ... denotes other machine-specific options required by the MPICH compiler (e.g., --with-device=ch_p4 or --with-arch=LINUX).

Let MPI_PREFIX be an environmental variable pointing to the directory where MPICH1 is installed. In other words, ${MPI_PREFIX}/lib should contain the MPICH1 libraries and ${MPI_PREFIX}/include should contain the MPICH1 header files. The configure-make-install procedure is then

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

This procedure was tested with MPICH1 1.0.6p1.

MPICH2

It is important that you enable FORTRAN support and use the same compilers you will use to compile APBS when installing/compiling MPICH2.

Let MPI_PREFIX be an environmental variable pointing to the directory where MPICH2 is installed. In other words, ${MPI_PREFIX}/lib should contain the MPICH2 libraries and ${MPI_PREFIX}/include should contain the MPICH2 header files. The configure-make-install procedure is then

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

This procedure was tested with MPICH2 1.2.7p1.

OpenMPI

It is important that you enable FORTRAN support and use the same compilers you will use to compile APBS when installing/compiling OpenMPI.

Let MPI_PREFIX be an environmental variable pointing to the directory where OpenMPI is installed. In other words, ${MPI_PREFIX}/lib should contain the OpenMPI libraries and ${MPI_PREFIX}/include should contain the OpenMPI header files. The configure-make-install procedure is then

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

This procedure was tested with OpenMPI 1.2.8.

FEtk support

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. Note that FEtk installs library files in directories designated with the GNU "machine triplet". Therefore, 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

Windows

We provide native APBS command line binaries for Windows; these binaries are probably the best options for most Windows users.

However, 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. Good luck.

Macintosh

We provide Mac install packages for Mac OS X versions greater than 10.4. Users on Mac OS 10.3 or older will have to compile binaries for themselves - and may want to examine the apbs-users mailing list which has a number of threads which discuss installation on Mac OS platforms.

A few notes about compiling on Macintosh:

• It has become apparent from the mailing lists that some "packages" of the GNU development software available for MacOS contain different major versions of the C and FORTRAN compilers. This is very bad; APBS will not compile with different versions of the C and FORTRAN compilers. If you use GCC 4.0, for instance, gfortran 4.0 will work while g77 3.3 will not. If you see link errors involving "restFP" or "saveFP" this is most likely the cause.
• In gcc 4.0 (included in Xcode 2.0 and higher) the -fast option turns on the -fast-math flag. This flag optimizes by using rounding, and thus can lead to inaccurate results and should be avoided.
• Currently the autoconf script does not support using the native vecLib framework as an architecture-tuned BLAS replacement. In testing there were only slight timing improvements over using the MALOC-supplied BLAS.
• For older PowerPC-based systems: we have had success using IBM's XLF for Mac in conjunction with GCC 4.0, although the corresponding XLC compilers do not seem to work under Tiger.

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