Dihedral Angle Analysis in GROMACS: gmx angle, gmx chi
Skip to content

Dihedral Angle Analysis in GROMACS: gmx angle and gmx chi

Dihedral Angle Analysis in GROMACS: gmx angle and gmx chi

To analyse a dihedral angle in a GROMACS trajectory, write an index group listing the four atoms of the torsion in bonded order, then run gmx angle -type dihedral with -ov for the angle over time and -od for its distribution. For protein side chains, gmx chi -maxchi 2 -all computes chi1 and chi2 for every residue and reports rotamer occupancy and transitions.

After a protein-ligand MD run, RMSD tells you that something moved, but not what. Very often the answer is a single torsion: the ligand’s rotatable bond swings its ring into a different sub-pocket, or a binding-site phenylalanine flips its chi1 and opens the pocket. Reviewers ask for exactly this evidence. This guide from the StemSkills Lab team (10+ years in structural bioinformatics, drug design and molecular modelling) shows how to measure a ligand torsion with gmx angle, how to track side-chain rotamers with gmx chi, how to plot both, and how to spot the index and periodicity mistakes that produce numbers which look plausible and mean nothing.

You need a finished trajectory and its .tpr, for example from our protein-ligand MD simulation tutorial. The options below are taken from the official gmx angle and gmx chi documentation. For where this sits in a full project, see our GROMACS molecular dynamics guide.

What is a dihedral angle, and why analyse it after MD?

A dihedral (torsion) angle is defined by four bonded atoms i, j, k, l. It is the angle between the plane through i, j, k and the plane through j, k, l, which measures the twist around the central j-k bond. It runs over a full circle, so +180 and -180 degrees are the same geometry.

Two questions in a protein-ligand study come down to dihedrals:

  • Does the ligand keep its docked conformation? A rotatable bond that stays near its starting value supports the pose. One that switches to a new value and stays there tells you the docked conformation was not the one MD prefers.
  • Does a binding-site side chain change rotamer? Side-chain chi1 angles cluster around three staggered values near +60, 180 and -60 degrees. A jump from one cluster to another is a rotamer transition, and in a pocket it can open or close space for the ligand.

Backbone phi and psi are also dihedrals, but for those use the Ramachandran workflow in our gmx rama tutorial.

How do I pick the four atoms for a ligand torsion?

Open the ligand in a viewer (PyMOL or VMD) with atom name labels on. Choose the rotatable bond you care about; its two atoms are j and k. Then pick one heavy atom bonded to j (that is i) and one heavy atom bonded to k (that is l). Write down the four atom names, for example C7 C8 N2 C9. These names are illustrative; use the names in your own ligand’s .itp or .gro.

Next you need the global atom numbers of those atoms in the simulated system, not their numbers inside the ligand .itp. Ask GROMACS:

gmx select -s md.tpr -select 'resname LIG and name C7 C8 N2 C9' -on tor_atoms.ndx

Open tor_atoms.ndx. It lists the four atom numbers, but in the order they appear in the system, not the order you typed. That matters, because the order of the four atoms defines the dihedral.

How do I build the index group for gmx angle?

Write the index file by hand, with the four numbers in bonded order i, j, k, l. Assuming gmx select returned atoms 2345 to 2351 (example numbers), a file named dihedral.ndx looks like:

[ LIG_tor1 ]
2345 2346 2348 2351

Two rules come straight from the documentation and the way the program reads the group:

  1. The group must contain atom quadruplets. The gmx angle help states that the index file must contain quadruplets for dihedrals and that otherwise “the program will crash”.
  2. Each consecutive block of four is one dihedral. To measure two torsions in one run, put eight numbers in the group. To keep them easy to read, use one group per torsion instead.

Avoid building this group in make_ndx with | (OR) between single atoms. The combined group is stored in atom-number order, so your bonded order can be lost silently. Our make_ndx index groups tutorial covers where make_ndx is the right tool and where it is not.

How do I run gmx angle for a dihedral time series and distribution?

Make the molecules whole and centred first, so no ligand is split across the periodic box (see our gmx trjconv tutorial):

gmx trjconv -s md.tpr -f md.xtc -o md_center.xtc -pbc mol -center

Then run the analysis:

gmx angle -f md_center.xtc -n dihedral.ndx -type dihedral -ov tor1_time.xvg -od tor1_dist.xvg -ot tor1_trans.xvg

Select LIG_tor1 when prompted. The outputs:

  • -ov: the average angle of the group as a function of time. With one dihedral in the group, this is simply that dihedral’s time series. Add -all when the group holds several dihedrals; the first column after time is then the average and the rest are the individual angles.
  • -od: the angle distribution, with a default bin width of 1 degree (change it with -binwidth).
  • -ot: when transitions occur between rotamers. The documentation limits this to dihedrals of multiplicity 3 and assumes the trajectory frames are equally spaced in time.

Use -b and -e (in ps) to drop the equilibration part of the run, and -dt to thin a long trajectory.

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.

Join the waitlist (free) →

How do I analyse side-chain rotamers with gmx chi?

gmx chi computes backbone and side-chain dihedrals for every amino acid in the structure, so you do not build index groups at all. The one setting that catches everyone: -maxchi defaults to 0, which means no chi angles are calculated. For chi1 and chi2:

gmx chi -s md.tpr -f md_center.xtc -maxchi 2 -all -g chi.log -o order.xvg -rt restrans.xvg

What you get back:

  • chi.log: for each residue, the rotamer transitions per nanosecond, the order parameter S2 of each dihedral, and the rotamer occupancy. This is the table to read first.
  • Per-residue time series from -all, named by the pattern (dihedral)(RESIDUE)(number).xvg, for example a chi1 file for a phenylalanine. On a whole protein this produces a large number of files, so run it in its own folder.
  • Distributions named histo-(dihedral)(RESIDUE).xvg, which the documentation notes are cumulative over all residues of each type. For a single binding-site residue, use its own time series file instead.
  • restrans.xvg: the number of transitions per rotamer.

The -r0 and -rN options limit the residue range. Check chi.log afterwards to confirm which residues were included.

Two details from the documentation shape how you read the results. Rotamers are treated as 3-fold, except dihedrals to planar groups, which are 2-fold: chi2 of aromatic residues, Asp and Asn, chi3 of Glu and Gln, and chi4 of Arg. And with the default -core_rotamer 0.5, only the central half of each rotamer window counts as that rotamer. For a 3-fold dihedral that is the central 60 degrees of each 120-degree window; frames outside the core are assigned to “rotamer 0”, so occupancies do not need to sum to 100% across the named rotamers.

gmx chi only knows amino acids. It does not analyse your ligand. Ligand torsions always go through gmx angle or a Python library.

Which dihedral tool should I use?

ToolBest forNeeds an index group?Handles ligands?Main output
gmx angle -type dihedralOne or a few specific torsionsYes, atom quadruplets in bonded orderYesTime series, distribution, transitions (3-fold only)
gmx chiSide-chain rotamers across many residuesNo, uses residue namesNochi.log occupancy, transitions per ns, S2, per-residue files
gmx ramaBackbone phi and psiNoNoPhi/psi pairs for a Ramachandran plot
MDAnalysis Dihedral and Janin classesCustom torsion sets and scripted analysis in PythonNo, uses selectionsYesNumPy arrays you plot yourself

If you already work in Python, the MDAnalysis dihedrals module provides a Dihedral class for arbitrary quadruplets and a Janin class for chi1/chi2. Our MDAnalysis tutorial for GROMACS trajectories shows how to load the files.

How do I plot the dihedral .xvg files?

Lines starting with # or @ are headers, so skip them when loading:

import numpy as np
import matplotlib.pyplot as plt

t, ang = np.loadtxt("tor1_time.xvg", comments=["#", "@"], unpack=True)

fig, (a1, a2) = plt.subplots(1, 2, figsize=(10, 3.5))
a1.plot(t / 1000, ang, lw=0.6)
a1.set_xlabel("Time (ns)"); a1.set_ylabel("Dihedral (deg)")
a2.hist(ang, bins=72)
a2.set_xlabel("Dihedral (deg)"); a2.set_ylabel("Frames")
plt.tight_layout(); plt.savefig("tor1.png", dpi=300)

If a torsion sits near the edge of the range (around 180 degrees on a -180 to 180 scale), the time series jumps between the top and bottom of the plot every few frames, which looks like constant flipping but is one stable state. Look at the range your own file uses, then shift the values so the stable state sits in the middle:

ang_shifted = np.mod(ang, 360)   # maps -180..180 onto 0..360, so 180 sits mid-plot

For a side-chain chi1 that sits near -60 degrees, the default scale is already fine. More plotting options are in our guide on plotting GROMACS .xvg files in Python.

What are the common mistakes, and how do I fix them?

  • Atoms in the wrong order. Swapping j and k, or using an atom not bonded to j, gives a different, valid-looking dihedral. Fix: re-check the four names against the structure and write the index file by hand in bonded order.
  • gmx angle crashes on start. The group size is not a multiple of 4 (for dihedrals) or 3 (for angles). Fix: count the numbers in the group.
  • The angle seems to flip all the time. Usually the wrap at the edge of the range, not real transitions. Fix: plot the distribution, or shift the values as shown above; a real transition shows up as a second peak.
  • An average of two dihedrals that means nothing. Without -all, -ov writes the group average, and averaging angles near +60 and -60 gives about 0, a value neither dihedral visits. Fix: one dihedral per group, or -all.
  • gmx chi writes no chi files. -maxchi was left at its default of 0. Fix: add -maxchi 2 (or higher for long side chains).
  • Transition counts for an amide or aryl torsion look wrong. The -ot counting in gmx angle only works for 3-fold dihedrals, a limitation listed in the documentation. Fix: count transitions from the time series yourself, with thresholds suited to that torsion.
  • Transition rates change when you join trajectories. Both tools assume equally spaced frames. Fix: concatenate parts with the same output interval, or thin them to a common -dt.

For errors outside the analysis step, see our list of common GROMACS errors and fixes.

How do I report dihedral results in a thesis or paper?

State the four atoms by name, the tool and version, the time window analysed and the number of replicate runs. Show the distribution rather than only the time series, because it is easier to compare across replicates. Report rotamer occupancy as percentages from chi.log, and note the core-region setting if you changed it.

If you want to go further, dihedrals are the basis of dihedral PCA: gmx angle -or writes the cosine and sine of the selected dihedrals as a trajectory that gmx covar can analyse. The gmx chi documentation explains why its correlation functions use cosines: “The use of cosines rather than angles themselves, resolves the problem of periodicity” (Van der Spoel and Berendsen, Biophys J 1997). The PCA steps themselves are in our PCA tutorial for GROMACS.

Where this fits: dihedral analysis is part of step 7 (trajectory analysis) on our computational biology skills roadmap, alongside RMSD, RMSF and contact analysis.

Frequently asked questions

What is the difference between gmx angle and gmx chi?

gmx angle measures any angle or dihedral you define with an index group, including ligand torsions. gmx chi computes backbone and side-chain dihedrals of amino acids automatically from residue names and reports rotamer occupancy and transitions, but it does not analyse ligands.

Why does gmx chi produce no chi1 output?

The -maxchi option defaults to 0, so no side-chain dihedrals are computed. Set -maxchi 1 for chi1 only, or -maxchi 2 for chi1 and chi2.

Does the order of the four atoms matter in the index file?

Yes. The atoms must be listed in bonded order i, j, k, l, with the rotatable bond between j and k. A different order defines a different dihedral, and gmx angle will not warn you.

How do I know whether a side chain changed rotamer?

Look at the residue’s chi1 time series and distribution. A stable rotamer gives one peak; a transition gives a second peak and a step in the time series. chi.log reports the number of transitions per nanosecond and the occupancy of each rotamer.

How long must the simulation be to trust rotamer statistics?

Long enough to see each transition more than once, ideally in several independent replicates. One flip in one run is an observation, not a population. Our guide on how many replicate simulations to run covers this.

Written by the StemSkills Lab team, with 10+ years of experience in sequence and structural bioinformatics, drug discovery and design, and multiscale molecular modelling.

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.

Join the waitlist (free) →

Think you know Molecular Dynamics (GROMACS)?
Take the free StemSkills assessment and earn a verifiable certificate you can download and add to your LinkedIn profile.
Start the free assessment

Keep going

GROMACS MD With Two Ligands: Topology, Index, Restraints Set up a GROMACS run with two bound ligands: merge topologies, fix duplicate atomtypes, build index groups and… Disulfide Engineering in a Vaccine Construct with DbD2 Learn when a disulfide bond earns its place in a multi-epitope vaccine model, and run Disulfide by Design… GROMACS Position Restraints: gmx genrestr and POSRES Restrain your ligand during NVT and NPT with gmx genrestr, place the #ifdef POSRES block correctly, and fix…
See live workshops