Troubleshooting Guide

"Number of coordinates in coordinate file does not match topology"

Cause: Your .gro and .top files are out of sync - almost always because one was edited (or an atom added/removed) without regenerating the other.

Fix: Regenerate both together from the same preparation step, or carefully re-check that the atom count and order in both files match exactly.

LINCS warnings, or the simulation "blows up"

Symptom: The log fills with LINCS warnings, or energies suddenly become enormous / NaN, and the run crashes.

Cause: Almost always an unstable starting structure - severe atomic clashes, a time step that's too large for the system, or starting production before the system was actually equilibrated.

Fix:

1. Re-run energy minimization and confirm the potential energy actually converged (check the .log).
2. Confirm your time step is reasonable (2 fs is standard) given your constraint settings.
3. Make sure NVT equilibration's temperature plot has genuinely plateaued before starting NPT.

"Fatal error: Too many warnings"

Cause: grompp found several concerning issues in your setup (often placeholder or default .mdp settings that don't match your system) and is refusing to proceed silently.

Fix: Read every warning listed above this message - don't just increase -maxwarn to make it go away. Each warning usually points at a real setup problem.

Pressure or temperature won't stabilize during equilibration

Cause: Most commonly, NPT was started before NVT temperature had actually plateaued, or restraints were released too early.

Fix: Check your temperature-vs-time plot from NVT before moving on. Consider a longer or staged equilibration (loosening restraints gradually) for larger or more flexible systems.

Simulation is far slower than expected

Cause: Often running on CPU only when GPU acceleration is available, or a poorly chosen number of MPI ranks / OpenMP threads for your hardware.

Fix: Confirm GPU offloading is actually active (check the top of the .log file, which reports what hardware was detected and used). Compare performance (ns/day) against a similar reference system size.

"Domain decomposition" errors on multi-core runs

Cause: GROMACS couldn't split your system evenly across the requested number of parallel domains, often because the number of cores requested doesn't divide the system sensibly, or the box is too small for that many domains.

Fix: Try a different (usually smaller) number of MPI ranks, or increase -dds tolerance if you're confident the setup is otherwise correct.

When in doubt

Read the .log file from top to bottom before anything else - GROMACS is usually explicit about what it detected and why it stopped. If you're still stuck, bring the exact error message and your .mdp settings to your instructor or a live lab session.