GMX-CLUSTER(1)

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

💖 GMX-CLUSTER(1) — the GROMACS girlies' guide to clustering 💖

okay bestie, pull up a chair, because this is gmx-cluster, the GROMACS manual page, and she is serving 🌸 this is a GROMACS tool, section 1 of the manual, and I am about to make clustering structures make sense to you fr fr 🫶

✨ NAME ✨

gmx-cluster — cluster structures. that's it, that's the whole thing, that's the vibe 💅

🦋 SYNOPSIS 🦋

gmx cluster [-f [<.xtc/.trr/...>]] [-s [<.tpr/.gro/...>]] [-n [<.ndx>]]
            [-dm [<.xpm>]] [-om [<.xpm>]] [-o [<.xpm>]] [-g [<.log>]]
            [-dist [<.xvg>]] [-ev [<.xvg>]] [-conv [<.xvg>]]
            [-sz [<.xvg>]] [-tr [<.xpm>]] [-ntr [<.xvg>]]
            [-clid [<.xvg>]] [-cl [<.xtc/.trr/...>]]
            [-clndx [<.ndx>]] [-b <time>] [-e <time>] [-dt <time>]
            [-tu <enum>] [-[no]w] [-xvg <enum>] [-[no]dista]
            [-nlevels <int>] [-cutoff <real>] [-[no]fit]
            [-max <real>] [-skip <int>] [-[no]av] [-wcl <int>]
            [-nst <int>] [-rmsmin <real>] [-method <enum>]
            [-minstruct <int>] [-[no]binary] [-M <int>] [-P <int>]
            [-seed <int>] [-niter <int>] [-nrandom <int>]
            [-kT <real>] [-[no]pbc]

like, yes, it's a lot of flags, but every single one of them is your friend 🌈

🌸 DESCRIPTION 🌸

gmx cluster can cluster structures using several different methods. Distances between structures can either be figured out from a trajectory, or read straight out of an .xpm matrix file — that's what the -dm option is for, iykyk 💫 To define the distance between structures you've got options: RMS deviation after fitting, or RMS deviation of atom-pair distances. pick your fighter.

here's the method roster, bestie:

  • single linkage: add a structure to a cluster when its distance to any element of the cluster is less than cutoff.
  • Jarvis Patrick: add a structure to a cluster when this structure and a structure in the cluster have each other as neighbors and they have at least P neighbors in common. A structure's neighbors are the M closest structures, or all structures within cutoff.
  • Monte Carlo: reorder the RMSD matrix using Monte Carlo so that the order of the frames uses the smallest possible increments. with this you can make a smooth animation going from one structure to another with the largest possible (e.g.) RMSD between them — but the intermediate steps should be as small as possible. applications could be visualizing a potential of mean force ensemble of simulations, or a pulling simulation. obviously the user has to prepare the trajectory well (e.g. by not superimposing frames). you can inspect the final result visually by looking at the matrix .xpm file, which should vary smoothly from bottom to top 👀
  • diagonalization: diagonalize the RMSD matrix. yeah. that's it. she's simple like that 💅
  • gromos: use the algorithm described in Daura et al. (Angew. Chem. Int. Ed. 1999, 38, pp 236-240). count number of neighbors using cut-off, take the structure with the largest number of neighbors together with all its neighbors as a cluster, and eliminate it from the pool of clusters. repeat for the remaining structures in the pool. iconic, honestly 🎀

okay so when the clustering algorithm assigns each structure to exactly one cluster (that's single linkage, Jarvis Patrick and gromos) and a trajectory file is supplied, then one of these gets written to a trajectory file: the structure with the smallest average distance to the others, or the average structure, or all structures for each cluster. and when it's writing all structures, separate numbered files are made for each cluster. organized queen ✨

💖 the two files that ALWAYS show up 💖

these two are non-negotiable, she writes them every single time:

  • -o writes the RMSD values in the upper left half of the matrix, and a graphical depiction of the clusters in the lower right half. when -minstruct = 1 the graphical depiction is black when two structures are in the same cluster. when -minstruct > 1 different colors will be used for each cluster 🖤🌈
  • -g writes information on the options used, plus a detailed list of all clusters and their members 📝

⭐ and then the optional glow-ups ⭐

on top of that, a number of optional output files can be written:

  • -dist writes the RMSD distribution.
  • -ev writes the eigenvectors of the RMSD matrix diagonalization.
  • -sz writes the cluster sizes.
  • -tr writes a matrix of the number transitions between cluster pairs.
  • -ntr writes the total number of transitions to or from each cluster.
  • -clid writes the cluster number as a function of time.
  • -clndx writes the frame numbers corresponding to the clusters to the specified index file, to be read into trjconv. 🫶
  • -cl writes the average (with option -av) or the central structure of each cluster, or writes numbered files with cluster members for a selected set of clusters (with option -wcl, depends on -nst and -rmsmin). the center of a cluster is the structure with the smallest average RMSD from all other structures of the cluster. main character chosen behavior, honestly 👑

💅 OPTIONS 💅

🌟 Options to specify input files 🌟

  • -f [<.xtc/.trr/...>] (traj.xtc) (Optional) — Trajectory: xtc trr cpt gro g96 pdb tng h5md
  • -s [<.tpr/.gro/...>] (topol.tpr) — Structure+mass(db): tpr gro g96 pdb brk ent
  • -n [<.ndx>] (index.ndx) (Optional) — Index file
  • -dm [<.xpm>] (rmsd.xpm) (Optional) — X PixMap compatible matrix file

🎀 Options to specify output files 🎀

  • -om [<.xpm>] (rmsd-raw.xpm) — X PixMap compatible matrix file
  • -o [<.xpm>] (rmsd-clust.xpm) — X PixMap compatible matrix file
  • -g [<.log>] (cluster.log) — Log file
  • -dist [<.xvg>] (rmsd-dist.xvg) (Optional) — xvgr/xmgr file
  • -ev [<.xvg>] (rmsd-eig.xvg) (Optional) — xvgr/xmgr file
  • -conv [<.xvg>] (mc-conv.xvg) (Optional) — xvgr/xmgr file
  • -sz [<.xvg>] (clust-size.xvg) (Optional) — xvgr/xmgr file
  • -tr [<.xpm>] (clust-trans.xpm) (Optional) — X PixMap compatible matrix file
  • -ntr [<.xvg>] (clust-trans.xvg) (Optional) — xvgr/xmgr file
  • -clid [<.xvg>] (clust-id.xvg) (Optional) — xvgr/xmgr file
  • -cl [<.xtc/.trr/...>] (clusters.pdb) (Optional) — Trajectory: xtc trr cpt gro g96 pdb tng h5md
  • -clndx [<.ndx>] (clusters.ndx) (Optional) — Index 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 frame when t MOD dt = first time (default unit ps)
  • -tu <enum> (ps) — Unit for time values: fs, ps, ns, us, ms, s
  • -[no]w (no) — View output .xvg, .xpm, .eps and .pdb files
  • -xvg <enum> (xmgrace) — xvg plot formatting: xmgrace, xmgr, none
  • -[no]dista (no) — Use RMSD of distances instead of RMS deviation
  • -nlevels <int> (40) — Discretize RMSD matrix in this number of levels
  • -cutoff <real> (0.1) — RMSD cut-off (nm) for two structures to be neighbor
  • -[no]fit (yes) — Use least squares fitting before RMSD calculation
  • -max <real> (-1) — Maximum level in RMSD matrix
  • -skip <int> (1) — Only analyze every nr-th frame
  • -[no]av (no) — Write average instead of middle structure for each cluster
  • -wcl <int> (0) — Write the structures for this number of clusters to numbered files
  • -nst <int> (1) — Only write all structures if more than this number of structures per cluster
  • -rmsmin <real> (0) — minimum rms difference with rest of cluster for writing structures
  • -method <enum> (linkage) — Method for cluster determination: linkage, jarvis-patrick, monte-carlo, diagonalization, gromos
  • -minstruct <int> (1) — Minimum number of structures in cluster for coloring in the .xpm file
  • -[no]binary (no) — Treat the RMSD matrix as consisting of 0 and 1, where the cut-off is given by -cutoff
  • -M <int> (10) — Number of nearest neighbors considered for Jarvis-Patrick algorithm, 0 is use cutoff
  • -P <int> (3) — Number of identical nearest neighbors required to form a cluster
  • -seed <int> (0) — Random number seed for Monte Carlo clustering algorithm (0 means generate)
  • -niter <int> (10000) — Number of iterations for MC
  • -nrandom <int> (0) — The first iterations for MC may be done complete random, to shuffle the frames
  • -kT <real> (0.001) — Boltzmann weighting factor for Monte Carlo optimization (zero turns off uphill steps)
  • -[no]pbc (yes) — PBC check

🧚 SEE ALSO 🧚

More information about GROMACS is available at <http://www.gromacs.org/>. ✨

2026, GROMACS development team

and that's the whole page, bestie 💖 this was GMX-CLUSTER(1) from GROMACS 2026.4, dated Oct 02, 2026 — copyright 2026, GROMACS development team. go forth and cluster, you absolute icon 🦋💅⭐

📦 where this page comes from