=============
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

.. note::

   `PROPKA <https://github.com/jensengroup/propka>`_ options are exposed via the PDB2PQR command line for convenience.
   However, not all of these options are supported in PDB2PQR.
   We have tried to add warning or error messages when unsupported PROPKA options are passed to the code but we may have missed some.
   Please `file an issue <https://github.com/Electrostatics/pdb2pqr/issues>`_ if you find a PROPKA option that is not working in PDB2PQR.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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