iAPBS/Amber Interface: User Guide

1. Introduction

The Amber/APBS interface makes most of the APBS functionality available to Amber users. The APBS interface in sander is accessible through the &apbs keyword. Additionally, the igb keyword must be set to 6. This combination of keywords means that a calculation will be performed on the given system in vacuum and then APBS calculated solvation energies and forces will be added to the total energy and forces.

In addition to minimization and molecular dynamics simulation with APBS calculated implicit solvent contribution the Amber/APBS module can write out calculated electrostatic potential to a file. This file can be visualized using third party applications, including VMD, Pymol, PMV/Vision and OpenDX.

The current version of the Amber/APBS module supports serial execution only. Parallel capability will be added in later versions.

2. Installing the iAPBS Interface

2.1. Requirements

To compile iAPBS/Amber interface two packages are required:

APBS (version 1.5.0 or later).
Amber (version 16 or later)

2.2. Building iAPBS interface

Building of the iAPBS interface requires compilation and installation of MALOC and APBS libraries. The following describes all steps (assumes bash as login script, modify appropriately for t/csh). The instructions also assume working gcc/gfortran compilers. The use of Intel compilers is recomended for better performance of the compiled executables.

# create a build directory and cd to it, then:
export APBS_PREFIX=`pwd`
export APBSHOME=$APBS_PREFIX/apbs
export APBS_SRC=$APBS_PREFIX/apbs-pdb2pqr/apbs
export MCSH_HOME=/dev/null

# get the source
git clone https://github.com/Electrostatics/apbs-pdb2pqr
cd apbs-pdb2pqr
git submodule init
git submodule update

# configure and build it
cd $APBS_PREFIX
mkdir build.apbs && cd $_
cmake -DCMAKE_INSTALL_PREFIX=$APBSHOME \
 -DCMAKE_BUILD_TYPE=Release \
 -DBUILD_DOC=OFF \
 -DBUILD_SHARED_LIBS=OFF \
 -DENABLE_QUIET=ON \
 -DENABLE_iAPBS=ON \
 $APBS_SRC

make install

These steps should build the apbs executable in ${APBSHOME}/bin and all the necessary apbs and iapbs libraries in ${APBSHOME}/lib.

2.3. Building of Amber/APBS module

The Amber/APBS module is supported on the x86_64 Linux platform only.

# unpack your Amber and Amber Tools source code in
# ${APBS_PREFIX}/amber (or use a symlink), then:

export AMBERHOME=$APBS_PREFIX/amber.apbs
export AMBER_SRC=$APBS_PREFIX/amber

cd $APBS_PREFIX
mkdir build.amber && cd $_
cmake3 -DCMAKE_INSTALL_PREFIX=$AMBERHOME \
       -DCOMPILER=GNU \
       -DMPI=FALSE \
       -DCUDA=FALSE \
       -DBUILD_PYTHON=FALSE \
       -DDOWNLOAD_MINICONDA=FALSE \
       -DBUILD_GUI=FALSE \
       -DCHECK_UPDATES=FALSE \
       -DINSTALL_TESTS=TRUE \
       -DBUILD_SANDER_APBS=TRUE \
       -DPRINT_PACKAGING_REPORT=TRUE \
       -DCMAKE_PREFIX_PATH=$APBSHOME \
       $AMBER_SRC

make -j 16 # or how many CPU cores you have available
make install

# And test it:

export TESTsander=${AMBERHOME}/bin/sander.APBS
cd ${AMBERHOME}/test/iapbs_radi
./Run.ion.min

This builds the sander.APBS binary in $AMBERHOME/bin directory.

Instructions for Amber 18 or earlier:

# unpack your Amber and Amber Tools source code in
# ${APBS_PREFIX}/amber (or use a symlink), then:

cd $APBS_PREFIX
export AMBERHOME=${APBS_PREFIX}/amber
cd $AMBERHOME
./configure -noX11 --skip-python gnu
make install

cd ${AMBERHOME}/AmberTools/src/sander
export APBS_LIBDIR=${APBS_PREFIX}/lib
export APBS_LIBS="-liapbs -lapbs_routines -lapbs_mg -lapbs_generic -lapbs_pmgc -lmaloc -lz"
make clean
make depend
make -e AMBERBUILDFLAGS="-DAPBS" ${AMBERHOME}/bin/sander.APBS

# test it
export TESTsander=${AMBERHOME}/bin/sander.APBS
cd ${AMBERHOME}/test/iapbs_radi
./Run.ion.min

3. Using sander.APBS

The APBS module in sander offers an alternative to the built-in PB sander module. The APBS module can be used for example for implicit solvent minimization and dynamics, calculation and visualization of miscellaneous electrostatic biomolecular properties. Please see the Examples section of this User’s Guide.

The following table lists all Amber/APBS keywords with their description. The left side of the table also lists corresponding APBS keywords which Amber/APBS keywords mimic very closely. For detailed discussion of APBS keywords please see APBS documentation.

3.1. APBS and sander.APBS keyword description

Table 1. APBS and sander.APBS input parameters
APBS	Amber/APBS	Description
	apbs	Enters the APBS module
mg-auto/mg-para	calc_type [1]	0: manual MG; 1: autoMG; 2: parallel MG
lpbe/nbpe	nonlin [0]	Linear/full Poisson-Boltzmann equation: 0: linear; 1: non-linear; 4: size-dependent PBE
bcfl	bcfl [1]	Boundary condition method: 0: zero; 1: sdh; 2: mdh; 4: focus
srfm	srfm [2]	Surface calculation method: 0: mol; 1: smol; 2: spl2; 3: spl4
pdie	pdie [2.0]	Solute dielectric
sdie	sdie [78.4]	Solvent dielectric
sdens	sdens [10.0]	Vacc sphere density
srad	srad [1.4]	Solvent radius
swin	swin [0.3]	Cubic spline window
temp	temp [298.15]	Temperature (in K)
gamma	gamma [0.105]	Surface tension for apolar energies/forces (in kJ/mol/A²)
chgm	chgm [1]	Charge discretization method: 0: spl0; 1: spl2; 2: spl4
vol	smvolume	The parameter smvolume controls the lattice size (in Angstroms³) used in the SMPBE formalism.
size	smsize	The parameter smsize controls the relative size of the ions (in Angstroms) such that each lattice site can contain a single ion of volume radius³ or size ions of volume radius³/size.
calcenergy	calcenergy [2]	Energy calculation flag: 0: Do not perform energy calculation; 1: Calculate total energy only; 2: Calculate per-atom energy components
calcforce	calcforce [2]	Atomic forces calculation: 0: Do not perform force calculation; 1: Calculate total force only; 2: Calculate per-atom force components
write pot	wpot	Writes electrostatic potential data to iapbs-pot.dx in DX format
write charge	wchg	Writes charge data to iapbs-charge.dx in DX format
write smol	wsmol	Writes molecular surface data to iapbs-smol.dx in DX format
write kappa	wkappa	Writes the ion-accessibility kappa map to iapbs-kappa.dx in DX format
write diel	wdiel	Writes dielectric maps to iapbs-diel[x,y,z].dx in DX format
read charge	rchg	Reads charge data from iapbs-charge.dx in DX format
read kappa	rkappa	Reads the ion-accessibility kappa map from iapbs-kappa.dx in DX format
read diel	rdiel	Reads dielectric maps from iapbs-diel[x,y,z].dx in DX format
	nion	Number of counterions
ionq	ionq	Counterion charges (in e)
ionc	ionc	Counterion concentrations (in M)
ionr	ionrr	Counterion radii (in A)
dime	dime	Grid dimensions (in x, y and z)
cmeth	cmeth [1]	Centering method: 0: Center on a point 1: Center on a molecule
gcent	center	Grid center if cmeth=0
ccmeth	ccmeth [1]	Coarse grid centering method: 0: Center on a point 1: Center on a molecule
cgcent	ccenter	Coarse grid center if ccmeth=0
fcmeth	fcmeth [1]	Fine grid centering method: 0: Center on a point 1: Center on a molecule
fgcent	fcenter	Fine grid center if fcmeth=0
grid	grid	Grid spacings
glen	glen	Grid side lengths
cglen	cglen	Coarse grid side lengths
fglen	fglen	Fine grid side lengths
pdime	pdime	Grid of processors to be used in calculation
ofrac	ofrac [0.1]	Overlap fraction between processors
	radiopt [0]	Radii optimization: 0: use prmtop for both charge and radius; 1: read charge and radius information from `pbparamsin` file (format: atom_label charge radius); 2: Read charge/radius information from a PQR file; 3: Read radius information from a PQR file.
	pqr	PQR file name. Used with conjuction with the `radiopt` option
	calcnpenergy [1]	Calculate nonpolar energy [0, 1]. 0: Don’t calculate; 1: SASA-based apolar energy caclulation.
	calcnpforce [2]	Calculate nonpolar forces [0, 1, 2]. 0: Do not perform force calculation; 1: Calculate total force only; 2: Calculate per-atom force components
	apbs_print [1]	Verbosity of the output
	apbs_debug [0]	Debugging flag
	sp_apbs [.FALSE.]	Perform a single point (a single electrostatic evaluation) APBS calculation

Notes

Values in square brackets [] are defaults. For up-to-date default values please see $AMBERHOME/src/sander/apbs.F90
To disable creation of io.mc file before attempting any extensive minimization or MD simulation with the APBS module please set the MCSH_HOME environment variable to /dev/null (export MCSH_HOME=/dev/null).

4. Examples of using sander.APBS

The APBS module is initialized when &apbs keyword is encountered in the input file. Also, igb must be set to 6 in the &cntrl section. The &apbs keyword can be then followed by additional apbs keywords, for details see Amber/APBS keywords.

4.1. Solvation energy calculation

This example executes a solvation energy calculation and prints out total solvation energy for the given molecule (in energy terms EPB and ENPOLAR for polar and non-polar solvation terms, respectively).

 iAPBS solvation energy example
 &cntrl
   maxcyc=0, imin=1,
   cut=12.0,
   igb=6, ntb=0,
   ntpr=1,
 /
 &apbs
    apbs_print=1
    grid=0.5, 0.5, 0.5,
    calc_type=0, cmeth=1,
    bcfl=2, srfm=1, chgm=1,
    pdie=1.0, sdie=78.54,
    srad = 1.4,
    nion=2,
    ionq  = 1.0, -1.0,
    ionc  = 0.15, 0.15,
    ionrr = 2.0, 2.0,
    radiopt = 3, pqr = 'my.pqr',
    calcforce=0, calcnpenergy=1,
 &end

4.2. Electrostatic energy calculation

This example executes a single point electrostatic energy calculation and prints out the calculated energy (in energy terms EPB and ENPOLAR for polar and non-polar terms, respectively).

 APBS electrostatic energy example
 &cntrl
   maxcyc=0, imin=1,
   cut=12.0,
   igb=6, ntb=0,
   ntpr=1,
 /
 &apbs
    apbs_print=1
    grid = 0.1, 0.5, 0.5,
    calc_type=0, cmeth=1,
    sp_apbs=.true.,
 &end

4.3. Molecular dynamics in implicit solvent using APBS

This examples shows how to use the Amber/APBS module for carrying out a molecular dynamics simulation in implicit solvent with APBS.

Example of APBS implicit solvent dynamics
&cntrl
 ntx=1, irest=0, imin=0,
 ntpr=10, ntwx=500, nscm=100, ntwr=5000,
 dt=0.001, nstlim=50,
 temp0=300, tempi=0, ntt=1, tautp=0.1,
 igb=6, cut=12.0, ntb=0,
 ntc=2, ntf=2, tol=0.000001
/
 &apbs
    apbs_print=0,
    grid = 0.5, 0.5, 0.5,
    calc_type=0,
    cmeth=1,
    bcfl=2, srfm=2, chgm=1,
    pdie=2.0, sdie=78.54,
    radiopt=2, pqr='my.pqr',
    calcforce=2, calcnpenergy=1,
    nion=2,
    ionq  = 1.0, -1.0,
    ionc  = 0.15, 0.15,
    ionrr = 2.0, 2.0,
 &end

4.4. Calculation and visualization of electrostatic potential

When this input file is run three DX files will be created. These can be visualized using several applications (for details please see APBS visualization guide). The DX files will be iapbs-pot.dx, iapbs-smol.dx and iapbs-charge.dx which will contain electrostatic potential, solvent accessible surface and charge information, respectively.

 APBS visualization example
 &cntrl
   maxcyc=0, imin=1,
   cut=12.0,
   igb=6, ntb=0
   ntpr=1,
 /
 &apbs
    apbs_print=1,
    grid= 0.5, 0.5, 0.5,
    calc_type = 0,
    srad = 0.7,
    wpot = 1, wchg = 1, wsmol =1,
    sp_apbs=.true.,
 &end

Notes

To determine the correct size of the numerical grid enveloping the studied molecule (parameters cglen and fglen) you can use psize.py tool from the APBS distribution.

Parameter sp_apbs=.true. triggers only a single APBS calculation (SP, single point energy). The calculated electrostatic energy contains self-energy terms thus it is not very useful by itself. This is however useful when, for instance, generating DX files for visualization. If the parameter sp_apbs is omitted (or set to .false., which is the default) then two APBS calculations (one for a system in solvent and then in vacuum) are performed every time solvation energy and forces are recalculated. This is used during minimization and MD simulations.