Running APBS

From APBS software documentation wiki

Jump to: navigation, search

APBS can either be used by itself or with other programs.

Contents

Invocation

In addition to using APBS through other programs, there are two ways to invoke APBS from the command line. The traditional approach uses the primary APBS binary to run APBS on local resources. However, in recent developmental versions of APBS, we have added the ability to run APBS through a secondary Python-based program which can be invoked locally but uses Opal web services to run APBS on remote (NBCR) resources.

Main APBS binary

As mentioned in the APBS installation and availability section, the main APBS binary is installed in ${APBS_PREFIX}/bin where ${APBS_PREFIX} is the top-level directory you chose for the installation. Of course, you can move the binary to any directory you choose. APBS is invoked with a very simple syntax: 

   apbs [options] input-file

Command line options include:

--outputfile=name
Sets the output logging path (as described in the output logging section of the manual) to name, or name_N for parallel runs, where N is the processor ID. If --outputformat is not specified, a flat-file format will be used as the default.
--outputformat=type
Sets the output logging format. Accepted values are:
flat
Flat-file format (default).
xml
XML format
--help
Displays command line usage
--version
Displays the current APBS version

input-file is an input file with a specific syntax described in the section Input files. Besides the output files specified from within input-file and the optional logs as specified by use of the --output-file command line option, APBS writes data to three additional places:

  • Standard output. This will appear on your screen (if you don't redirect it somewhere) and will contain all the basic information about the electrostatics calculation.
  • Standard error. This will also appear on your screen (if you don't redirect it somewhere) and will contain warnings and error messages.
  • The file io.mc (or io.mc_N for parallel runs, where N is the processor ID. This gives you detailed information about the progress of the run with a particular focus on the numerical solver.

APBS Opal client

The Opal Toolkit is a set of software produced by the National Biomedical Computational Resource (NBCR). This toolkit allows for the computing load for processor intensive scientific applications to be shifted to a 3rd party and/or generic computing grid. This can be tremendously advantageous in situations where a large amount of computing power is not locally available, but is required, for the task at hand. In particular, many users have discovered that their local computational resources are insufficient for certain types of APBS calculations on large systems or at extremely high accuracy. This client removes this resource limitation by allowing users to run on clusters at NBCR.

Recent developmental versions APBS add optional support for the off-loading of APBS calculations to an Opal service. Currently, the client uses services hosted by NBCR. Opal support has been integrated into APBS such that the end user will not be able to tell the difference between local and Opal runs of APBS: the APBS Opal client can be invoked in exactly the same way as the main APBS binary with identical output.

The APBS Opal support is in the form of a Python script ApbsClient.py and is installed by default when following the installation procedure outlined elsewhere. The script has been tested on Python 2.5; newer/older versions of Python may or may be functional.

As mentioned above, the basic invocation is the same as the main binary. The only difference is the executable, which is called ApbsClient.py, rather than apbs. This client should be installed by default when APBS is installed. Users can run: 

   ApbsClient.py [options] {input}

where options are described below and input is an APBS input file. Options available with ApbsClient.py include

--fetch={dir}
By default, the resulting files will be saved to the directory from which ApbsClient.py was launched. The --fetch switch can be used to change the directory (dir) to which the resulting files should be saved.
--help
This will cause a brief summary of the available options to be displayed.
--job-id={id}
This command can be used to automatically fetch the results of an APBS calculation run with the --non-blocking option. The --fetch switch must also be present if the --job-id switch is in use.
--local
This forces APBS to be run locally rather than on remote resources.
--no-fetch
One can prevent the automatic retrieval of APBS calculation results with this flag. If used, APBS will output a URL from which the resulting data can be retrieved later via a web browser. Use of this switch will also cause APBS to output a job ID which can be used to automatically retrieve all files using ApbsClient.py with the --job-id switch.
--non-blocking
By default, an Opal calculation will cause APBS to block (pause) until the remote calculation is complete. If you would instead like to manually retrieve the files, you can use the --non-blocking switch, which will cause APBS to output a URL from which the resulting data can be retrieved later via a web browser. Use of this switch will also cause APBS to output a job ID which can be used to automatically retrieve all files using ApbsClient.py with the --job-id switch.
--service-location={URL}
By default, the Opal support in APBS makes use of the NBCR's Opal web services. However, the user can easily substitute in any functional Opal APBS installation by specifying the URL for the remote service with this option.

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.

Please note that 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:

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 pages:

Using APBS with other programs

APBS was designed to facilitate use with other programs. This section outlines some of the programs with which APBS is known to work. However, it is likely that applications which use APBS have been inadvertently omitted from this list. If you know of software that uses APBS and is not listed here, please contact Nathan Baker.

Web interfaces

Gemstone

The Gemstone extension (http://gemstone.mozdev.org/) for the Firefox web browser used to provide a very easy-to-use interface to older versions of APBS (0.4.0) with all of the functionality of the command-line interface. However, this extension was created by external developers and is no longer actively maintained. Please let Nathan Baker know if this extension was important to your research.

NBCR web services

The NBCR Web Services portal (http://ws.nbcr.net:8080/opal/GetServicesList.do) provides an off-site alternative for running computationally-expensive APBS calculations that won't fit on local resources. This portal is currently running APBS 1.0.0.

The NBCR Opal Web Services client for APBS (http://nbcr.net/services/#Software) provides a more basic interface which allows users to execute APBS jobs remotely via Python or build such functionality into their own software.

However, in recent developmental versions of APBS, we have integrated Opal web services support into the existing command line client. If you are interested in testing this experimental functionality, please read the APBS Opal client section of this documentation.

Graphical user interfaces

PyMOL

PyMOL (http://pymol.sourceforge.net/) is a molecular visualization and animation package which provides an interface to APBS. The APBS plugin to PyMOL (developed by Michael George Lerner) permits isocontour and surface map visualization of APBS results. More information about using PyMOL with APBS is provided in the APBS FAQs.

VMD

VMD (http://www.ks.uiuc.edu/Research/vmd/) is a molecular visualization and animation package which provides an interface to APBS. It permits visualization of APBS results as isocontours, electric field lines, or on biomolecular surfaces. VMD also a graphical plugin to setup APBS calculations and execute them either locally or remotely via BioCoRE. More information is available at http://www.ks.uiuc.edu/Research/vmd/plugins/apbsrun/ and in the APBS FAQs.

PMV

PMV (http://www.scripps.edu/~sanner/python) is a Python-based molecular visualization package which provides an interface to APBS. It not only permits visualization of APBS results but it also integrates setup and executation of APBS calculations. The PMV/APBS interface (http://mccammon.ucsd.edu/pmv_apbs/) is under active development and future versions will offer even more setup, visualization, and analysis functionality.

The APBS interface is distributed with recent beta versions of PMV, avalaible from http://www.scripps.edu/~sanner/python. Additional documention for using APBS with PMV is provided at http://mccammon.ucsd.edu/~jswanson/apbsDoc/command_doc2.html.

Simulation software

Robert Konecny (McCammon Group) has developed iAPBS (http://mccammon.ucsd.edu/iapbs/), an interface between APBS and the simulation packages AMBER, CHARMM, and NAMD. More information is available from the iAPBS homepage: http://mccammon.ucsd.edu/iapbs/ .

Visualization software

Electrostatic potentials are commonly visualized in the context of biomolecular structure to better understand functional aspects of biological systems. This section describes molecular graphics software which can display potentials and other data output from APBS. Note that the graphical user interfaces discussed above can also be used to visualize APBS output.

Dino3D

Dino3D (http://www.dino3d.org/ is a molecular graphics program which can read UHBD-format electrostatic data. APBS can write multigrid results in UHBD format (see the write ELEC command) and therefore can be used with Dino3D.

MOLMOL

MOLMOL (http://www.mol.biol.ethz.ch/wuthrich/software/molmol/) is a molecular graphics package with an emphasis on NMR-generated structural data. A program is provided with APBS (see tools/mesh directory in the APBS distribution and the Data conversion tools in this manual) which converts OpenDX format data to MOLMOL format.

OpenDX

OpenDX (http://www.opendx.org) is a general data visualization package which can read APBS output using the scripts provided in tools/visualization/opendx (see the discussion of Data visualization tools in this manual). However, as there is no straightforward way to visualizate the potential in the context of the atomic structure, OpenDX should not a first choice for APBS visualization.

Retrieved from "http://apbs.wustl.edu/MediaWiki/index.php/Running_APBS"
Personal tools
Create a book