GROMACS MD Setup

What this workflow does

This workflow runs a complete molecular dynamics setup for hen egg-white lysozyme (PDB: 1AKI). It uses GROMACS and the CHARMM36 force field. The workflow starts from the raw PDB file and ends with a production trajectory.

The workflow builds a topology, defines a cubic box, and solvates the protein in SPC water. It then adds neutralizing NaCl ions. It minimizes the system, runs NVT and NPT equilibration, and runs a free production MD simulation. Two final stages re-center the protein and extract the dry structure.

Every stage uses a BioExcel building block. All the blocks share one syntax: input files, output files, and properties. You do not write glue code between GROMACS calls.

The compute problem

An MD setup is a long chain of short stages and a few long ones. The two do not want the same machine.

The fetch, fix, topology, box, solvate, and ion stages read and write small text files. Each one takes seconds on a CPU core. They are cheap.

The mdrun stages are different. Minimization, NVT, NPT, and free MD each run a real GROMACS engine over a solvated box. These stages scale with core count and run much faster on a GPU. In a 100 ps demo they take minutes. At production length they take days.

A single-machine setup makes you pay for the large machine during the cheap stages. It also makes you copy input decks and trajectories by hand when you move the run to a cluster.

How Horus solves it

Horus assigns an executor to each stage. The preparation stages stay on your local CPU inside the conda environment. The mdrun stages move to a GPU node or to an HPC scheduler.

To move a stage, change the executor: field. The runtime.command string does not change. The same workflow.yaml runs on a laptop and on a cluster. This is the portability benefit of Horus.

All the biobb packages in this workflow (biobb_io, biobb_model, biobb_structure_utils, biobb_gromacs, biobb_analysis) have native osx-arm64 conda builds. The full workflow runs on Apple Silicon without Docker. This is not true for the AMBER and virtual screening workflows in the same collection.

Horus also builds the conda environment for you. It reads conda_env.yaml and provisions GROMACS and the biobb stack on the first run. Later runs reuse the cached environment.

Pipeline

fetch_pdb          Download 1AKI from the PDB
   │
fix_side_chain     Model missing side-chain atoms (biobb_structure_utils)
   │
build_topology     Build GROMACS topology (pdb2gmx, CHARMM36)
   │
editconf           Define cubic simulation box
   │
solvate            Solvate box with SPC water
   │
grompp_ions ──► genion        Add neutralizing NaCl ions
   │
grompp_minimize ──► mdrun_minimize   Energy minimization (steepest descent)
   │
grompp_nvt ──► mdrun_nvt     NVT equilibration (restrained, 10 ps)
   │
grompp_npt ──► mdrun_npt     NPT equilibration (restrained, 10 ps)
   │
grompp_free ──► mdrun_free   Free production MD (100 ps)
   │
gmx_image          Re-center protein, fix periodic boundary conditions
   │
gmx_trjconv_str    Extract final dry protein structure

Inputs and outputs

Inputs

This workflow has no file inputs. It fetches 1AKI from the RCSB PDB.

Outputs land in workflow_results/results/:

• downloaded.pdb: the raw PDB from the RCSB.
• fixed.pdb: the PDB with modelled side chains.
• structure.gro, topol.top, posre.itp: the GROMACS topology.
• mdrun_nvt.trr, mdrun_npt.trr: the equilibration trajectories.
• mdrun_free.trr: the production MD trajectory.
• structure.dry.pdb: the final dry protein structure.

The files in configs/ control the GROMACS mdp parameters. Edit them to change the time step, the temperature, the pressure, or the simulation length.

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
• CHARMM36 force field
• BioExcel MD setup tutorial