==========
Using APBS
==========

.. _PDB ID: https://www.rcsb.org/pages/help/advancedsearch/pdbIDs

.. note::

   *Before you begin!* PDB2PQR funding is dependent on your help for continued development and support. Please `register <http://eepurl.com/by4eQr>`_ before using the software so we can accurately report the number of users to our funding agencies.

APBS is often used together with the `PDB2PQR software <https://github.com/Electrostatics/pdb2pqr>`_; e.g., ,in the following type of workflow

#. Start with a `PDB ID`_ or locally generated PDB file (see :doc:`/formats/pdb`).
#. Assign titration states and parameters with :program:`pdb2pqr` to convert the protein and ligands to PQR format (see :doc:`/formats/pqr`).
#. Perform electrostatics calculations with :program:`apbs` (can be done from within the `PDB2PQR web server <web-server>`_).
#. Visualize results from within PDB2PQR web server or with :ref:`other-software`.

--------------
Web server use
--------------

Most users will use PDB2PQR through `the web server <http://server.poissonboltzmann.org/>`_ (after `registering <http://eepurl.com/by4eQr>`_, of course).
However, it is also possible to install local versions of PDB2PQR and run these through the command line.

----------------
Command line use
----------------

.. code-block:: bash

   apbs [options] input-file

where the list of ``[options]`` can be obtained by running APBS with the ``--help`` option.
The input file format is described below.

-----------------
Input file syntax
-----------------

APBS has a :ref:`new input file format <new_input_format>` that accepts `YAML- <http://yaml.org>`_ or `JSON- <http://json.org>`_ format input.
The :ref:`old APBS input format <old_input_format>` has been deprecated but will continue to be supported for the next few releases.

.. toctree::
   :maxdepth: 2
   :caption: New and old input file formats

   input/new/index
   input/old/index

.. _examples:

--------
Examples
--------

.. _PDB2PQR:  https://github.com/Electrostatics/pdb2pqr
.. _APBS-PDB2PQR web interface:  http://server.poissonboltzmann.org/

APBS examples start with a PQR file (e.g., generated by PDB2PQR_).
Some of these examples can be performed through the `APBS-PDB2PQR web interface`_ but most require a command-line APBS program.

.. toctree::
   :maxdepth: 2

   examples/solvation-energies
   examples/binding-energies
   examples/salt-linkage
   examples/visualization-pymol
   examples/visualization-unitymol

--------------------
Tests and validation
--------------------

APBS is distributed with testing tools and validation examples.

.. toctree::
   :maxdepth: 1

   tests

-------------------
Tools and utilities
-------------------

APBS is distributed with utilities designed to simplify typical tasks associated with electrostatics calculations.

.. toctree::
   :maxdepth: 1

   tools

.. _other-software:

--------------
Other software
--------------

A variety of other software can be used to visualize and process the results of PDB2PQR and APBS calculations.

^^^^^^^^^^^^^^^^^^^^^^
Visualization software
^^^^^^^^^^^^^^^^^^^^^^

Examples of visualization software that work with output from PDB2PQR and APBS:

* `PyMOL <https://pymol.org/>`_
* `VMD <https://www.ks.uiuc.edu/Research/vmd/>`_
* `Chimera <https://www.cgl.ucsf.edu/chimera/>`_
* `PMV <http://mgltools.scripps.edu/packages/pmv>`_

^^^^^^^^^^^^^^^^^^^^
Dynamics simulations
^^^^^^^^^^^^^^^^^^^^

As an example of PDB2PQR and APBS integration with molecular mechanics sofware, the `iAPBS <https://mccammon.ucsd.edu/iapbs/>`_ library was developed to facilitate the integration of APBS with other molecular simulation packages.
This library has enabled the integration of APBS with several molecular dynamics packages, including `NAMD <http://www.ks.uiuc.edu/Research/namd/>`_, `AMBER <http://ambermd.org/>`_, and `CHARMM <https://www.charmm.org/charmm/>`_.

APBS is also used directly by Brownian dynamics software such as `SDA <https://mcm.h-its.org/sda/>`_ and `BrownDye <http://browndye.ucsd.edu/>`_.

--------------
Notes on units
--------------

APBS and PDB2PQR use a few different sets of units, explained in the following sections:

.. toctree::
   :maxdepth: 2

   units