Ligand Parameterization

What this workflow does

This workflow generates GROMACS-compatible force-field parameters for a small molecule. It uses the GAFF (General AMBER Force Field) through ACPype.

The workflow fetches a ligand structure from the RCSB by its PDB ligand code. It adds hydrogen atoms with OpenBabel at pH 7.4. It then minimizes the hydrogen positions with OpenBabel and GAFF. The last stage runs ACPype and writes the .gro, .itp, and .top files.

Those three files are the input that a GROMACS protein-ligand simulation needs. This workflow is the standard first step before a complex MD setup.

The compute problem

Ligand parameterization is short but brittle. The whole run takes about a minute on one CPU core. No stage needs a GPU.

The difficulty is the software stack, not the compute. ACPype depends on AmberTools. OpenBabel depends on its own chemistry libraries. The three tools have different install paths and different version constraints. A local install that works today breaks after an unrelated upgrade.

The second difficulty is scale. One ligand is cheap. A library of 5,000 ligands is 5,000 independent runs. At that point you want the parameterize stage on a many-core node, and you want the fetch stage to stay off it. A fetch stage that waits on the RCSB holds a compute reservation for no reason.

How Horus solves it

Horus builds the conda environment from conda_env.yaml. It provisions OpenBabel, ACPype, AmberTools, and the biobb stack on the first run. Later runs reuse the cached environment. You do not manage the stack by hand.

Each stage declares an executor. For a single ligand, all four stages run in the local conda environment. For a library, move the parameterize stage to a many-core node with one executor: change. The runtime.command string does not change.

The packages here (biobb_io, biobb_chemistry) have native osx-arm64 conda builds. The workflow runs on Apple Silicon without Docker and without emulation. The AMBER-based workflows in this collection need the Docker executor on the same hardware.

Horus also tracks the file dependencies between the stages. The MOL2 file from add_hydrogens reaches minimize_hydrogens without a copy command. If you rerun after you change the pH, Horus reruns only the affected stages.

Pipeline

fetch_ligand       Fetch ligand structure from the PDB (biobb)
   │
add_hydrogens      Add hydrogen atoms at pH 7.4 (OpenBabel)
   │
minimize_hydrogens Energetically minimize hydrogen positions (OpenBabel + GAFF)
   │
parameterize       Generate GROMACS force-field parameters (ACPype / GAFF)
                   → ligand.params.gro  ligand.params.itp  ligand.params.top

Inputs and outputs

Inputs

This workflow has no file inputs. It fetches the ligand from the PDB. Set the ligand code in configs/fetch_ligand.yaml.

Outputs land in workflow_results/results/:

• ligand.pdb: the raw ligand structure from the RCSB.
• ligand.H.mol2: the ligand with added hydrogens.
• ligand.H.min.pdb: the hydrogen-minimized ligand.
• ligand.params.gro: the GROMACS structure file.
• ligand.params.itp: the GROMACS include topology with the GAFF parameters.
• ligand.params.top: the GROMACS top file.

The files configs/add_h.yaml and configs/minimize_h.yaml control the pH, the force field, and the convergence criteria.

Run the workflow

Install the horus-runtime and the plugins one time:

uv sync

If you do not have uv, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

You can also install the packages with pip:

pip install horus-runtime horus-environments

Then run the workflow:

uv run horus run workflow.yaml

The first run builds the conda environment. This takes a few minutes.

References

• BioExcel Building Blocks (biobb)
• ACPype
• OpenBabel
• GAFF (General AMBER Force Field)
• BioExcel ligand parameterization tutorial