Using LigandParam to Parameterize Ligands
=========================================

| Zeke A. Piskulich\ :sup:`1`, Patricio Barletta\ :sup:`1`,  and Darrin M.
  York\ :sup:`1`
| :sup:`1`\ Laboratory for Biomolecular Simulation Research, Institute
  for Quantitative Biomedicine and Department of Chemistry and Chemical
  Biology, Rutgers University, Piscataway, NJ 08854, USA

Learning objectives
-------------------

.. start-learning-objectives

- Automate ligand parameterization workflows using the LigandParam command-line tool and Python API.

.. end-learning-objectives



Outline
-------

In this tutorial we will be covering the basic use of ligand parameterization with LigandParam, a tool developed by the York group to make ligand parameterization easy to do in a way that matches our best practices.

This tutorial will cover both the old way of doing simple parameterizations by hand, and then show how to do the same thing with LigandParam. 

Tutorial
--------

.. start-tutorial

.. mermaid::

   flowchart LR

   A["Prepare environment<br>Inputs: Python installation<br>Subprograms: python venv, pip install<br>Outputs: Activated ligandparam virtual environment"]

   B["Install LigandParam<br>Inputs: pip package index<br>Subprograms: pip install ligandparam<br>Outputs: LigandParam CLI available"]

   A --> B

   subgraph LazierLigand["LazierLigand recipe"]
      C["Run LazierLigand<br>Inputs: ligand.pdb, gaff2, bcc, net charge<br>Subprograms: lig-getparam lazierligand<br>Outputs: GAFF2 parameters and rst7 file"]
   end

   subgraph LazyLigand["LazyLigand recipe with RESP"]
      D["Ensure Gaussian available<br>Inputs: Gaussian installation<br>Subprograms: module load Gaussian<br>Outputs: Gaussian executable in PATH"]

      E["Run LazyLigand<br>Inputs: ligand.pdb, gaff2, bcc, net charge, Gaussian<br>Subprograms: lig-getparam lazyligand<br>Outputs: RESP-fitted parameters and rst7 file"]

      D --> E
   end

   B --> C
   B --> D





Parameterizing with LigandParam
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Within the "York Group", we have developed a tool called LigandParam that automates the above process and makes it easy to do ligand parameterization in a way that matches our best practices.

LigandParam is available by installing through pip with the following command: :footcite:t:`ligandParam_2026`

..

.. code-block:: bash 

    pip install ligandparam 

.. warning:: 
    One should only ever install LigandParam into a virtual environment to avoid conflicts with other environments and to keep your base environment clean. 

    .. code-block:: bash

        python -m venv ligandparam_env
        source ligandparam_env/bin/activate
        pip install rdkit parmed typing_extensions
        pip install ligandparam
        
Once installed, you now have LigandParam's command line interface. LigandParam is a complex package, with a wide-range of tools aimed at helping to automate LigandParameterization with relatively little user input. 
It works by running a prebuilt set of recipes that at its simplest mimics the three step process you did above (with some additions for some of the by hand steps mentioned above, such as charge equalization). 

In this tutorial, we will demonstrate the use of two of these recipes. 

- LazierLigand: The three step process above (essentially)
- LazyLigand: The three step process above with a single round of charge fitting with RESP.

There is another recipe, FreeLigand, that does everything LazyLigand does, but it adds a number of RESP calculations where the ligand is rotated around each cartesian axis (for a total of ~36 rotations) to 
remove any impact of the finite grid on the RESP calculation. This can lead to some slight numerical differences; however, the added expense is not worth it for a tutorial. 

We will start by showing an example for LazierLigand, which is the one that mimics what you did above. 

First, make a new folder to store these parameters, change directory into it, and copy the ligand pdb to this folder.

.. code-block:: bash
    
    mkdir lazier_param
    cd lazier_param
    cp ../ligand.pdb .

.. warning::

    For the next step, you'll want to make sure your ligandparam environment is activated!

    .. code-block:: bash

        source ../ligandparam_env/bin/activate


Now, we will run the LigandParam tool with the LazierLigand recipe.

.. code-block:: bash

    lig-getparam --recipe lazierligand --input ligand.pdb --resname LIG --data_cwd LIG --atom_type gaff2 --charge_model bcc --net_charge -1 --sqm 

The parameters used here are:

- recipe: lazierligand, this is the three step recipe
- input: ligand.pdb
- resname: LIG
- data_cwd: LIG
- atom_type: gaff2
- charge_model: bcc
- net_charge: -1
- sqm: True, this just tells it to take the minimized structure from antechamber.

This will do the same three-step process as before, but it will be fully automated and should be much faster. You should see you have the same outputs as before (along with a range of intermediate steps) in the 
folder LIG. However, this still doesn't use RESP charges. LigandParam can help with that too!

To get started, lets make our final set of parameters. Again start by making a new directory.

.. code-block:: bash

    cd ../
    mkdir lazy_param
    cd lazy_param
    cp ../ligand.pdb .

Now we will run with the LazyLigand recipe, which will do a single round of RESP fitting.

.. warning:: 
    
    This requires the Guassian electronic structure program to be available on the command line. 

    On {{DISPLAY_NAME}}, Guassian is available through:

    .. code-block:: console

        {{GAUSSIAN_LOAD}}


Now just like before, we can call ligandparam. 

.. warning:: 

    This can take some time and should not be run on a cluster's login node unless you want an angry email. 

.. code-block:: bash

    lig-getparam --recipe lazyligand --input ligand.pdb --resname  LIG --data_cwd LIG --atom_type gaff2 --charge_model bcc --net_charge -1 --sqm --nproc 4 --mem 10


.. note::

    If you want to run a more expensive calculation, you can use the freeligand recipe and compare the results. This uses the multi-orientational resp approach that helps handle the finite grid in Gaussian.

.. end-tutorial


Relevant literature
-------------------

.. footbibliography::