=============
Using PDB2PQR
=============

.. _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.

PDB2PQR is often used together with the `APBS software <https://github.com/Electrostatics/apbs>`_; 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 biomolecule and ligand 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 :doc:`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

   pdb2pqr [options] --ff={forcefield} {path} {output-path}

This module takes a PDB file as input and performs optimizations before yielding a new PQR-style file in ``{output-path}``.
If ``{path}`` is a `PDB ID`_ it will automatically be retrieved from the online PDB archive.

In addition to the required ``{path}`` and ``{output-path}`` arguments, :program:`pdb2pqr` requires one of the following options:

* ``--ff=FIELD_NAME`` specifying the forcefield to use.  Run ``pdb2pqr --help`` to see specific options.

* ``--userff=USER_FIELD_FILE`` specifying a user-created forcefield file. Requires ``--usernames`` and overrides ``--ff``.

* ``--clean`` specifying no optimization, atom addition, or parameter assignment, just return the original PDB file in aligned format.
  Overrides ``--ff`` and ``--userff`` options.

Information about additional options can be obtained by running:

.. code-block:: bash

   pdb2pqr --help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Additional command-line tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following tools are also provided with PDB2PQR.
They all accept the ``--help`` option which provides information about usage of these tools.

"""""""
dx2cube
"""""""

Converts an OpenDX volumetric (e.g., as generated by APBS) to a Gaussian cube-format file.

""""""""
inputgen
""""""""

Generates an APBS input file with recommended settings.

-----------------------
Examples and algorithms
-----------------------

.. toctree::
   :maxdepth: 2

   examples
   algorithms
   other-software