GROMACS Protein-Ligand Complex MD Setup

What this workflow does

This workflow runs a complete molecular dynamics setup for a protein-ligand complex in GROMACS. The protein is T4 lysozyme L99A/M102Q (PDB: 3HTB). The ligand is 2-propylphenol (PDB ligand code JZ4).

The workflow splits the downloaded structure into a protein chain and a ligand. The two halves then follow separate branches. The protein branch models the missing side chains and builds an amber99sb-ildn topology with SPC/E water. The ligand branch adds hydrogens with Reduce, minimizes them with OpenBabel and GAFF, and parameterizes the molecule with ACPype. It also builds position restraints.

The two branches merge. The workflow concatenates the structures, appends the ligand topology to the protein topology, and defines a truncated octahedron box. It then solvates the box, adds neutralizing NaCl ions, and minimizes the system. NVT and NPT equilibration follow, then a 50 ps free production MD run. Three analysis stages compute the RMSd and the radius of gyration.

The compute problem

The graph has a fork. The protein branch and the ligand branch are independent until cat_pdb_complex. Both are CPU-light. The ligand branch runs four small chemistry tools in about a minute. The protein branch runs pdb2gmx in seconds.

The mdrun stages after the merge carry all the cost. Minimization, NVT, NPT, and free MD each integrate a solvated octahedron box that holds the protein, the ligand, the water, and the ions. This is a larger system than a bare protein, so each step costs more. GROMACS mdrun uses a GPU well.

The gmx_energy, gmx_rms, and gmx_rgyr stages read the trajectories and write .xvg traces. They are cheap and stay near the output files.

If you run all 30 stages on one GPU node, the GPU idles during the ligand parameterization and during every analysis stage. If you run them all on a laptop, the free MD run becomes the bottleneck.

How Horus solves it

Horus runs the independent branches in parallel. The ligand parameterization and the protein topology build do not wait for each other. Horus resolves the file dependencies from the workflow graph.

Horus also assigns an executor per stage. Keep the split, merge, and analysis stages on your local CPU. Send the four mdrun stages to a GPU node or to an HPC scheduler. Change one executor: field per stage. The runtime.command string does not change.

Every package in this workflow (biobb_io, biobb_model, biobb_chemistry, biobb_gromacs, biobb_analysis, biobb_structure_utils) has a native osx-arm64 conda build. The full complex setup runs on Apple Silicon without Docker. The equivalent AMBER complex workflow needs the Docker executor on the same hardware.

Pipeline

fetch_pdb                    Download 3HTB (T4 lysozyme + JZ4) from PDB
   │
   ├─ extract_heteroatoms     Extract JZ4 ligand (biobb_structure_utils)
   │     │
   │  reduce_add_hydrogens    Add hydrogens to ligand (Reduce)
   │     │
   │  babel_minimize          Energetically minimize ligand hydrogens (OpenBabel GAFF)
   │     │
   │  acpype_params_gmx       Generate ligand GROMACS topology (ACPype / amberGAFF)
   │     │
   │  make_ndx_ligand ──► genrestr   Ligand position restraints (1000 kJ/mol·nm²)
   │
   └─ extract_molecule        Extract protein chain
         │
      fix_side_chain          Model missing side-chain atoms
         │
      pdb2gmx                 Build protein topology (amber99sb-ildn, SPC/E)
         │
trjconv_protein + trjconv_ligand   Convert GRO to PDB (with hydrogens)
         │
      cat_pdb_complex          Concatenate protein + ligand into complex structure
         │
      append_ligand             Merge ligand topology into protein topology
         │
      editconf                  Define truncated octahedron box (0.8 nm)
         │
      solvate                   Fill box with SPC water molecules
         │
grompp_ions ──► genion            Add neutralizing NaCl ions
         │
grompp_minimize ──► mdrun_minimize ──► gmx_energy_min   Energy minimization
         │
      make_ndx_complex           Index file for protein-ligand complex group
         │
grompp_nvt ──► mdrun_nvt ──► gmx_energy_nvt   NVT equilibration (restrained)
         │
grompp_npt ──► mdrun_npt ──► gmx_energy_npt   NPT equilibration (restrained)
         │
grompp_free ──► mdrun_free        Free production MD (50 ps, unrestrained)
         │
gmx_rms_first / gmx_rms_exp / gmx_rgyr   RMSd and radius of gyration
         │
gmx_image                          Center complex, strip periodic-boundary artifacts
         │
gmx_trjconv_str_dry                Extract final dry protein-ligand structure

Inputs and outputs

Inputs

This workflow has no file inputs. It fetches 3HTB from the RCSB PDB and extracts both the protein chain and the JZ4 ligand.

Outputs land in results/:

• downloaded.pdb, ligand.pdb, protein.pdb, fixed.pdb: the split structures.
• pdb2gmx.gro, pdb2gmx_top.zip: the protein topology.
• ligand.params.gro, ligand.params.itp, ligand.params.top: the GAFF ligand topology.
• ligand_posres.itp: the ligand position restraints.
• complex_H.pdb, complex_top.zip: the merged complex and its topology.
• ionized.gro, ionized_top.zip: the solvated, neutralized system.
• min_energy.xvg, nvt_temp.xvg, npt_PD.xvg: the energy, temperature, and density traces.
• md.gro, md.trr: the free production MD trajectory.
• rms_first.xvg, rms_exp.xvg, rgyr.xvg: the analysis output.
• dry.gro: the final dry protein-ligand structure.

Change the target PDB code and the ligand code in configs/fetch_pdb.yaml and configs/extract_heteroatoms.yaml.

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)
• GROMACS
• ACPype
• Official GROMACS protein-ligand complex tutorial
• BioExcel protein-ligand complex MD setup tutorial