Bug #1441

g_principal - bug in output files axis{1,2,3}.dat

Added by Antonio Baptista over 3 years ago. Updated about 3 years ago.

analysis tools
Target version:
Affected version - extra info:
Affected version:


As of version 4.6.5, the program g_principal continues to suffer from what I would call a bug or, at least, a very bad and misleading choice of output file names.

The program g_principal "calculates the three principal axes of inertia for a group of atoms" and generates three output files with the default names axis{1,2,3}.dat. Although the content of these files is not explained, their names naturally suggest that axisN.dat contains the xyz components of the Nth principal axis (presumably in the conventional major-to-minor order). Indeed, each of these files contains (besides the time) 3 real values per frame, and this interpretation also yields 3 vectors which are orthonormal, as one would expect for the new frame defining the principal axes.

However, this "natural" interpretation is wrong, and not because of a different axes order. As correctly identified by Chris Neale in a previous gmx-users thread (, the file axis1.dat contains the x components of the 1st, 2nd and 3rd axes, the file axis2.dat their y components, and the file axis3.dat their z components (he checked with VMD, we did it with in-house programs in C and Octave). I think this a rather convoluted and extremely misleading way to output the principal axes.

My guess is that this problem derives from a simple confusion between the form of the orthogonal matrix obtained when solving the eigenvalue problem -- depending on the adopted algorithm, the vectors defining the new basis (the principal axes) can be either the columns or the rows of this matrix. I didn't look beyond gmx_principal.c, but the problem can be easily solved there by replacing the current lines

fprintf(axis1, "%15.10f     %15.10f  %15.10f  %15.10f\n", t, axes[XX][XX], axes[YY][XX], axes[ZZ][XX]);
fprintf(axis2, "%15.10f %15.10f %15.10f %15.10f\n", t, axes[XX][YY], axes[YY][YY], axes[ZZ][YY]);
fprintf(axis3, "%15.10f %15.10f %15.10f %15.10f\n", t, axes[XX][ZZ], axes[YY][ZZ], axes[ZZ][ZZ]);


fprintf(axis1, "%15.10f     %15.10f  %15.10f  %15.10f\n", t, axes[XX][XX], axes[XX][YY], axes[XX][ZZ]);
fprintf(axis2, "%15.10f %15.10f %15.10f %15.10f\n", t, axes[YY][XX], axes[YY][YY], axes[YY][ZZ]);
fprintf(axis3, "%15.10f %15.10f %15.10f %15.10f\n", t, axes[ZZ][XX], axes[ZZ][YY], axes[ZZ][ZZ]);

With this change, the file names would make perfect sense, with axisN.dat simply containing the components of the Nth principal axis. (Note that both the by-row and by-column readings give orthonormal vectors, because this is an orthogonal matrix.)

The file moi.dat also produced by g_principal is fine, containing the moments of inertia along the principal axes in the proper order (lowest to highest, since the inertia around those axes increases as one goes from the major to the minor).

I believe that, as it stands now, g_principal is misleading many users into the wrong interpretation of its output.

Related issues

Related to GROMACS - Feature #609: suggestion to add titles to columns in g_principal output files Closed 11/03/2010

Associated revisions

Revision 97c3c3a9 (diff)
Added by Erik Lindahl about 3 years ago

Fixed the output format of g_principal

Gromacs-4.6 and earlier versions had the output transposed. This
patch fixes it such that paxisN.dat contains the x/y/z components
of the N:th prinicipal axis. The default file output names have
been changed to paxisN.dat to increase the probability that users
who rely on old scripts will need to read the help text and find
the changed format.

Fixes #1441, related to #609.

Change-Id: Ic1ed9370145d3389ae8f43c2a419765dabf3a66f


#1 Updated by Szilárd Páll over 3 years ago

  • Category set to analysis tools

#2 Updated by Mark Abraham over 3 years ago

Thanks for the report, we'll probably incorporate that as-is for 4.6.6, but probably not for a fortnight or so.

#3 Updated by Chris Neale over 3 years ago

I agree with the change, but this might cause unexpected problems with old automated analysis scripts that already handle the previous usage. Is there any way to ensure that nobody runs into problems because of this improvement? Changing default name of the output file might be one way to catch user attention. At the very least, g_principal should probably output a NOTE on every usage describing how/why/that the output format has been totally reworked.

#4 Updated by Gerrit Code Review Bot about 3 years ago

Gerrit received a related patchset '1' for Issue #1441.
Uploader: Erik Lindahl ()
Change-Id: Ic1ed9370145d3389ae8f43c2a419765dabf3a66f
Gerrit URL:

#5 Updated by Erik Lindahl about 3 years ago

  • Status changed from New to Fix uploaded

Fixed the output (transposed it), and changed default output names to paxisN.dat with a note in the description.

#6 Updated by Rossen Apostolov about 3 years ago

  • Related to Feature #609: suggestion to add titles to columns in g_principal output files added

#7 Updated by Rossen Apostolov about 3 years ago

shall we add also names to the columns, related to the report in #609 ?

#8 Updated by Mark Abraham about 3 years ago

If you want. Seems straightforward.

#9 Updated by Erik Lindahl about 3 years ago

  • Status changed from Fix uploaded to Resolved
  • % Done changed from 0 to 100

#10 Updated by Erik Lindahl about 3 years ago

  • Status changed from Resolved to Closed

Also available in: Atom PDF