GMX-TUNE_PME(1)

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

💖 GMX-TUNE_PME 💖

okay bestie, welcome to gmx-tune_pme from the GROMACS manual (section 1, iykyk). this is the little tool that figures out how many PME ranks you should be running, and honestly? it's giving personal trainer for your mdrun. let's get into it 🦋

✨ NAME ✨

gmx-tune_pme — time mdrun as a function of PME ranks to optimize settings 💅

🌸 SYNOPSIS 🌸

gmx tune_pme [-s [<.tpr>]] [-cpi [<.cpt>]] [-table [<.xvg>]]
             [-tablep [<.xvg>]] [-tableb [<.xvg>]]
             [-rerun [<.xtc/.trr/...>]] [-ei [<.edi>]] [-p [<.out>]]
             [-err [<.log>]] [-so [<.tpr>]] [-o [<.trr/.cpt/...>]]
             [-x [<.xtc/.tng>]] [-cpo [<.cpt>]]
             [-c [<.gro/.g96/...>]] [-e [<.edr>]] [-g [<.log>]]
             [-dhdl [<.xvg>]] [-field [<.xvg>]] [-tpi [<.xvg>]]
             [-tpid [<.xvg>]] [-eo [<.xvg>]] [-px [<.xvg>]]
             [-pf [<.xvg>]] [-ro [<.xvg>]] [-ra [<.log>]]
             [-rs [<.log>]] [-rt [<.log>]] [-mtx [<.mtx>]]
             [-swap [<.xvg>]] [-bo [<.trr/.cpt/...>]] [-bx [<.xtc>]]
             [-bcpo [<.cpt>]] [-bc [<.gro/.g96/...>]] [-be [<.edr>]]
             [-bg [<.log>]] [-beo [<.xvg>]] [-bdhdl [<.xvg>]]
             [-bfield [<.xvg>]] [-btpi [<.xvg>]] [-btpid [<.xvg>]]
             [-bdevout [<.xvg>]] [-brunav [<.xvg>]] [-bpx [<.xvg>]]
             [-bpf [<.xvg>]] [-bro [<.xvg>]] [-bra [<.log>]]
             [-brs [<.log>]] [-brt [<.log>]] [-bmtx [<.mtx>]]
             [-bdn [<.ndx>]] [-bswap [<.xvg>]] [-xvg <enum>]
             [-mdrun <string>] [-np <int>] [-npstring <enum>]
             [-ntmpi <int>] [-r <int>] [-max <real>] [-min <real>]
             [-npme <enum>] [-fix <int>] [-rmax <real>]
             [-rmin <real>] [-[no]scalevdw] [-ntpr <int>]
             [-steps <int>] [-resetstep <int>] [-nsteps <int>]
             [-[no]launch] [-[no]bench] [-[no]check]
             [-gpu_id <string>] [-[no]append] [-[no]cpnum]
             [-deffnm <string>]

🎀 DESCRIPTION 🎀

so here's the vibe: for a given number -np or -ntmpi of ranks, gmx tune_pme systematically times gmx mdrun with various numbers of PME-only ranks and determines which setting is fastest. iconic behavior honestly ✨ it will also test whether performance can be enhanced by shifting load from the reciprocal to the real space part of the Ewald sum. basically you just pass your .tpr file to gmx tune_pme together with other options for gmx mdrun as needed. that's it, that's the whole assignment 🫶

okay but gmx tune_pme needs to call gmx mdrun, so you gotta tell it how to do that with the argument to the -mdrun parameter. depending how you have built GROMACS, values such as 'gmx mdrun', 'gmx_d mdrun', or 'gmx_mpi mdrun' might be needed. choose wisely bestie 💀

the program that runs MPI programs can be set in the environment variable MPIRUN (defaults to 'mpirun'). ⚠️ note that for certain MPI frameworks, you need to provide a machine- or hostfile. this can also be passed via the MPIRUN variable, e.g.

export MPIRUN="/usr/local/mpirun -machinefile hosts"

note that in such cases it is normally necessary to compile and/or run gmx tune_pme without MPI support, so that it can call the MPIRUN program. lowkey important, don't skip this part 🌸

before doing the actual benchmark runs, gmx tune_pme will do a quick check whether gmx mdrun works as expected with the provided parallel settings — but only if the -check option is activated (and it is the default, so like, it's on unless you turn it off 👑). please call gmx tune_pme with the normal options you would pass to gmx mdrun and add -np for the number of ranks to perform the tests on, or -ntmpi for the number of threads. you can also add -r to repeat each test several times to get better statistics fr fr 📊

gmx tune_pme can test various real space / reciprocal space workloads for you 🌀 with -ntpr you control how many extra .tpr files will be written with enlarged cutoffs and smaller Fourier grids respectively. typically, the first test (number 0) will be with the settings from the input .tpr file; the last test (number ntpr) will have the Coulomb cutoff specified by -rmax with a somewhat smaller PME grid at the same time. in this last test, the Fourier spacing is multiplied with rmax/rcoulomb. the remaining .tpr files will have equally-spaced Coulomb radii (and Fourier spacings) between these extremes. 📐

💡 note that you can set -ntpr to 1 if you just seek the optimal number of PME-only ranks; in that case your input .tpr file will remain unchanged. no cap.

for the benchmark runs, the default of 1000 time steps should suffice for most MD systems. the dynamic load balancing needs about 100 time steps to adapt to local load imbalances, therefore the time step counters are by default reset after 100 steps. for large systems (>1M atoms), as well as for a higher accuracy of the measurements, you should set -resetstep to a higher value. 🔍 from the 'DD' load imbalance entries in the md.log output file you can tell after how many steps the load is sufficiently balanced. example call, bestie:

gmx tune_pme -np 64 -s protein.tpr -launch

after calling gmx mdrun several times, detailed performance information is available in the output file perf.out ✨ note that during the benchmarks, a couple of temporary files are written (options -b*), these will be automatically deleted after each test. so don't get attached 🥲

if you want the simulation to be started automatically with the optimized parameters, use the command line option -launch. 🚀

basic support for GPU-enabled mdrun exists. 🎮 give a string containing the IDs of the GPUs that you wish to use in the optimization in the -gpu_id command-line argument. this works exactly like mdrun -gpu_id, does not imply a mapping, and merely declares the eligible set of GPU devices. gmx-tune_pme will construct calls to mdrun that use this set appropriately. gmx-tune_pme does not support -gputasks. 🙈

✨ OPTIONS ✨

okay bestie, here's the full tea on every single flag. buckle up 🎀

📥 input files, the "what am I even looking at" pile

  • -s [<.tpr>] (topol.tpr) — the portable xdr run input file, aka your whole simulation setup in one tidy little binary 💖
  • -cpi [<.cpt>] (state.cpt) (optional) — a checkpoint file, for when you're continuing instead of starting fresh
  • -table [<.xvg>] (table.xvg) (optional) — an xvgr/xmgr file 👑
  • -tablep [<.xvg>] (tablep.xvg) (optional) — another xvgr/xmgr file 💅
  • -tableb [<.xvg>] (table.xvg) (optional) — yep, also an xvgr/xmgr file 🌸
  • -rerun [<.xtc/.trr/...>] (rerun.xtc) (optional) — trajectory vibes, and it takes a whole rainbow of them: xtc trr cpt gro g96 pdb tng h5md 🦋
  • -ei [<.edi>] (sam.edi) (optional) — ED sampling input, for the essential-dynamics girlies ✨

📤 output files, the "where does it all go" pile

  • -p [<.out>] (perf.out) — a generic output file, no cap
  • -err [<.log>] (bencherr.log) — log file, catching the errors so you don't have to 😭
  • -so [<.tpr>] (tuned.tpr) — a portable xdr run input file — this is the tuned one, the glow-up version 💅
  • -o [<.trr/.cpt/...>] (traj.trr) — full precision trajectory: trr cpt tng h5md 🔥
  • -x [<.xtc/.tng>] (traj_comp.xtc) (optional) — compressed trajectory (tng format or portable xdr format), lil file big energy
  • -cpo [<.cpt>] (state.cpt) (optional) — checkpoint file
  • -c [<.gro/.g96/...>] (confout.gro) — structure file: gro g96 pdb brk ent esp
  • -e [<.edr>] (ener.edr) — energy file ⚡
  • -g [<.log>] (md.log) — log file
  • -dhdl [<.xvg>] (dhdl.xvg) (optional) — xvgr/xmgr file
  • -field [<.xvg>] (field.xvg) (optional) — xvgr/xmgr file
  • -tpi [<.xvg>] (tpi.xvg) (optional) — xvgr/xmgr file
  • -tpid [<.xvg>] (tpidist.xvg) (optional) — xvgr/xmgr file
  • -eo [<.xvg>] (edsam.xvg) (optional) — xvgr/xmgr file
  • -px [<.xvg>] (pullx.xvg) (optional) — xvgr/xmgr file
  • -pf [<.xvg>] (pullf.xvg) (optional) — xvgr/xmgr file
  • -ro [<.xvg>] (rotation.xvg) (optional) — xvgr/xmgr file
  • -ra [<.log>] (rotangles.log) (optional) — log file
  • -rs [<.log>] (rotslabs.log) (optional) — log file
  • -rt [<.log>] (rottorque.log) (optional) — log file
  • -mtx [<.mtx>] (nm.mtx) (optional) — Hessian matrix, fancy
  • -swap [<.xvg>] (swapions.xvg) (optional) — xvgr/xmgr file
  • -bo [<.trr/.cpt/...>] (bench.trr) — full precision benchmark trajectory: trr cpt tng h5md
  • -bx [<.xtc>] (bench.xtc) — compressed benchmark trajectory (portable xdr format): xtc
  • -bcpo [<.cpt>] (bench.cpt) — benchmark checkpoint file
  • -bc [<.gro/.g96/...>] (bench.gro) — benchmark structure file: gro g96 pdb brk ent esp
  • -be [<.edr>] (bench.edr) — benchmark energy file ⚡
  • -bg [<.log>] (bench.log) — benchmark log file
  • -beo [<.xvg>] (benchedo.xvg) (optional) — xvgr/xmgr file
  • -bdhdl [<.xvg>] (benchdhdl.xvg) (optional) — xvgr/xmgr file
  • -bfield [<.xvg>] (benchfld.xvg) (optional) — xvgr/xmgr file
  • -btpi [<.xvg>] (benchtpi.xvg) (optional) — xvgr/xmgr file
  • -btpid [<.xvg>] (benchtpid.xvg) (optional) — xvgr/xmgr file
  • -bdevout [<.xvg>] (benchdev.xvg) (optional) — xvgr/xmgr file
  • -brunav [<.xvg>] (benchrnav.xvg) (optional) — xvgr/xmgr file
  • -bpx [<.xvg>] (benchpx.xvg) (optional) — xvgr/xmgr file
  • -bpf [<.xvg>] (benchpf.xvg) (optional) — xvgr/xmgr file
  • -bro [<.xvg>] (benchrot.xvg) (optional) — xvgr/xmgr file
  • -bra [<.log>] (benchrota.log) (optional) — log file
  • -brs [<.log>] (benchrots.log) (optional) — log file
  • -brt [<.log>] (benchrott.log) (optional) — log file
  • -bmtx [<.mtx>] (benchn.mtx) (optional) — Hessian matrix
  • -bdn [<.ndx>] (bench.ndx) (optional) — index file
  • -bswap [<.xvg>] (benchswp.xvg) (optional) — xvgr/xmgr file

yes bestie that was a LOT of files. you ate that. 💅

🎛️ other options (the actually-interesting part, fr fr)

  • -xvg <enum> (xmgrace) — how to format the xvg plots, your options are: xmgrace, xmgr, none ✨
  • -mdrun <string> — the command line used to run a simulation, like 'gmx mdrun' or 'gmx_mpi mdrun' 👑
  • -np <int> (1) — number of ranks to run the tests on. heads up: it must be > 2 if you want separate PME ranks 🫶
  • -npstring <enum> (np) — the name of the $MPIRUN option that specifies how many ranks to use. your choices: 'np', or 'n'; use 'none' if there's no such option. so the enum is: np, n, none
  • -ntmpi <int> (1) — number of MPI-threads to run the tests on — note this turns MPI & mpirun off 💀
  • -r <int> (2) — repeat each test this many times 🔁
  • -max <real> (0.5) — max fraction of PME ranks to test with
  • -min <real> (0.25) — min fraction of PME ranks to test with
  • -npme <enum> (auto) — within -min and -max, benchmark all possible values for -npme, or just a reasonable subset. auto neglects -min and -max and just picks reasonable values around a guess for npme derived from the .tpr. your options: auto, all, subset
  • -fix <int> (-2) — if it's >= -1, don't vary the number of PME-only ranks at all — just use this fixed value and only vary rcoulomb and the PME grid spacing 🎀
  • -rmax <real> (0) — if >0, the maximal rcoulomb for -ntpr>1 (rcoulomb upscaling results in fourier grid downscaling)
  • -rmin <real> (0) — if >0, the minimal rcoulomb for -ntpr>1
  • -[no]scalevdw (yes) — scale rvdw along with rcoulomb 🌸
  • -ntpr <int> (0) — number of .tpr files to benchmark. create this many files with different rcoulomb scaling factors depending on -rmin and -rmax. if < 1, it automatically chooses how many .tpr files to test 🦋
  • -steps <int> (1000) — take timings for this many steps in the benchmark runs
  • -resetstep <int> (1500) — let dlb equilibrate this many steps before timings are taken (reset cycle counters after this many steps)
  • -nsteps <int> (-1) — if non-negative, perform this many steps in the real run. overwrites nsteps from the .tpr, and add .cpt steps
  • -[no]launch (no) — launch the real simulation after optimization 🚀
  • -[no]bench (yes) — run the benchmarks, or just create the input .tpr files and dip?
  • -[no]check (yes) — before the benchmark runs, check whether mdrun works in parallel
  • -gpu_id <string> — list of unique GPU device IDs that are eligible for use 💜
  • -[no]append (yes) — append to previous output files when continuing from checkpoint instead of adding the simulation part number to all file names (launch only bestie, don't forget)
  • -[no]cpnum (no) — keep and number checkpoint files (launch only)
  • -deffnm <string> — set the default filenames (launch only) 🎀

🌈 SEE ALSO 🌈

more info about GROMACS is available at <http://www.gromacs.org/> — go look, it's giving resources ✨

2026, GROMACS development team 💖

okay that's the whole page bestie, you're officially a tune_pme expert, no cap 🫶 this was GROMACS 2026.4, dated Oct 02, 2026 (the manual page for GMX-TUNE_PME(1)) — now go optimize something and slay 💅✨

📦 where this page comes from