GMX-CHI(1)

📦
version 2026.4 · 8 versions
, in nixpkgs unstable, ubuntu stonking

✨ gmx-chi 💅 — the GROMACS manual page, bestie edition ✨

okay so this is the man page for gmx-chi, which lives in section 1 of the GROMACS manual. yes it's a mouthful, no I will not be shortening the vibes. let's go 🫶

🌸 NAME 🌸

gmx-chi — calculate literally everything you could ever want to know about chi and other dihedrals 💖

🎀 SYNOPSIS 🎀

gmx chi [-s [<.gro/.g96/...>]] [-f [<.xtc/.trr/...>]] [-ss [<.dat>]]
        [-o [<.xvg>]] [-p [<.pdb>]] [-jc [<.xvg>]] [-corr [<.xvg>]]
        [-g [<.log>]] [-ot [<.xvg>]] [-oh [<.xvg>]] [-rt [<.xvg>]]
        [-cp [<.xvg>]] [-b <time>] [-e <time>] [-dt <time>] [-[no]w]
        [-xvg <enum>] [-r0 <int>] [-rN <int>] [-[no]phi] [-[no]psi]
        [-[no]omega] [-[no]rama] [-[no]viol] [-[no]periodic]
        [-[no]all] [-[no]rad] [-[no]shift] [-binwidth <int>]
        [-core_rotamer <real>] [-maxchi <enum>] [-[no]normhisto]
        [-[no]ramomega] [-bfact <real>] [-[no]chi_prod] [-[no]HChi]
        [-bmax <real>] [-acflen <int>] [-[no]normalize] [-P <enum>]
        [-fitfn <enum>] [-beginfit <real>] [-endfit <real>]

🦋 DESCRIPTION 🦋

so like, gmx chi computes phi, psi, omega, and chi dihedrals for all your amino acid backbone and sidechains. all of them. every single one, bestie. 💜

it can compute a dihedral angle as a function of time, and as histogram distributions. the distributions are named histo-(dihedral)(RESIDUE).xvg and they're cumulative over all residues of each type — iconic behavior, honestly. ✨

if you pass the -corr option, the program will calculate dihedral autocorrelation functions. the function it uses is:

C(t) = <cos(chi(tau)) cos(chi(tau+t))>

the chef's kiss detail here is that it uses cosines rather than the angles themselves, which completely resolves the problem of periodicity. this is from Van der Spoel &amp; Berendsen (1997), Biophys. J. 72, 2032-2041. separate files for each dihedral of each residue are output as corr(dihedral)(RESIDUE)(nresnr).xvg, plus a file containing the info for all residues (that's the argument of -corr). 📁

with the -all option, the angles themselves as a function of time for each residue get printed to separate files named (dihedral)(RESIDUE)(nresnr).xvg. these can be in radians or degrees, your call. 🌈

a log file (the argument of -g) is also written, and it contains:

  • info about the number of residues of each type.
  • the NMR ^3J coupling constants from the Karplus equation.
  • a table for each residue of the number of transitions between rotamers per nanosecond, and the order parameter S^2 of each dihedral.
  • a table for each residue of the rotamer occupancy.

all rotamers are taken as 3-fold, except for omega and chi dihedrals to planar groups — that's chi_2 of aromatics, Asp and Asn; chi_3 of Glu and Gln; and chi_4 of Arg — which are 2-fold. and <bold>"rotamer 0"</bold> means the dihedral was not in the core region of each rotamer. the width of that core region can be set with -core_rotamer. 🎯

the S^2 order parameters are also output to an .xvg file (argument -o) and optionally as a .pdb file with the S^2 values as B-factor (argument -p). the total number of rotamer transitions per timestep (argument -ot), the number of transitions per rotamer (argument -rt), and the ^3J couplings (argument -jc) can also be written to .xvg files.

⚠️ heads up bestie: the analysis of rotamer transitions assumes that the supplied trajectory frames are equally spaced in time. it does not check. it trusts you. do not betray it. 🙈

if -chi_prod is set (and -maxchi > 0), cumulative rotamers are calculated, e.g.:

1+9(chi_1-1)+3(chi_2-1)+ (chi_3-1)

(that's if the residue has three 3-fold dihedrals and -maxchi >= 3). as before, if any dihedral is not in the core region, the rotamer is taken to be 0. the occupancies of these cumulative rotamers (starting with rotamer 0) are written to the file that is the argument of -cp, and if the -all flag is given, the rotamers as functions of time are written to chiproduct(RESIDUE)(nresnr).xvg and their occupancies to histo-chiproduct(RESIDUE)(nresnr).xvg. 💅

the option -r generates a contour plot of the average omega angle as a function of the phi and psi angles — meaning that in a Ramachandran plot, the average omega angle is plotted using color coding. art. 🎨

💖 OPTIONS 💖

🧚 Options to specify input files:

  • -s [<.gro/.g96/...>] (conf.gro) — structure file. the vibes it accepts: gro g96 pdb brk ent esp tpr.
  • -f [<.xtc/.trr/...>] (traj.xtc) — your trajectory. accepted formats: xtc trr cpt gro g96 pdb tng h5md.
  • -ss [<.dat>] (ssdump.dat) (Optional) — a generic data file. just a data file. living its life.

🍓 Options to specify output files:

  • -o [<.xvg>] (order.xvg) — an xvgr/xmgr file.
  • -p [<.pdb>] (order.pdb) (Optional) — a Protein data bank file.
  • -jc [<.xvg>] (Jcoupling.xvg) — an xvgr/xmgr file.
  • -corr [<.xvg>] (dihcorr.xvg) (Optional) — an xvgr/xmgr file.
  • -g [<.log>] (chi.log) — the log file.
  • -ot [<.xvg>] (dihtrans.xvg) (Optional) — an xvgr/xmgr file.
  • -oh [<.xvg>] (trhisto.xvg) (Optional) — an xvgr/xmgr file.
  • -rt [<.xvg>] (restrans.xvg) (Optional) — an xvgr/xmgr file.
  • -cp [<.xvg>] (chiprodhisto.xvg) (Optional) — an xvgr/xmgr file.

👑 Other options:

  • -b <time> (0) — time of first frame to read from trajectory (default unit ps).
  • -e <time> (0) — time of last frame to read from trajectory (default unit ps).
  • -dt <time> (0) — only use a frame when t MOD dt = first time (default unit ps).
  • -[no]w (no) — view output .xvg, .xpm, .eps and .pdb files.
  • -xvg <enum> (xmgrace) — xvg plot formatting. choices: xmgrace, xmgr, none.
  • -r0 <int> (1) — starting residue.
  • -rN <int> (-1) — last residue.
  • -[no]phi (no) — output for phi dihedral angles.
  • -[no]psi (no) — output for psi dihedral angles.
  • -[no]omega (no) — output for omega dihedrals (the peptide bonds, periodt).
  • -[no]rama (no) — generate phi/psi and chi_1/chi_2 Ramachandran plots.
  • -[no]viol (no) — write a file that gives 0 or 1 for violated Ramachandran angles.
  • -[no]periodic (yes) — print dihedral angles modulo 360 degrees.
  • -[no]all (no) — output separate files for every dihedral.
  • -[no]rad (no) — in angle vs time files, use radians rather than degrees.
  • -[no]shift (no) — compute chemical shifts from phi/psi angles.
  • -binwidth <int> (1) — bin width for histograms (degrees).
  • -core_rotamer <real> (0.5) — only the central -core_rotamer*(360/multiplicity) belongs to each rotamer (the rest is assigned to rotamer 0).
  • -maxchi <enum> (0) — calculate first ndih chi dihedrals: 0, 1, 2, 3, 4, 5, 6.
  • -[no]normhisto (yes) — normalize histograms.
  • -[no]ramomega (no) — compute average omega as a function of phi/psi and plot it in an .xpm plot.
  • -bfact <real> (-1) — B-factor value for .pdb file for atoms with no calculated dihedral order parameter.
  • -[no]chi_prod (no) — compute a single cumulative rotamer for each residue.
  • -[no]HChi (no) — include dihedrals to sidechain hydrogens.
  • -bmax <real> (0) — maximum B-factor on any of the atoms that make up a dihedral, for the dihedral angle to be considered in the statistics. this applies to database work where a number of X-Ray structures is analyzed. -bmax <= 0 means no limit.
  • -acflen <int> (-1) — length of the ACF; default is half the number of frames.
  • -[no]normalize (yes) — normalize ACF.
  • -P <enum> (0) — order of Legendre polynomial for ACF (0 indicates none): 0, 1, 2, 3.
  • -fitfn <enum> (none) — fit function: none, exp, aexp, exp_exp, exp5, exp7, exp9.
  • -beginfit <real> (0) — time where to begin the exponential fit of the correlation function.
  • -endfit <real> (-1) — time where to end the exponential fit of the correlation function; -1 is until the end.

💀 KNOWN ISSUES 💀

  • N-terminal phi and C-terminal psi dihedrals are calculated in a non-standard way, using H-N-CA-C for phi instead of C(-)-N-CA-C, and N-CA-C-O for psi instead of N-CA-C-N(+). this causes (usually small) discrepancies with the output of other tools like gmx rama. not me finding out my numbers don't match 😭
  • Rotamers with multiplicity 2 are printed in chi.log as if they had multiplicity 3, with the 3rd (g(+)) always having probability 0. it's giving fake news but in a log file. 🙈

🌈 SEE ALSO 🌈

more information about GROMACS is available at <http://www.gromacs.org/>. (the original wraps that URL with a soft hyphen, but you get it. 💖)

2026, GROMACS development team

and that's the whole thing, bestie 🫶 this was version 2026.4, dated Oct 02, 2026, straight from the GROMACS fam. go compute some dihedrals, you absolute icon. 👑💅✨

📦 where this page comes from