AMBER Protein-Ligand Complex MD Setup

What this workflow does

This workflow sets up a molecular dynamics simulation of a protein-ligand complex with AmberTools. The example is T4 lysozyme (PDB 3HTB, mutant L99A/M102Q) bound to 2-propylphenol (ligand code JZ4).

The workflow first cleans the crystal structure. It strips the water. It removes the PO4 and BME co-crystallized ligands. pdb4amber then prepares the protein for AMBER.

The workflow handles the ligand on a separate branch. It extracts the heteroatoms. Reduce adds the hydrogens. OpenBabel minimizes the ligand against GAFF. ACPype then produces the GAFF parameter set, the library file and the frcmod file.

The two branches meet at LEaP. LEaP builds one topology for the complete complex. The workflow minimizes the ligand hydrogens in vacuo, then the full system in vacuo. ambpdb converts the result to PDB.

LEaP then solvates the system in a truncated octahedron box and adds ions. sander runs the minimization, the heating to 300 K, the NVT equilibration, the NPT equilibration and the free production MD. cpptraj computes the RMSd and the radius of gyration, and images the trajectory.

The compute problem

Ligand parameterization is the fragile part. ACPype, Reduce and OpenBabel each carry their own binary dependencies. A wrong atom type or a wrong charge at this point invalidates every later stage. You want to iterate on this branch alone, without repeating the MD.

The MD branch has the opposite profile. It is stable and expensive. The NPT equilibration and the production run need a GPU or a large core count. They produce trajectory files of several gigabytes.

The biobb_amber package has no osx-arm64 conda build. The LEaP stages, the sander stages and the ambpdb stage cannot install natively on Apple Silicon.

How Horus solves it

Horus splits the workflow along the same line. The ligand branch runs in the native conda environment on your machine. ACPype, Reduce and OpenBabel all have arm64 builds. You iterate on the parameters at local speed.

The AMBER stages run in the quay.io/biocontainers/biobb_amber container. Horus declares that image once and each AMBER stage points at it with the executor: field. The command string is identical to the conda case.

When the parameters are correct, move the production stages. Set the executor: field of sander_npt and sander_free to a remote GPU host. Horus sends the topology and the coordinates. Horus brings the trajectory back for cpptraj. The ligand branch does not change.

This per-stage routing keeps the cheap, error-prone work close and the expensive, stable work remote. A single-machine setup forces you to hold a GPU allocation while ACPype runs, or to rebuild the ligand parameters on the cluster by hand.

Pipeline

fetch_pdb              Download 3HTB from the PDB (biobb_io)
   │
remove_pdb_water        Strip crystallographic waters
   │
remove_ligand_po4        Remove PO4 co-crystallized ligand
   │
remove_ligand_bme         Remove BME co-crystallized ligand
   │
pdb4amber                  Prepare structure for AMBER
   ├──────────────────────────────────┐
extract_heteroatoms                    │
   │                                   │
reduce_add_hydrogens (Reduce)          │
   │                                   │
babel_minimize (OpenBabel/GAFF)        │
   │                                   │
acpype_params_ac (ACPype)              │
   │  lib, frcmod                      │
   └──────────► leap_gen_top ◄─────────┘   Build protein-ligand complex topology (leap)
                    │
               sander_h_min ──► process_h_min      Minimize ligand hydrogens in vacuo
                    │
               sander_n_min ──► process_n_min      Minimize full system in vacuo
                    │
               amber_to_pdb (ambpdb)                Convert minimized structure to PDB
                    │
               leap_solvate                         Solvate in truncated octahedron box
                    │
               leap_add_ions                        Neutralize and add ions
                    │
               sander_min ──► process_min           Energy minimize solvated system
                    │
               sander_heat ──► process_heat          Heat 0 → 300 K
                    │
               sander_nvt ──► process_nvt             NVT equilibration
                    │
               sander_npt ──► process_npt              NPT equilibration
                    │
               sander_free                              Free production MD
                    │
        ┌───────────┼───────────┬───────────────┐
   cpptraj_rms_first  cpptraj_rms_exp  cpptraj_rgyr  cpptraj_image
   (RMSd vs frame 0)  (RMSd vs exp.)   (Rgyr)        (image + strip solvent)

Inputs and outputs

Inputs

This workflow has no file inputs. It fetches PDB 3HTB from the RCSB at run time. The ligand code JZ4 is set in configs/extract_heteroatoms.yaml.

Outputs land in workflow_results/results/:

• 3htb.pdb, 3htb.noBME.pdb: the downloaded and cleaned structures.
• JZ4.pdb, JZ4.reduce.H.pdb, JZ4.H.min.mol2: the ligand intermediates.
• JZ4params.inpcrd, JZ4params.frcmod, JZ4params.lib, JZ4params.prmtop: the ACPype GAFF parameters.
• structure.leap.pdb, structure.leap.top: the complex topology.
• structure.ions.pdb, structure.ions.parmtop: the solvated, neutral system.
• sander.free.netcdf: the production MD trajectory.
• 3htb_rms_first.dat, 3htb_rms_exp.dat, 3htb_rgyr.dat: the analysis series.
• 3htb_imaged_traj.trr: the imaged, solvent-stripped trajectory.

Run the workflow

Install the horus-runtime 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

References

• BioExcel Building Blocks (biobb)
• biobb_amber
• biobb_wf_amber tutorial notebooks
• AmberTools
• ACPype