GROMACS Topology File Explained: topol.top and .itp Files

The GROMACS topology file (topol.top) tells gmx grompp which molecules exist in your system, the atoms, charges, bonds and force-field parameters of each, and how many copies of each molecule appear, in the same order as your coordinate file. It is usually short, because it pulls the force field and each molecule in through #include statements pointing at .itp files.

If you have run gmx pdb2gmx even once, you already have a topol.top. Most students never open it until grompp stops with a fatal error. This guide, written by the StemSkills Lab team (10+ years in structural bioinformatics, drug design and molecular modeling), walks through a real protein-ligand topology directive by directive, explains the ordering rules behind it, and maps the six errors that come from getting it wrong. It is the companion to our GROMACS .mdp file explained guide: the .mdp says how to simulate, the .top says what you are simulating.

What is a topology file in GROMACS?

A topology is the complete chemical and physical description of your system, minus the positions. The coordinate file (.gro or .pdb) says where each atom is. The topology says what each atom is (its atom type, charge and mass), which atoms are bonded, which angles and dihedrals carry a potential, which pairs are excluded from non-bonded interactions, and which force field supplies the numbers.

The official GROMACS reference manual (topology file formats) states that “the topology hierarchy (which must be followed) consists of three levels”:

1. Parameter level: force-field definitions such as [ defaults ], [ atomtypes ], [ bondtypes ] and [ dihedraltypes ].
2. Molecule level: one or more [ moleculetype ] blocks, each followed by its [ atoms ], [ bonds ], [ pairs ], [ angles ], [ dihedrals ] and optional restraints.
3. System level: only [ system ] and [ molecules ].

The same page adds the rule that explains most topology errors: the file “is parsed only once”, so “items must be defined before they can be used”. There are no forward references. If a molecule uses an atom type, that type must already have appeared higher in the file.

What is the difference between topol.top and an .itp file?

An .itp (include topology) file is a fragment that is pasted into the .top at the position of its #include line, exactly like a C header file. grompp runs a C-preprocessor-style pass first, so #include, #define, #ifdef, #else and #endif all work. By convention:

• topol.top is the one file you pass to grompp with -p. It holds the system level and the include lines.
• forcefield.itp (inside the .ff folder) holds [ defaults ] and includes ffnonbonded.itp and ffbonded.itp.
• Molecule .itp files (for example topol_Protein_chain_A.itp, tip3p.itp, ions.itp or your ligand’s .itp) each hold one or more [ moleculetype ] blocks.
• posre*.itp files hold [ position_restraints ] for one molecule.

Here is how the five input and output files of a GROMACS run compare:

What does each line of a protein-ligand topol.top do?

Below is the skeleton of a correctly ordered topol.top for one protein chain, one ligand, water and ions. Folder and file names depend on your force field and ligand tool, so read them as patterns rather than strings to copy. The atom lines inside [ atoms ] and the molecule counts are omitted.

; Include forcefield parameters
#include "charmm36.ff/forcefield.itp"

; Include ligand parameters (new atomtypes, bondtypes, dihedraltypes)
#include "lig_params.itp"

[ moleculetype ]
; Name            nrexcl
Protein_chain_A     3

[ atoms ]
;   nr       type  resnr residue  atom   cgnr     charge       mass
...
[ bonds ]
...
[ pairs ]
...
[ angles ]
...
[ dihedrals ]
...

; Include Position restraint file
#ifdef POSRES
#include "posre.itp"
#endif

; Include ligand topology
#include "lig.itp"

#ifdef POSRES_LIG
#include "posre_lig.itp"
#endif

; Include water topology
#include "charmm36.ff/tip3p.itp"

; Include topology for ions
#include "charmm36.ff/ions.itp"

[ system ]
; Name
Protein-ligand complex in water

[ molecules ]
; Compound        #mols
Protein_chain_A     1
LIG                 1
SOL               ...
NA                ...
CL                ...

The force field include and [ defaults ]

The first #include loads forcefield.itp, which contains [ defaults ] (non-bonded function type, combination rule, whether 1-4 pairs are generated, and the fudgeLJ and fudgeQQ scaling factors). The GROMACS run-time errors page is explicit: [ defaults ] “can only appear once and must be the first directive in the topology”. That is why this line must sit at the very top. Choosing which force field goes here is covered in how to choose a force field in GROMACS.

Ligand parameters: why they come second

A ligand usually brings atom types or bonded parameters the protein force field does not have. Those [ atomtypes ] and [ *types ] blocks are parameter-level directives, so they must appear after the force field (the types they reference must exist) and before the first [ moleculetype ]. The run-time errors page puts it in one sentence: “The force field has to be fully constructed before any molecules can be defined.” Justin Lemkul’s widely used protein-ligand complex tutorial places its ligand parameter include in exactly this slot.

[ moleculetype ] and nrexcl

[ moleculetype ] gives the molecule a name and an nrexcl value. The manual’s urea example uses nrexcl = 3, which excludes non-bonded interactions between atoms up to three bonds apart; 1-4 interactions are then handled through [ pairs ]. The name you type here is the name you must use in [ molecules ], character for character.

[ atoms ], [ bonds ], [ pairs ], [ angles ], [ dihedrals ]

Each [ atoms ] line lists the atom number, atom type, residue number, residue name, atom name, charge group, charge and mass. Atoms “should be numbered consecutively starting at 1” within each molecule. pdb2gmx also writes a running qtot comment at the end of each atom line, and the manual advises that this cumulative charge “should be an integer after every residue”. It is the fastest way to find where a non-integer charge creeps in. The bonded sections list atom indices plus a function type; when no parameters follow, grompp looks them up from the force field by atom type.

#ifdef POSRES and posre.itp

pdb2gmx writes posre.itp with heavy-atom position restraints at a default force constant of 1000 kJ mol^-1 nm^-2 (the -posrefc default in the gmx pdb2gmx documentation). The #ifdef POSRES block means these restraints are only read when your .mdp contains define = -DPOSRES, which is how NVT and NPT equilibration hold the protein in place while production runs leave it free.

Water, ions, [ system ] and [ molecules ]

Water and ion .itp files come from the force field folder. [ system ] is a free-text title. [ molecules ] lists each molecule name and its count, and after [ system ] “the only allowed directive is [ molecules ]”. Ion names (NA, CL, or older spellings) must match the [ moleculetype ] names inside your force field’s ions.itp.

Why does my protein have several topol_Protein_chain_X.itp files?

When your PDB has more than one chain, pdb2gmx by default (-merge no) writes each chain as its own molecule type in a separate file, such as topol_Protein_chain_A.itp and topol_Protein_chain_B.itp, each with its own matching position restraint file. topol.top then only includes those files and lists each chain in [ molecules ]. Use -merge all if you need the chains in one [ moleculetype ], for example when a disulfide bridge links two chains.

The practical consequence: when you add a ligand to a multi-chain system, its include line goes after the last chain’s #ifdef POSRES ... #endif block, not in the middle of the chain includes.

Where should the ligand .itp go in topol.top?

A ligand normally needs two things in the topology, and they go in two different places:

1. Its new parameters ([ atomtypes ], and any [ bondtypes ], [ angletypes ], [ dihedraltypes ]) go directly after the force field include, before the protein.
2. Its [ moleculetype ] (atoms, bonds, angles, dihedrals) goes after the protein’s position restraint block and before the water include.

Parameterization tools often write both parts into one .itp file. If you include that single file after the protein, grompp stops with Invalid order for directive atomtypes. The fix is to cut the [ atomtypes ] block (and any other [ *types ] blocks) into a separate file, for example lig_params.itp, and include it right after forcefield.itp. Step-by-step ligand parameter generation with CGenFF and ACPYPE is covered in how to parameterize a ligand for GROMACS; cofactors such as heme or NAD follow the same placement rules, shown in our protein-cofactor simulation guide.

Finally, add the ligand to [ molecules ] in the same position it occupies in your complex .gro file. If the ligand coordinates follow the protein coordinates, the ligand line follows the protein line.

How do gmx solvate and gmx genion change topol.top?

Both tools edit [ molecules ] for you when you pass the topology with -p:

gmx solvate -cp complex_box.gro -cs spc216.gro -p topol.top -o solv.gro
gmx genion -s ions.tpr -o solv_ions.gro -p topol.top -pname NA -nname CL -neutral

The gmx solvate documentation says it “adds a line with the total number of solvent molecules” to your topology. genion replaces the matching number of SOL molecules with ions and appends the ion lines. Two habits prevent most count errors: always pass -p topol.top, and check the [ molecules ] block after each of these commands. Our guide to adding ions in GROMACS covers the genion step and the -pname/-nname choices in detail.

How do I add position restraints for a ligand?

Use gmx genrestr on the ligand’s own coordinate file, never the full complex, because restraint indices must count from 1 inside the ligand’s [ moleculetype ]. The manual notes that “you cannot use the output of a tool like genrestr blindly” for exactly this reason. The Lemkul tutorial does it in two commands, first building an index group of ligand heavy atoms with gmx make_ndx:

gmx make_ndx -f lig.gro -o index_lig.ndx
gmx genrestr -f lig.gro -n index_lig.ndx -o posre_lig.itp -fc 1000 1000 1000

Then include posre_lig.itp directly after the ligand’s .itp, inside its own #ifdef block. Using a separate name such as POSRES_LIG lets you restrain the protein and the ligand independently; to restrain both, set define = -DPOSRES -DPOSRES_LIG in the equilibration .mdp, as described in our .mdp file guide.

Which grompp errors come from the topology, and how do I fix them?

All six messages below are listed on the GROMACS run-time errors page or are printed verbatim by the grompp source code. For errors outside the topology, see common GROMACS errors and how to fix them.

Invalid order for directive atomtypes

Cause: an [ atomtypes ] block (usually from a ligand .itp) appears after a [ moleculetype ]. The manual calls [ atomtypes ] “the most common source of this error”. Fix: move the ligand’s [ atomtypes ] and other [ *types ] blocks into a file included immediately after the force field. The same message naming defaults means [ defaults ] appears somewhere other than the top of the file.

Found a second defaults directive

Cause: an included .itp sets its own [ defaults ], common with ligand files generated as standalone topologies. Fix: comment out that block in the ligand file with semicolons. If its values differ from your force field’s, stop and check that the ligand was parameterized for the same force field family; mixing families is the real problem.

Number of coordinates in coordinate file does not match topology

Cause: the atom total implied by [ molecules ] differs from the atom count in the .gro, typically because solvate or genion ran without -p topol.top, the ligand line was never added, or a count was typed by hand. Fix: make [ molecules ] match the coordinate file “in terms of both numbers and order of the molecules”, in the manual’s words.

No such moleculetype XXX

Cause: a name in [ molecules ] has no matching [ moleculetype ], often a ligand renamed in one file but not the other, or an include that sits inside an #ifdef that is switched off. Fix: make the names identical and check that the include is outside any conditional block.

Atomtype XXX not found

Cause: a molecule or parameter line uses an atom type that no included file defines, most often because the ligand’s parameter file was never included, or the ligand was typed for a different force field. Fix: include the ligand parameters right after forcefield.itp, and confirm the ligand’s atom types belong to the same force field family.

XXX non-matching atom names (molecule order mismatch)

Cause: the molecule order in [ molecules ] differs from the order of atoms in the .gro, so grompp maps parameters onto the wrong atoms. The manual says that when this appears “it should not be ignored”, and that a run forced past it with -maxwarn “will almost certainly blow up”. Fix: reorder the [ molecules ] lines to match the coordinate file.

A related failure, Atom index n in position_restraints out of bounds, comes from grouping all posre includes at the end of the file. Each restraint include must follow the [ moleculetype ] it belongs to.

How can I see the topology grompp actually reads?

Add -pp to your grompp call:

gmx grompp -f em.mdp -c solv_ions.gro -p topol.top -o em.tpr -pp processed.top

This writes the fully expanded topology after every #include and #ifdef has been resolved. When an ordering error points at a line inside a file you did not expect, searching processed.top for the directive shows exactly where it landed. It is the most useful single debugging step for topology problems, and it costs one flag. After grompp succeeds, the next step is energy minimization; the full sequence is in our protein-ligand MD tutorial.

Where does the topology fit in the full MD workflow?

The topology is built at the setup stage and then edited by every preparation step that adds molecules: pdb2gmx creates it, you add the ligand, solvate adds water, genion adds ions, and grompp reads it once per stage to build each .tpr. GROMACS itself is described in Abraham et al., SoftwareX (2015), the standard citation for the package. For the complete learning path from installation to analysis, start at our learn molecular dynamics with GROMACS pillar, and see where MD sits among the other skills in the computational biology skills roadmap.

Frequently asked questions

Can I edit topol.top in a text editor?

Yes. It is plain text, and adding ligand includes and molecule lines by hand is normal practice. Keep a copy of the original before editing, and let solvate and genion update the molecule counts with -p rather than typing them yourself.

Do I need to rerun pdb2gmx after adding a ligand?

No. pdb2gmx only handles residues its force field database knows. Run it on the protein alone, then add the ligand’s .itp files and [ molecules ] line to the topology it produced.

Why does [ molecules ] say SOL when my water model is TIP3P?

SOL is the [ moleculetype ] name used inside the force field’s water .itp files. The water model is chosen by which .itp you include, not by the molecule name.

Is a .top file the same as a .tpr file?

No. The .top is a human-readable text description you edit. The .tpr is a binary file grompp writes by combining the .top, the coordinates and the .mdp; mdrun reads only the .tpr.

What does nrexcl = 3 mean?

Non-bonded interactions are excluded between atoms separated by up to three bonds. Interactions between atoms exactly three bonds apart (1-4 pairs) are then applied through the [ pairs ] section, with the scaling set in [ defaults ].