Periodic Image Check in GROMACS: gmx mindist -pi

To check if your protein saw its periodic image in GROMACS, run gmx mindist -s md.tpr -f md.xtc -pi -od mindist.xvg and choose the Protein group. The second column of the output is the minimum distance between the protein and its nearest periodic copy. If it ever drops below your longest non-bonded cut-off (rlist, rvdw or rcoulomb), the protein interacted with itself.
You set the box with gmx editconf -d, the system equilibrated, and the production run finished. A reviewer, a supervisor or your own doubt now asks a fair question: did the protein stay far enough from its own copies for the whole simulation? A box that looked generous at time zero can become too small when a loop swings out, a domain rotates, or a long terminus extends. The protein then feels a copy of itself, which no real protein in dilute solution ever does, and every downstream analysis inherits the artefact.
This guide from the StemSkills Lab team (10+ years in structural bioinformatics, drug design and molecular modelling) shows how to run the check, read every column of the output, plot it against your cut-off, and decide what to do when it fails. Every flag below was checked against the official GROMACS 2026 documentation for gmx mindist.
What is a periodic image and why does it matter?
MD simulations of solvated proteins use periodic boundary conditions: the box is surrounded by copies of itself in every direction, so a molecule leaving one face re-enters through the opposite face and there are no vacuum edges. Each atom interacts only with the nearest copy of every other atom, the minimum image convention. The GROMACS reference manual on periodic boundary conditions states the consequence: the cut-off radius used for non-bonded interactions may not exceed half the shortest box vector, otherwise more than one image of a particle falls inside the cut-off.
That rule protects the algorithm. It does not protect your science. A protein can still drift, rotate or extend until some of its atoms sit within the cut-off of atoms in its own periodic copy. When that happens the protein feels forces from itself: an artificial self-contact that can stabilise or distort its structure. The periodic image check tells you whether this happened, when, and how close it came.
Which GROMACS tool measures what?
GROMACS has several distance tools, and students often pick the wrong one for this job. The gmx mindist manual page itself points to gmx distance and gmx pairdist for other distance questions.
| Tool | What it measures | Input | Typical use |
|---|---|---|---|
gmx mindist -pi | Minimum distance from one group to its own periodic images, plus the group’s maximum internal distance and the three box vector lengths | One group, and a .tpr (or PDB with CRYST1) for box information | Did the protein see its periodic image? |
gmx mindist (no -pi) | Minimum distance and number of contacts between one group and other groups | Two or more groups, contact distance set by -d (default 0.6 nm) | Protein-ligand or chain-chain contact over time |
gmx distance | Distances between pairs of positions defined by selections | Selections made of position pairs | One specific atom-atom or centre-of-mass distance |
gmx pairdist | Minimum (default) or maximum distance between a reference selection and other selections, optionally grouped per residue | -ref and -sel selections | Per-residue closest approach to a ligand or partner |
Do I need to prepare the trajectory first?
Usually not, provided you pass the run input file. When gmx mindist has topology information from a .tpr, its source code makes molecules whole in every frame before computing the periodic distance. Without a run input file it prints a warning that a trajectory with broken molecules will not give the correct periodic image distance. So the rule is simple: give it -s md.tpr, the same file you ran gmx mdrun with, and the raw md.xtc.
The documentation also requires periodicity information from the -s file, either a .tpr or a .pdb with CRYST1 fields. If you must analyse a processed trajectory without the .tpr, make molecules whole first with gmx trjconv and -pbc mol, because a molecule split across the boundary gives a false near-zero distance.
What is the exact command, and which group should I choose?
gmx mindist -s md.tpr -f md.xtc -pi -od mindist.xvg -tu nsGROMACS asks you to “Choose a group for distance calculation”. Choose Protein for a single protein, or a group covering every chain for a complex. To run without the prompt, pipe the group name:
echo "Protein" | gmx mindist -s md.tpr -f md.xtc -pi -od mindist.xvg -tu nsThe flags that matter here:
-pi: switch on the periodic image calculation. The manual notes that only one shift in each direction is considered, giving 26 shifts in total (every neighbouring box in a 3 by 3 by 3 block, minus the central one).-od: output file,mindist.xvgby default.-tu ns: write time in nanoseconds instead of the default picoseconds.-b,-e,-dt: start time, end time and frame spacing, useful for long runs.
When the run ends, GROMACS prints a summary, “The shortest periodic distance is … (nm) at time …”, followed by the two atom numbers involved. Copy it into your notes: it is the single number your supervisor will ask for, and the atom numbers tell you which part of the protein came closest.
Want the guided, hands-on version?
Our live Molecular Modeling & MD Simulations cohort bootcamp takes you from zero to running real docking and MD workflows, with a portfolio project for your grad-school applications.
How do I read the columns of mindist.xvg?
With -pi the file has six data columns. The legend names below come from the gmx mindist source code. Confirm them in the legend lines (@ s0 legend to @ s4 legend) at the top of your own file:
| Column | Legend | Meaning | Unit |
|---|---|---|---|
| 1 | (time) | Simulation time | ps, or ns with -tu ns |
| 2 | min per. | Minimum distance between the group and any of its 26 periodic images | nm |
| 3 | max int. | Maximum distance between any two atoms inside the group | nm |
| 4 to 6 | box1, box2, box3 | Lengths of the three box vectors | nm |
Column 2 is the verdict. Column 3 is the explanation: if the protein’s largest internal distance grows over time, the molecule is extending, and that is usually why column 2 shrinks. Columns 4 to 6 show the box itself, which fluctuates slightly under pressure coupling. For a rhombic dodecahedron the GROMACS manual’s box-type table gives all three vectors the same length, a quick check that you used the box type you intended.
What cut-off should I compare against?
Compare column 2 with the longest of rlist, rvdw and rcoulomb used in your production run. Read them from the run input file rather than from memory:
gmx dump -s md.tpr | grep -E "rlist|rvdw|rcoulomb"This also prints related settings such as rvdw-switch and the interaction types, which you can ignore here. Our guide to the GROMACS mdp file explains each parameter. If the minimum periodic distance stays above the longest cut-off in every frame, no atom of the protein interacted directly with its own image. That is the claim you can make in a methods section, with the shortest distance as supporting data. We quote no extra safety margin here: the cut-off is the boundary the method defines, and any margin beyond it is a judgement you should state and justify for your own system.
How do I plot the result in Python?
import numpy as np
import matplotlib.pyplot as plt
data = np.loadtxt("mindist.xvg", comments=["#", "@"])
t, min_per, max_int = data[:, 0], data[:, 1], data[:, 2]
cutoff = 1.2 # placeholder: use the longest of rlist, rvdw, rcoulomb from gmx dump
fig, ax = plt.subplots(figsize=(7, 3.5))
ax.plot(t, min_per, lw=0.8, label="min distance to periodic image")
ax.axhline(cutoff, color="red", ls="--", label=f"cut-off ({cutoff} nm)")
ax.set_xlabel("Time (ns)")
ax.set_ylabel("Distance (nm)")
ax.legend()
fig.tight_layout()
fig.savefig("periodic_image.png", dpi=300)
below = t[min_per < cutoff]
print(f"Shortest distance: {min_per.min():.3f} nm at {t[min_per.argmin()]:.2f} ns")
print(f"Frames below cut-off: {below.size} of {t.size}")Replace the placeholder 1.2 with the number gmx dump printed for your run. The last two lines give you a frame count you can report honestly. For styling multi-panel figures, see our guide on plotting GROMACS xvg files in Python.
What should I do if the check fails?
If the minimum periodic distance falls below the cut-off, the affected part of the trajectory contains a self-interaction artefact. Running longer does not repair it. Equilibration relaxes the system, and extra time cannot undo frames in which the protein already felt its image. The honest fixes go back to setup:
- Use a larger box. Rebuild with gmx editconf and a larger
-d, which sets the distance between the solute and the box edge. At the start, two images of the protein are then separated by at least twice that distance. - Use a rhombic dodecahedron. For example
gmx editconf -f protein.gro -o box.gro -c -d 1.2 -bt dodecahedron, with the distance chosen for your system. The editconf documentation notes that a dodecahedron with the same periodic distance has 0.71 times the volume of a cube, so you gain distance with much less water to simulate. - Re-solvate, re-ionise, re-minimise and re-equilibrate. A new box means a new system. Run the whole preparation chain again rather than reusing old equilibrated coordinates.
- Re-run the check on the new production trajectory, and if a thesis chapter already used the first run, say so and report the corrected setup.
How do protein complexes, unfolding proteins and membranes change the check?
- Protein-protein complexes. Choose a group containing every chain, so the check covers the complex against its image. If the partners drift apart, the “max int.” column grows and one partner can approach the other partner’s image. Our protein-protein complex MD guide covers setup for these systems.
- Flexible or unfolding proteins. Proteins with long disordered termini or loops are the classic failure case. Watch column 3: a steady rise in maximum internal distance warns you before column 2 crosses the cut-off.
- Membrane systems. The lipid bilayer is continuous across the box in the membrane plane by design, so running
-pion the membrane group tells you nothing. Run it on the protein group only: the protein’s distance to its own image in the neighbouring box still matters.
What goes wrong with gmx mindist -pi and how do I fix it?
- “You have to specify either the index file or a tpr file”. You ran without
-s. Add-s md.tpr. - A warning that broken molecules will not give the correct periodic image distance. You passed a
.groor.pdbinstead of the.tpr, so molecules cannot be made whole. Use the.tpr, or rungmx trjconv -pbc molon the trajectory first. - The distance drops to almost zero in one or two frames. A molecule is split across the box boundary in those frames, typical of a processed trajectory analysed without the
.tpr. Rerun with-s md.tpron the originalmd.xtc. - The run is very slow on a long trajectory. The calculation scales with group size and frame count. Use
-dtto skip frames, for example-dt 100for one frame every 100 ps, or-band-eto check a window first. - You chose System and the values look meaningless. Solvent fills the whole box and always touches its own image, so a System or Water group answers nothing. Choose Protein, or a custom group built with gmx make_ndx.
- The xvg has more columns than you expected. That is normal for
-pi: time, minimum periodic distance, maximum internal distance and three box lengths. Read the legend lines in the file header. - An index or atom-number error with a reduced xtc. Your xtc stores fewer atoms than the
.tpr(a reduced output group in the mdp). Check that the group you choose is fully contained in the saved atoms, or run the check on the full.trrif you have one. - A few frames sit just under the cut-off. Judge it honestly. Note how many frames, by how much, and which atoms (from the summary line). A flexible terminal residue dipping briefly under the cut-off is a weaker artefact than a structured domain sitting there for nanoseconds, but it is still a contact you must report. For publication work, rebuilding with a larger box is the safe path. Our common GROMACS errors guide covers related setup issues.
Where does this check fit in a full MD workflow?
Run the periodic image check on every production trajectory, right after the run finishes and before RMSD, RMSF or binding analysis, because an image contact undermines those numbers. Report the shortest periodic distance and your longest cut-off in the methods. For the full sequence of MD skills, see our guide to learning molecular dynamics with GROMACS and the computational biology skills roadmap. When citing GROMACS itself, the standard reference is Abraham et al., SoftwareX 2015, 1-2:19-25.
Frequently asked questions
What does gmx mindist -pi actually calculate?
The minimum distance between the atoms of one group and the atoms of its own periodic images, considering one shift in each direction (26 images). It also writes the group’s maximum internal distance and the three box vector lengths for every frame. The manual calls it “useful for checking if a protein has seen its periodic image during a simulation”.
What distance is safe for the periodic image check?
The defined boundary is your longest non-bonded cut-off: rlist, rvdw or rcoulomb, read with gmx dump -s md.tpr. If the minimum periodic distance stays above it in every frame, the protein never interacted directly with its image.
Can I use a .gro file with -s?
Use the .tpr. The documentation asks for periodicity from a .tpr or a PDB with CRYST1 fields, and without a run input file GROMACS cannot make broken molecules whole, so the periodic distance may be wrong.
Does a longer simulation fix a periodic image contact?
No. Frames in which the protein felt its image already contain the artefact. The fix is a larger box (bigger editconf -d or a dodecahedron), followed by fresh preparation and a new production run.
Should I run the check on the ligand too?
Run it on the group that defines your system’s size, usually Protein or Protein plus ligand. A ligand that stays bound is covered by the protein group’s distance. A small ligand that unbinds needs a separate look, because it can drift toward the protein’s image.
Written by the StemSkills Lab team, who have spent 10+ years in structural bioinformatics, drug discovery and multiscale molecular modelling. Flags and output columns checked against the GROMACS 2026 documentation and the gmx mindist source code.
Want the guided, hands-on version?
Our live Molecular Modeling & MD Simulations cohort bootcamp takes you from zero to running real docking and MD workflows, with a portfolio project for your grad-school applications.
