How to Define the Simulation Box in GROMACS with gmx editconf (Cubic vs Dodecahedron): A Step-by-Step Guide

Answer: gmx editconf sets your simulation box before solvation. Run gmx editconf -f in.gro -o box.gro -c -d 1.0 -bt dodecahedron to centre the solute and leave 1.0 nm to every wall. A rhombic dodecahedron holds 71 percent of the cubic volume at the same image distance, so it needs roughly 29 percent less water and less CPU time.

Almost every GROMACS tutorial hands you the box command as a single copied line and moves on to solvation. That line is one of the few points in the whole setup where a five second decision changes your wall clock time by nearly a third, and where getting it wrong produces a simulation that runs perfectly and means nothing.

What does gmx editconf actually do in the GROMACS setup chain?

The setup chain runs in a fixed order: gmx pdb2gmx builds the topology, gmx editconf defines the box, gmx solvate fills it with water, and gmx genion neutralises the charge. editconf sits in the middle and does exactly one thing that matters: it writes box vectors into the coordinate file.

The official description is deliberately modest. The GROMACS manual says editconf “converts generic structure format to .gro, .g96 or .pdb”. The box work is a side effect of that conversion, which is why students skim past it. But gmx solvate does not choose a box. It fills whatever box editconf already wrote. Every water molecule you pay for downstream was decided here.

Two flags carry the decision:

• -bt sets the box shape. Allowed values are triclinic, cubic, dodecahedron and octahedron.
• -d sets the distance between the solute and the box wall. The default is 0, which is never what you want.

Which box type should you choose: cubic, dodecahedron, octahedron or triclinic?

For a roughly globular protein in water, choose dodecahedron. The reason is pure geometry and it is quantified in the GROMACS reference manual.

Periodic boundary conditions require a minimum separation between your solute and its own periodic images, called the image distance. A cube is a wasteful way to guarantee that distance, because the corners of a cube sit much further from the centre than the faces do, and those corners are filled with water you are simulating for no scientific reason. A rhombic dodecahedron guarantees the same image distance in a smaller volume.

The manual’s own numbers, from the periodic boundary conditions chapter:

The manual states the payoff directly for the rhombic dodecahedron: “The volume is 71% of the volume of a cube having the same image distance”, and this “saves about 29% of CPU-time when simulating a spherical or flexible molecule in solvent”.

Twenty nine percent is not a rounding detail. In a solvated protein system the overwhelming majority of atoms are water, so cutting the water count cuts the non bonded work almost proportionally. That is often the difference between a 100 ns run that finishes on a free Colab GPU session and one that does not. If you are budgeting hardware for a first project, our guide to the computer requirements for docking and MD simulations puts that saving in context.

The catch, and it is the only real one: a dodecahedron box is stored internally as a triclinic cell, so your trajectory will look distorted in a viewer until you fix periodicity. That is a visualisation step, not a physics problem, and it is covered below.

What does -d actually control, and why do people use 1.0 nm?

-d is not the box length. It is a buffer, and the manual is precise about how that buffer becomes a box: “With -d and cubic, dodecahedron or octahedron boxes, the dimensions are set to the diameter of the system (largest distance between atoms) plus twice the specified distance”.

So -d 1.0 on a protein whose longest interatomic distance is 4.5 nm gives a box dimension of 4.5 + 2(1.0) = 6.5 nm. The factor of two is the part students miss. You are adding the distance on both sides.

The value matters because of a hard constraint in the physics. The manual states that “The minimum image convention implies that the cut-off radius used to truncate non-bonded interactions may not exceed half the shortest box vector”. Your non bonded cut-off in the .mdp file is typically around 1.0 to 1.2 nm depending on the force field, and grompp will refuse to run if the box cannot support it.

Justin Lemkul states the underlying principle plainly in the GROMACS tutorial suite published in Living Journal of Computational Molecular Science: “no atom should see multiple copies of the same atom within the short-range neighbor list”. A buffer of 1.0 nm is the common starting point precisely because it keeps the solute more than one cut-off length from its own image in the starting configuration.

Practical guidance, and be honest in your methods section about which you used:

• 1.0 nm is the conventional minimum for a stable globular protein with a 1.0 nm cut-off.
• 1.2 to 1.5 nm is safer for a protein you expect to unfold, extend or undergo a large conformational change, because the solute diameter grows during the run while the box does not grow with it.
• Below 0.9 nm is where periodic artefacts start being reported in the literature, and where grompp is likely to reject your cut-off outright.

What is the exact gmx editconf command for a protein?

Assuming pdb2gmx has written processed.gro, the command is:

gmx editconf -f processed.gro -o newbox.gro -c -d 1.0 -bt dodecahedron

Reading it flag by flag:

1. -f processed.gro is the input structure from pdb2gmx.
2. -o newbox.gro is the output that gmx solvate will take as -cp.
3. -c centres the molecule in the box. The manual describes it as “Center molecule in box (implied by -box and -d)”. It is off by default, and the parenthetical is why so many people get away with omitting it.
4. -d 1.0 is the solute to wall buffer in nanometres.
5. -bt dodecahedron is the shape.

For a cubic box, swap the last flag to -bt cubic and change nothing else. That single substitution is the whole cubic versus dodecahedron decision.

If you need explicit box vectors instead of a computed buffer, use -box rather than -d. The manual lists -box as “Box vector lengths (a,b,c)”. Do not pass both and expect the buffer to win.

How do you verify the box you actually got?

Two checks, both take seconds, and skipping them is how bad boxes reach production.

Check 1: read the terminal output. editconf prints the system size, the diameter, the centre, the box vectors, the box angles and the box volume before it exits. The diameter it reports is the same “largest distance between atoms” the manual refers to, so you can confirm the arithmetic yourself: the box dimension should equal that diameter plus twice your -d.

Check 2: read the last line of the .gro file. The final line of any GROMACS .gro file is the box vectors. A cubic box writes three numbers. A dodecahedron writes a triclinic representation with additional off diagonal terms, and the printed box angles are no longer all 90 degrees. If you asked for a dodecahedron and see only three numbers, the flag did not take effect.

You can also re-run editconf on the output file with no modifying flags to have it re-report the geometry of an existing structure. It is the cheapest possible sanity check on a file someone else gave you.

The decisive comparison, if you want to see the 29 percent for yourself: build the same solute twice, once cubic and once dodecahedron at the same -d, run gmx solvate on both, and compare the number of SOL molecules each reports. The ratio is your saving, measured on your own system rather than taken on trust.

When should you use -princ instead of just -c?

For a globular protein, -c alone is fine. For anything elongated, a DNA duplex, a coiled coil, a long peptide, the orientation of the solute inside the box changes how big the box has to be.

Because -d works from the largest distance between atoms, a long molecule lying diagonally across the box forces a much larger box than the same molecule aligned to an axis. The -princ flag fixes that. The manual describes it as “Orient molecule(s) along their principal axes”, and Lemkul’s tutorial suite notes it is the option “that aligns the longest axis”. Note that -princ will ask you to select a group, so it expects an index selection rather than running silently.

Two warnings. First, aligning to principal axes rotates your coordinates, so any position restraints or reference structures you generated before this step must be regenerated after it. Second, an elongated solute in a dodecahedron is often the case where -bt octahedron, at 0.77 of cubic volume, is the better compromise.

Why does a dodecahedron box look broken in VMD?

It does not. This is the single most common panic after switching box types, and the GROMACS user guide addresses it directly, noting that “Any periodic cell shape can be expressed as a parallelepiped (a.k.a. triclinic cell), and GROMACS does so internally regardless of the initial shape”.

So your dodecahedron is stored as a triclinic cell, and a viewer that draws the raw cell shows a slanted box with your protein apparently sliced across the boundary. The user guide also confirms the molecule wandering is expected, since “The box is not centered around anything while performing the simulation”.

The fix is post processing, not a re-run. Use gmx trjconv with the appropriate -pbc and centring options before you visualise or analyse, which is covered step by step in our gmx trjconv tutorial. Do this before RMSD and radius of gyration analysis as well as before making figures, because a molecule broken across the periodic boundary produces nonsense in both.

Which box mistakes actually break your simulation?

These are the failures that trace back to this one command, and the error you will actually see.

On that last row, the GROMACS run time errors page is worth reading before you change anything, because constraint warnings usually mean the system is destabilising for reasons upstream of the box. Our post on common GROMACS errors and how to fix them works through the diagnosis order, and energy minimisation is where most of these actually get resolved.

Frequently asked questions

Is a dodecahedron box less accurate than a cubic box?

No. Both satisfy the same minimum image convention at the same image distance. The dodecahedron simply achieves it with less solvent. The physics of the solute is unchanged; you are removing water that was never contributing anything.

Can I change the box after solvation?

Not sensibly. Running editconf on a solvated system rescales or re-boxes coordinates that already contain water and ions, which produces overlaps or vacuum. Go back to the unsolvated structure, set the box correctly, and re-run gmx solvate and gmx genion.

What is the difference between -d and -box?

-d computes box dimensions from your solute’s diameter plus twice the distance you give. -box sets the vector lengths explicitly in nanometres. Use -d for ordinary solute in solvent setups and -box when an external requirement fixes the cell.

Does gmx editconf change my topology file?

No. editconf only touches coordinates and box vectors. The topology from pdb2gmx is unaffected. gmx solvate and gmx genion are the steps that modify the .top file, by adding SOL and ion entries.

Why does my protein drift out of the box during the simulation?

Because nothing holds it there. The box is not centred on anything during the run, and molecules cross the boundary freely under periodic boundary conditions. Restore whole molecules and re-centre with gmx trjconv before analysis.

Where this fits in the wider workflow

The box is a five second decision with a measurable cost attached, which makes it a good example of what separates a copied tutorial from a run you can defend. If you are working through the full pipeline, this step sits inside our pillar guide on learning molecular dynamics with GROMACS, and the broader sequence of skills is mapped in the computational biology skills roadmap.

Written by the StemSkills Lab team, with more than 10 years of combined experience in sequence and structural bioinformatics, drug discovery and design, and multiscale molecular modeling.