Input Files

APBS input files are loosely-formatted files which contain information about the input, parameters, and output for each calculation. These files are whitespace- or linefeed-delimited. Comments can be added to the input files via the # character; all text between the # and the end of the line is not parsed by APBS. Specific examples of APBS input are described in the Examples section.

Note

There are several tools which help prepare APBS input files based on molecular structures, memory constraints, etc. These tools are described in more detail in the Problem setup section.

APBS input files contain three basic sections which can be repeated any number of times:

  • READ section for specifying input.
  • ELEC section for specifying polar solvation (electrostatics) calculation parameters.
  • APOLAR section for specifying apolar solvation calculation parameters.
  • PRINT section for specifying summary output.

The APBS input file is constructed from these sections in the following format:

 READ
 ...
 END

 ELEC
 ...
 END

 APOLAR
 ...
 END

 PRINT
 ...
 END

 QUIT
 

These sections can occur in any order and can be repeated any number of times. However, the sections are interdependent. For example, PRINT requires ELEC and/or APOLAR while ELEC requires one or more READ sections. Sections can also be repeated; several READ statements may be used to load molecules and multiple ELEC or APOLAR sections would specify various electrostatics calculations on one or more molecules.

Note

There are a number of places in the APBS input files where pathnames can be specified. If the pathname contains spaces, then the entire pathname must be enclosed in quotes. For example, if you wanted to refer to the file "foo" which resides in a directory with spaces in its name, then you should refer to foo as "/path with spaces/foo".

Each section of the APBS input file has its own syntax, described in more detail in the following sections:

Category List

APOLAR

This section is the main component for apolar solvation calculations in APBS runs. There may be several APOLAR sections, operating on different molecules or using different parameters for multiple runs on the same molecule. The syntax of this section is:

APOLAR [name id]
        {keywords...}
END

The first (optional) argument is:

name {id}

where id is a unique string which can be assigned to the calculation to facilitate later operations (particularly in the PRINT statements). The keywords… describing the parameters of the apolar calculation are discussed in more detail in the section APOLAR keywords. Basic APOLAR calculations are described in this section.

APOLAR Keywords

bconc

calcenergy

calcforce

dpos

gamma

grid

mol

press

sdens

srad

srfm

swin

temp

Basic APOLAR calculations

APBS apolar calculations follow the very generic framework described in Wagoner JA, Baker NA. Assessing implicit models for nonpolar mean solvation forces: the importance of dispersion and volume terms. Proc Natl Acad Sci USA, 103, 8331-8336, 2006.(doi:10.1073/pnas.0600118103).

In particular, nonpolar solvation potentials of mean force (energies) are calculated according to:

\[ \mathbf{W}^{(\mathrm{np})}(x) = \gamma A(x) + pV(x) + \bar \rho \sum^N_{i=1} \int _{\Omega} u_i^{(\mathrm{att})} (x_i, y) \theta (x,y) \, \mathrm{d}y \]

and mean nonpolar solvation forces are calculated according to:

\[ \mathbf{F}_i^{(\mathrm{np})}(x) = -\gamma \frac{\partial A (x)}{\partial x_i} - p \int _{\Gamma _i (x)} \frac{y-x_i}{\lVert y - x_i \rVert} \, \mathrm{d}y \] \[ -\, \bar \rho \sum _{i=1}^N \int _{\Omega} \frac{\partial u_i^{(\mathrm{att})}(x_i,y)}{\partial x_i} \theta (x,y) \, \mathrm{d}y \]

In these equations, $\gamma$ is the repulsive (hard sphere) solvent surface tension, $A$ is the conformation-dependent solute surface area (see srad and srfm keywords), $p$ (see press keyword) is the repulsive (hard sphere) solvent pressure, $V$ is the conformation-dependent solute volume (see srad and srfm keywords), $\rho$ (see bconc keywords) is the bulk solvent density, and the integral involves the attractive portion (defined in a Weeks-Chandler-Andersen sense) of the Lennard-Jones interactions between the solute and the solvent integrated over the region of the problem domain outside the solute volume $V$. Lennard-Jones parameters are taken from APBS parameter files as read in through an APBS input file READ statement.

Note

The above expressions can easily be reduced to simpler apolar solvation formalisms by setting one or more of the coefficients to zero through the keywords.

Important

All APOLAR calculations require a parameter file which contains Lennard-Jones radius and well-depth parameters for all the atoms in the solute PDB. This parameter file must also contain radius and well-depth parameters for water (specifically: residue "WAT" and atom "OW"). Complete parameter files for protein and nucleic acid parameters are not currently available and are actively under development as a research project. Please contact Nathan Baker for additional information about the state of this research, particularly if you are interested in helping.

ELEC

The ELEC block of an APBS input file is used for polar solvation (electrostatics) calculations and has the following syntax:

ELEC [ name {id} ]
        {type}
        {keywords...}
END

where the indentation and linefeeds are included for clarity; only whitespace is needed in the input file. The {id} tag allows the user to name ELEC blocks. The {type} command defines the Types of ELEC calculation to be performed. Finally, the {keywords} are calculation-specific commands that customize the particular type of calculation. This section is the main component for polar solvation calculations in APBS runs. There may be several ELEC sections, operating on different molecules or using different parameters for multiple runs on the same molecule. The order of the ELEC statement can matter since certain types of boundary conditions (bcfl) can require information about previous calculations.

ELEC block naming

Since numerous ELEC blocks may appear in an APBS input file, it can be difficult to keep track of them all. It is possible to assign an optional name to each ELEC block to simplify the organizational process. This syntax has the form

ELEC name {id}
    ...

where ELEC is the start of the ELEC block and {id} is an alphanumeric string denoting the “name” of the calculation block.

Elec keywords

akeypre

akeySOLVE

async

bcfl

calcenergy

calcforce

cgcent

cglen

chgm

dime

domainLength

ekey

etol

fgcent

fglen

gcent

glen

grid

ion

lpbe

lrpbe

maxsolve

maxvert

mol

nlev

npbe

nrpbe

ofrac

pdie

pdime

sdens

sdie

smpbe

srad

srfm

swin

targetNum

targetRes

temp

useaqua

usemap

usemesh

write

writemat

Types of ELEC calculations

fe-manual: manually-configured adaptive finite element Poisson-Boltzmann calculations

mg-auto: manually-configured adaptive finite element Poisson-Boltzmann calculations

mg-dummy: calculations of surface and charge distribution properties which do not require solution of the PBE

mg-manual: manually-configured multigrid Poisson-Boltzmann calculations

mg-para: automatically-configured parallel focusing multigrid Poisson-Boltzman calculations

PRINT

This is a very simple section that allows linear combinations of calculated properties to be written to standard output.

The syntax of this section is:

PRINT {what} [id op id op...] END

The first mandatory argument is what, the quantity to manipulate or print. This variable is a string that can assume the following values:

  • energy: Print energies as calculated with an earlier calcenergy ELEC command. Warning: this keyword is deprecated and will be removed soon. Please use elecEnergy or apolEnergy as appropriate to obtain the desired energy output. For now, use of this keyword will return the old results of elecEnergy.
  • force: Print forces as calculated with an earlier calcforce ELEC command. Warning: this keyword is deprecated and will be removed soon. Please use elecForce or apolForce as appropriate to obtain the desired energy output.
  • elecEnergy: Print electrostatic energies as calculated with an earlier calcenergy ELEC command.
  • elecForce: Print forces as calculated with an earlier calcforce ELEC command.
  • apolEnergy: Print energies as calculated with an earlier calcenergy APOLAR command.
  • apolForce: Print forces as calculated with an earlier calcforce APOLAR command.

The next arguments are a series of id op id op id op ... id commands where every id is immediately followed by an op and another id. These options have the following form:

  • id: This is a variable string or integer denoting the ID of a particular ELEC or APOLAR calculation. String values of id are assume to correspond to the optional "names" that can be assigned to ELEC or APOLAR calculations. Integer values of id are assumed to corresponding to the sequentially-assigned integer IDs for ELEC or APOLAR calculations. These IDs start at 1 and are incremented independently for each new ELEC or AOPLAR calculation.
  • op: Specify the arithmetic operation to be performed on the calculated quantities:
    • +: Addition
    • -: Subtraction

Given these options, a typical PRINT declaration might look like:

# Energy change due to binding
print energy complex - ligand - protein end
# Energy change due to solvation
print energy solvated - reference end
# Solvation energy change due to binding
print energy complex_solv - complex_ref - ligand_solv + ligand_ref - protein_solv + protein_ref end

See the examples directory provided with the APBS distribution for more examples.

READ

The READ block of an APBS input file has the following general format:

READ
    [ keywords... ]
END

where keywords is or more of the keywords described in the Keyword section (the line breaks and indentation are for clarity; only whitespace is necessary).

Note

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 and incremented independently for each input type. In other words, each input PQR file is assigned an ID 1, 2, 3, ...; each input dielectric map is assigned an independent ID 1, 2, 3, ...; etc.

READ keywords

charge

diel

kappa

mol

parm

pot

READ examples

The following is an example of a minimal READ section that only imports PQR format molecular structure files.

READ
   mol pqr ligand.pqr
   mol pqr receptor.pqr
   mol pqr complex.pqr
END

Reading a PDB file with parameters

READ
   mol pdb molecule.pdb
   parm flat param.dat
END

Reading external dielectric maps

READ
   mol pqr molecule.pqr
   diel dx dielx.dx diely.dx dielz.dx
END