How to Generate a GROMACS Topology with pdb2gmx: A Step-by-Step Beginner’s Guide

Answer capsule: To generate a GROMACS topology, run gmx pdb2gmx -f protein.pdb -o processed.gro -water spce, then select a force field when prompted. The command reads your cleaned PDB, adds hydrogens, and writes three files: a coordinate file, a topol.top topology, and a posre.itp position-restraint file for the equilibration steps that follow.

By the StemSkills Lab team, computational scientists with 10+ years in sequence and structural bioinformatics, drug discovery, and multiscale molecular modeling.

The single most common place a first molecular dynamics (MD) run breaks is not the simulation itself. It is the very first preparation command, gmx pdb2gmx. Get the force field, water model, and structure cleanup right here, and the rest of the GROMACS workflow tends to fall into place. This tutorial walks through the command end to end, explains every choice it asks you to make, and shows how to fix the error almost every beginner hits.

What does pdb2gmx actually do?

According to the GROMACS documentation, pdb2gmx reads a structure file, “adds hydrogens to the molecules and generates coordinates and a topology” in the GROMACS format (GROMACS manual, gmx pdb2gmx). In plain terms, it converts a static experimental structure into the parameterized system an MD engine can integrate over time.

A crystallographic PDB file lists atom positions but carries no physics: no bonded terms, no partial charges, no van der Waals parameters. pdb2gmx maps every residue onto a force field, assigns those parameters, and produces the files your later steps depend on.

• The coordinate file (for example processed.gro): your protein with hydrogens added, in GROMACS units.
• The topology (topol.top): the bonded and non-bonded parameters, atom types, and charges for the whole system.
• The position restraints (posre.itp): lets you hold heavy atoms in place during equilibration so water can relax around a fixed protein.

How do you run gmx pdb2gmx step by step?

Start from a cleaned single-chain protein PDB (ligands, crystallographic waters, and ions removed unless you plan to parameterize them separately). The canonical beginner path follows the lysozyme walkthrough in Justin Lemkul’s tutorial suite (Lemkul, LiveCoMS, 2019).

Step 1: Clean the structure

Remove non-protein records that pdb2gmx cannot parameterize on its own. Water lines in a PDB are labelled HOH or SOL:

• grep -v HOH 1aki.pdb > protein_clean.pdb

Inspect the file for HETATM records (ligands, cofactors, ions). If they are not part of the system you want to simulate, delete those lines too. If they are, they need separate ligand parameters, which is a later topic.

Step 2: Run the command

• gmx pdb2gmx -f protein_clean.pdb -o processed.gro -water spce

The -water flag sets the water model; -o names the output coordinate file. If you leave off -water, GROMACS will ask you to pick one interactively.

Step 3: Choose a force field

GROMACS prints a numbered menu of the force fields bundled with your installation and waits for a number. This is the most consequential choice in the whole preparation, so do not pick at random. The next section compares the common options.

Step 4: Confirm the outputs

On success you get processed.gro, topol.top, and posre.itp in your working directory. Open topol.top and confirm the [ molecules ] section lists your protein. If it does, the topology generated correctly and you can move on to defining the simulation box.

Which force field and water model should you choose?

The force field defines how every atom interacts. Different families were fit to different data, so they suit different jobs. For folded-protein MD, the AMBER and CHARMM families are the common defaults; GROMOS uses a united-atom scheme; OPLS-AA is all-atom. Note that CHARMM27 ships with GROMACS, but the newer CHARMM36 port is downloaded separately from the developers rather than bundled.

The -water flag must be compatible with your force field. The values GROMACS accepts include spc, spce, tip3p, tip4p, and none. A widely used starting pair is a GROMOS or AMBER force field with SPC/E (spce), or CHARMM with TIP3P (tip3p). When in doubt, match the water model the force field was originally parameterized with, which is documented on the force field’s own reference page.

How do you handle termini and protonation states?

By default pdb2gmx chooses charged N- and C-termini and standard protonation states for a neutral-pH environment. When your system needs something else (a capped terminus, a specific histidine tautomer, a protonated aspartate at low pH), you ask for the interactive menus with extra flags.

• -ter: interactively choose the N- and C-terminus type for each chain.
• -his: choose the protonation and tautomer state for each histidine instead of letting GROMACS decide.
• -asp, -glu, -lys, -arg: set the protonation state of those titratable residues interactively.
• -ignh: strip existing hydrogens from the input and let pdb2gmx rebuild them, which avoids naming mismatches from a hydrogen-containing PDB.

Protonation matters more than beginners expect. A histidine near an active site can change hydrogen-bonding and even the mechanism you are trying to study, so treat these states as a scientific decision, not a default to click past.

How do you fix “Residue not found in residue topology database”?

This is the error nearly every newcomer meets. The full message reads: Residue ‘XXX’ not found in residue topology database. It means pdb2gmx reached a residue or molecule that the chosen force field has no parameters for, and it stops rather than guessing.

Work through these causes in order:

1. Leftover heteroatoms. A ligand, cofactor, ion, or crystallographic water is still in the file. Remove the offending HETATM lines, or parameterize the ligand separately with a tool such as ACPYPE or CGenFF and add it back to the topology.
2. Non-standard residue names. Modified residues (for example a phosphorylated serine, or selenomethionine MSE) are not in the standard database. Rename to the standard residue if the modification is not essential, or supply parameters for it.
3. Hydrogen naming mismatches. If the PDB already contains hydrogens with non-standard names, rerun with -ignh so GROMACS rebuilds them under its own naming.
4. Wrong force field for the molecule. A nucleic acid or lipid residue may need a force field that includes those building blocks. Re-run and pick an appropriate one.

The habit that prevents most of these failures is disciplined cleanup before you ever call pdb2gmx. Know exactly what is in your PDB, line by line, and decide what stays.

Where does pdb2gmx sit in the full MD workflow?

Topology generation is step one of a longer pipeline: define a box (gmx editconf), solvate (gmx solvate), add ions (gmx grompp and gmx genion), minimize energy, equilibrate under NVT and NPT, then run production MD. Each step reads the topology you just built, which is why errors here cascade. For the full staged path and where MD fits alongside docking and structure preparation, see our computational biology skills roadmap, and for the deeper GROMACS track start at the molecular dynamics with GROMACS pillar.

Context for why this matters: the RCSB Protein Data Bank holds over 200,000 experimentally determined structures (RCSB PDB), and turning any one of them into a simulation begins with a correct topology. GROMACS itself is described by its developers as a package for “high performance molecular simulations” (Abraham et al., SoftwareX, 2015).

Frequently asked questions

What is the difference between a .gro file and a topology?

A .gro file stores coordinates: where each atom is in space. The topology (topol.top) stores physics: atom types, charges, bonds, angles, and dihedrals. MD needs both. pdb2gmx produces the pair from your input PDB.

Do I have to remove water and ligands before running pdb2gmx?

Yes, unless you intend to parameterize them. Standard force fields in pdb2gmx only recognize the 20 standard amino acids (plus common variants). Any ligand, cofactor, or crystallographic water left in the file triggers the “residue not found” error.

Which water model is safest for a beginner?

SPC/E (-water spce) paired with a GROMOS or AMBER force field is a common, well-documented starting point. If you use a CHARMM force field, TIP3P is the standard match. Always confirm the pairing on the force field’s reference page.

Why did pdb2gmx add hydrogens to my structure?

Most X-ray structures do not resolve hydrogen positions, but MD force fields need every atom. Adding hydrogens under the force field’s own naming and geometry is a core job of pdb2gmx, which is also why -ignh exists to rebuild them cleanly.

Can I run pdb2gmx without installing GROMACS locally?

Yes. GROMACS runs in cloud notebooks such as Google Colab, so you can complete the whole preparation without a local install. The command syntax is identical once GROMACS is available in the environment.