iAPBS/Amber Interface: User Guide

Table of Contents

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 3.4.1 or later).
  • AmberTools (version 23 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

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/A2)
chgm chgm [1] Charge discretization method: 0: spl0; 1: spl2; 2: spl4
vol smvolume The parameter smvolume controls the lattice size (in Angstroms3) 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 radius3 or size ions of volume radius3/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 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=3 option
  calcnpenergy [1] Calculate nonpolar energy [0, 1]. 0: Don't calculate; 1: SASA-based apolar energy calculation.
  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

Note

  • 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

Note

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.

Author: Robert Konecny <rok@ucsd.edu>

Created: 2023-04-12 Wed 10:40

Validate