.. _subs_make_ligand_mol2:

make-ligand-mol2
----------------

``pestifer make-ligand-mol2`` generates Tripos mol2 files for every HETATM ligand
in a PDB whose residue name is not already defined in the loaded CHARMM
topologies.  Each mol2 is ready to feed directly to the CGenFF binary or to the
CGenFF web tool at https://cgenff.com/ for atom typing and parameter generation.

For each unknown ligand the subcommand:

#. Reads the heavy-atom coordinates and atom names from the input PDB.
#. Fetches the ligand's SMILES from the RCSB Chemical Component Dictionary
   (``data.rcsb.org``), preferring the OpenEye canonical-stereo form.
#. Builds an RDKit ``Mol`` whose heavy atoms are in the original PDB order
   and carry the original PDB atom names.
#. Protonates the ligand at the target pH (default 7.4) using Dimorphite-DL,
   which is aware of multi-pKa groups such as phosphates.
#. Adds explicit hydrogens with 3D coordinates and writes a Tripos mol2 via
   Open Babel.  The mol2's ``@<TRIPOS>MOLECULE`` title is set to the residue
   name so that the CGenFF binary/web tool registers the resulting ``RESI``
   under that exact name.

Heavy-atom names from the input PDB are preserved into the mol2, which means
the ``.str`` file generated by CGenFF can later be remapped back to the
original PDB naming without ambiguity.

Requirements
++++++++++++

The subcommand uses three optional dependencies:

* The ``rdkit`` and ``dimorphite_dl`` Python packages.  Install them together
  with pestifer via the optional extra::

    pip install 'pestifer[ligand-paramgen]'

  Or, in a conda environment::

    conda install -c conda-forge rdkit
    pip install dimorphite_dl

* The ``obabel`` binary from Open Babel must be on ``$PATH``.  On most Linux
  distributions this is in an ``openbabel`` (or similar) package.

For help with ``pestifer make-ligand-mol2``:

.. code-block:: bash

    $ pestifer make-ligand-mol2 --help

Examples
++++++++

Generate mol2 files for every non-CHARMM ligand in PDB ``1HPV``:

.. code-block:: bash

    $ pestifer make-ligand-mol2 1HPV --outdir mol2_out

The output for that PDB looks like:

.. code-block:: text

    === make-ligand-mol2 summary (outdir: mol2_out) ===
    Already in CHARMM (1): HOH

    Generated 1 mol2 file(s):
        478  ->  mol2_out/478.mol2

The input source can also be a local PDB file:

.. code-block:: bash

    $ pestifer make-ligand-mol2 ./my_structure.pdb --outdir mol2_out

If the RCSB Data API has no entry for a particular ligand (or the
default SMILES is unsuitable, e.g. you want a different tautomer), you can
supply a SMILES override:

.. code-block:: bash

    $ pestifer make-ligand-mol2 1IEP --smiles STI='Cc1ccc(NC(=O)c2ccc(cc2)CN2CCN(CC2)C)cc1Nc1nccc(n1)-c1cccnc1'

The ``--smiles`` flag can be repeated for multiple residues.

The protonation pH can be adjusted with ``--ph``:

.. code-block:: bash

    $ pestifer make-ligand-mol2 1AKE --ph 7.0

Per-ligand failures (no RCSB SMILES, RDKit cannot sanitize the structure,
``obabel`` fails, etc.) are reported in the summary but do not abort the run,
so a single problematic ligand will not block mol2 generation for the rest.

CGenFF round-trip
+++++++++++++++++

The recommended workflow once a mol2 file has been generated:

#. Upload the mol2 to https://cgenff.com/ (free academic license) and download
   the resulting ``.str``.
#. Drop the ``.str`` into ``~/.pestifer/toppar/`` -- the per-user custom CHARMM
   cache.  Any pestifer build that subsequently encounters that residue will
   resolve it automatically, without requiring ``charmmff.user_custom`` entries
   in the input YAML.

See :ref:`config_ref charmmff user_custom` for details on the user-custom
search-path machinery.