1 .. NOTE: Below is a useful bash one-liner to verify whether there are variables in this file
2 .. no longer present in the code.
3 .. ( export INPUT_FILE='docs/user-guide/environment-variables.rst' GIT_PAGER="cat "; for s in $(grep '^`' $INPUT_FILE | sed 's/`//g' | sed 's/,/ /g'); do count=$(git grep $s | grep -v $INPUT_FILE | wc -l); [ $count -eq 0 ] && printf "%-30s%s\n" $s $count; done ; )
4 .. Another useful one-liner to find undocumentedvariables:
5 .. ( export INPUT_FILE=docs/user-guide/environment-variables.rst; GIT_PAGER="cat "; for ss in `for s in $(git grep getenv | sed 's/.*getenv("\(.*\)".*/\1/' | sort -u | grep '^[A-Z]'); do [ $(grep $s $INPUT_FILE -c) -eq 0 ] && echo $s; done `; do git grep $ss ; done )
10 |Gromacs| programs may be influenced by the use of
11 environment variables. First of all, the variables set in
12 the ``GMXRC`` file are essential for running and
13 compiling |Gromacs|. Some other useful environment variables are
14 listed in the following sections. Most environment variables function
15 by being set in your shell to any non-NULL value. Specific
16 requirements are described below if other values need to be set. You
17 should consult the documentation for your shell for instructions on
18 how to set environment variables in the current shell, or in configuration
19 files for future shells. Note that requirements for exporting
20 environment variables to jobs run under batch control systems vary and
21 you should consult your local documentation for details.
26 Neighbour list dump level; default 0.
29 |Gromacs| automatically backs up old
30 copies of files when trying to write a new file of the same
31 name, and this variable controls the maximum number of
32 backups that will be made, default 99. If set to 0 it fails to
33 run if any output file already exists. And if set to -1 it
34 overwrites any output file without making a backup.
37 if this is explicitly set, no cool quotes
38 will be printed at the end of a program.
41 prevent dumping of step files during
42 (for example) blowing up during failure of constraint
46 dump all configurations to a :ref:`pdb`
47 file that have an interaction energy less than the value set
48 in this environment variable.
51 ``GMX_VIEW_XVG``, ``GMX_VIEW_EPS`` and ``GMX_VIEW_PDB``, commands used to
52 automatically view :ref:`xvg`, :ref:`xpm`, :ref:`eps`
53 and :ref:`pdb` file types, respectively; they default to ``xv``, ``xmgrace``,
54 ``ghostview`` and ``rasmol``. Set to empty to disable
55 automatic viewing of a particular file type. The command will
56 be forked off and run in the background at the same priority
57 as the |Gromacs| tool (which might not be what you want).
58 Be careful not to use a command which blocks the terminal
59 (e.g. ``vi``), since multiple instances might be run.
62 the size of the buffer for file I/O. When set
63 to 0, all file I/O will be unbuffered and therefore very slow.
64 This can be handy for debugging purposes, because it ensures
65 that all files are always totally up-to-date.
68 set display color for logo in :ref:`gmx view`.
70 ``GMX_PRINT_LONGFORMAT``
71 use long float format when printing
75 Applies for computational electrophysiology setups
76 only (see reference manual). The initial structure gets dumped to
77 :ref:`pdb` file, which allows to check whether multimeric channels have
78 the correct PBC representation.
80 ``GMX_TRAJECTORY_IO_VERBOSITY``
81 Defaults to 1, which prints frame count e.g. when reading trajectory
82 files. Set to 0 for quiet operation.
84 ``GMX_ENABLE_GPU_TIMING``
85 Enables GPU timings in the log file for CUDA. Note that CUDA timings
86 are incorrect with multiple streams, as happens with domain
87 decomposition or with both non-bondeds and PME on the GPU (this is
88 also the main reason why they are not turned on by default).
90 ``GMX_DISABLE_GPU_TIMING``
91 Disables GPU timings in the log file for OpenCL.
95 ``GMX_PRINT_DEBUG_LINES``
96 when set, print debugging info on line numbers.
99 number of steps that elapse between dumping
100 the current DD to a PDB file (default 0). This only takes effect
101 during domain decomposition, so it should typically be
102 0 (never), 1 (every DD phase) or a multiple of :mdp:`nstlist`.
104 ``GMX_DD_NST_DUMP_GRID``
105 number of steps that elapse between dumping
106 the current DD grid to a PDB file (default 0). This only takes effect
107 during domain decomposition, so it should typically be
108 0 (never), 1 (every DD phase) or a multiple of :mdp:`nstlist`.
111 general debugging trigger for every domain
112 decomposition (default 0, meaning off). Currently only checks
113 global-local atom index mapping for consistency.
116 over-ride the number of DD pulses used
117 (default 0, meaning no over-ride). Normally 1 or 2.
119 ``GMX_DISABLE_ALTERNATING_GPU_WAIT``
120 disables the specialized polling wait path used to wait for the PME and nonbonded
121 GPU tasks completion to overlap to do the reduction of the resulting forces that
122 arrive first. Setting this variable switches to the generic path with fixed waiting
125 ``GMX_TEST_REQUIRED_NUMBER_OF_DEVICES``
126 sets the number of GPUs required by the test suite. By default, the test suite would
127 fall-back to using CPU if GPUs could not be detected. Set it to a positive integer value
128 to ensure that at least this at least this number of usable GPUs are detected. Default:
129 0 (not testing GPU availability).
131 There are a number of extra environment variables like these
132 that are used in debugging - check the code!
134 Performance and Run Control
135 ---------------------------
136 ``GMX_DO_GALACTIC_DYNAMICS``
137 planetary simulations are made possible (just for fun) by setting
138 this environment variable, which allows setting :mdp:`epsilon-r` to -1 in the :ref:`mdp`
139 file. Normally, :mdp:`epsilon-r` must be greater than zero to prevent a fatal error.
140 See webpage_ for example input files for a planetary simulation.
142 ``GMX_BONDED_NTHREAD_UNIFORM``
143 Value of the number of threads per rank from which to switch from uniform
144 to localized bonded interaction distribution; optimal value dependent on
145 system and hardware, default value is 4.
147 ``GMX_GPU_NB_EWALD_TWINCUT``
148 force the use of twin-range cutoff kernel even if :mdp:`rvdw` equals
149 :mdp:`rcoulomb` after PP-PME load balancing. The switch to twin-range kernels is automated,
150 so this variable should be used only for benchmarking.
152 ``GMX_GPU_NB_ANA_EWALD``
153 force the use of analytical Ewald kernels. Should be used only for benchmarking.
155 ``GMX_GPU_NB_TAB_EWALD``
156 force the use of tabulated Ewald kernels. Should be used only for benchmarking.
158 ``GMX_DISABLE_CUDA_TIMING``
159 Deprecated. Use ``GMX_DISABLE_GPU_TIMING`` instead.
162 perform domain decomposition halo exchange communication operations (on coordinate and force buffers)
163 directly on GPU memory spaces, without the staging of data through CPU memory, where possible.
165 ``GMX_GPU_PME_PP_COMMS``
166 when the simulation uses a separate PME rank, perform communication operations between PP and PME rank
167 (for coordinate and force buffers) directly on GPU memory spaces, without the staging of data through CPU
168 memory, where possible.
170 ``GMX_GPU_SYCL_NO_SYNCHRONIZE``
171 disable synchronizations between different GPU streams in SYCL build, instead relying on SYCL runtime to
172 do scheduling based on data dependencies. Experimental.
175 times all code during runs. Incompatible with threads.
177 ``GMX_CYCLE_BARRIER``
178 calls MPI_Barrier before each cycle start/stop call.
181 build domain decomposition cells in the order
182 (z, y, x) rather than the default (x, y, z).
184 ``GMX_DD_USE_SENDRECV2``
185 during constraint and vsite communication, use a pair
186 of ``MPI_Sendrecv`` calls instead of two simultaneous non-blocking calls
187 (default 0, meaning off). Might be faster on some MPI implementations.
189 ``GMX_DLB_BASED_ON_FLOPS``
190 do domain-decomposition dynamic load balancing based on flop count rather than
191 measured time elapsed (default 0, meaning off).
192 This makes the load balancing reproducible, which can be useful for debugging purposes.
193 A value of 1 uses the flops; a value > 1 adds (value - 1)*5% of noise to the flops to increase the imbalance and the scaling.
195 ``GMX_DLB_MAX_BOX_SCALING``
196 maximum percentage box scaling permitted per domain-decomposition
197 load-balancing step (default 10)
199 ``GMX_DD_RECORD_LOAD``
200 record DD load statistics for reporting at end of the run (default 1, meaning on)
202 ``GMX_DETAILED_PERF_STATS``
203 when set, print slightly more detailed performance information
204 to the :ref:`log` file. The resulting output is the way performance summary is reported in versions
205 4.5.x and thus may be useful for anyone using scripts to parse :ref:`log` files or standard output.
207 ``GMX_DISABLE_SIMD_KERNELS``
208 disables architecture-specific SIMD-optimized (SSE2, SSE4.1, AVX, etc.)
209 non-bonded kernels thus forcing the use of plain C kernels.
211 ``GMX_DISABLE_GPU_TIMING``
212 timing of asynchronously executed GPU operations can have a
213 non-negligible overhead with short step times. Disabling timing can improve performance in these cases.
215 ``GMX_DISABLE_GPU_DETECTION``
216 when set, disables GPU detection even if :ref:`gmx mdrun` was compiled
219 ``GMX_GPU_APPLICATION_CLOCKS``
220 setting this variable to a value of "0", "ON", or "DISABLE" (case insensitive)
221 allows disabling the CUDA GPU allication clock support.
223 ``GMX_DISRE_ENSEMBLE_SIZE``
224 the number of systems for distance restraint ensemble
225 averaging. Takes an integer value.
228 emulate GPU runs by using algorithmically equivalent CPU reference code instead of
229 GPU-accelerated functions. As the CPU code is slow, it is intended to be used only for debugging purposes.
232 disable exiting upon encountering a corrupted frame in an :ref:`edr`
233 file, allowing the use of all frames up until the corruption.
236 update forces when invoking ``mdrun -rerun``.
238 ``GMX_FORCE_UPDATE_DEFAULT_GPU``
239 Force update to run on the GPU by default, overriding the ``mdrun -update auto`` option. Works similar to setting
240 ``mdrun -update gpu``, but (1) falls back to the CPU code-path, if set with input that is not supported and
241 (2) can be used to run update on GPUs in multi-rank cases. The latter case should be
242 considered experimental since it lacks substantial testing. Also, GPU update is only supported with the GPU direct
243 communications and ``GMX_FORCE_UPDATE_DEFAULT_GPU`` variable should be set simultaneously with ``GMX_GPU_DD_COMMS``
244 and ``GMX_GPU_PME_PP_COMMS`` environment variables in multi-rank case. Does not override ``mdrun -update cpu``.
247 set in the same way as ``mdrun -gpu_id``, ``GMX_GPU_ID``
248 allows the user to specify different GPU IDs for different ranks, which can be useful for selecting different
249 devices on different compute nodes in a cluster. Cannot be used in conjunction with ``mdrun -gpu_id``.
252 set in the same way as ``mdrun -gputasks``, ``GMX_GPUTASKS`` allows the mapping
253 of GPU tasks to GPU device IDs to be different on different ranks, if e.g. the MPI
254 runtime permits this variable to be different for different ranks. Cannot be used
255 in conjunction with ``mdrun -gputasks``. Has all the same requirements as ``mdrun -gputasks``.
257 ``GMX_GPU_DISABLE_COMPATIBILITY_CHECK``
258 Disables the hardware compatibility check in OpenCL and SYCL. Useful for developers
259 and allows testing the OpenCL/SYCL kernels on non-supported platforms without source code modification.
261 ``GMX_IGNORE_FSYNC_FAILURE_ENV``
262 allow :ref:`gmx mdrun` to continue even if
266 when set to a floating-point value, overrides the default tolerance of
267 1e-5 for force-field floating-point parameters.
269 ``GMX_MAXCONSTRWARN``
270 if set to -1, :ref:`gmx mdrun` will
271 not exit if it produces too many LINCS warnings.
274 neighbor list balancing parameter used when running on GPU. Sets the
275 target minimum number pair-lists in order to improve multi-processor load-balance for better
276 performance with small simulation systems. Must be set to a non-negative integer,
277 the 0 value disables list splitting.
278 The default value is optimized for supported GPUs
279 therefore changing it is not necessary for normal usage, but it can be useful on future architectures.
282 use neighbor list and kernels based on charge groups.
285 when set, print detailed neighbor search cycle counting.
287 ``GMX_NBNXN_EWALD_ANALYTICAL``
288 force the use of analytical Ewald non-bonded kernels,
289 mutually exclusive of ``GMX_NBNXN_EWALD_TABLE``.
291 ``GMX_NBNXN_EWALD_TABLE``
292 force the use of tabulated Ewald non-bonded kernels,
293 mutually exclusive of ``GMX_NBNXN_EWALD_ANALYTICAL``.
295 ``GMX_NBNXN_SIMD_2XNN``
296 force the use of 2x(N+N) SIMD CPU non-bonded kernels,
297 mutually exclusive of ``GMX_NBNXN_SIMD_4XN``.
299 ``GMX_NBNXN_SIMD_4XN``
300 force the use of 4xN SIMD CPU non-bonded kernels,
301 mutually exclusive of ``GMX_NBNXN_SIMD_2XNN``.
303 ``GMX_NOOPTIMIZEDKERNELS``
304 deprecated, use ``GMX_DISABLE_SIMD_KERNELS`` instead.
306 ``GMX_NO_CART_REORDER``
307 used in initializing domain decomposition communicators. Rank reordering
308 is default, but can be switched off with this environment variable.
310 ``GMX_NO_LJ_COMB_RULE``
311 force the use of LJ paremeter lookup instead of using combination rules
312 in the non-bonded kernels.
314 ``GMX_NO_INT``, ``GMX_NO_TERM``, ``GMX_NO_USR1``
315 disable signal handlers for SIGINT,
316 SIGTERM, and SIGUSR1, respectively.
319 do not use separate inter- and intra-node communicators.
322 skip non-bonded calculations; can be used to estimate the possible
323 performance gain from adding a GPU accelerator to the current hardware setup -- assuming that this is
324 fast enough to complete the non-bonded calculations while the CPU does bonded force and PME computation.
325 Freezing the particles will be required to stop the system blowing up.
327 ``GMX_PULL_PARTICIPATE_ALL``
328 disable the default heuristic for when to use a separate pull MPI communicator (at >=32 ranks).
331 shell positions are not predicted.
333 ``GMX_NO_UPDATEGROUPS``
334 turns off update groups. May allow for a decomposition of more
335 domains for small systems at the cost of communication during update.
338 the ideal number of charge groups per neighbor searching grid cell is hard-coded
339 to a value of 10. Setting this environment variable to any other integer value overrides this hard-coded
342 ``GMX_PME_NUM_THREADS``
343 set the number of OpenMP or PME threads; overrides the default set by
344 :ref:`gmx mdrun`; can be used instead of the ``-npme`` command line option,
345 also useful to set heterogeneous per-process/-node thread count.
348 use P3M-optimized influence function instead of smooth PME B-spline interpolation.
350 ``GMX_PME_THREAD_DIVISION``
351 PME thread division in the format "x y z" for all three dimensions. The
352 sum of the threads in each dimension must equal the total number of PME threads (set in
353 :envvar:`GMX_PME_NTHREADS`).
356 if the number of domain decomposition cells is set to 1 for both x and y,
357 decompose PME in one dimension.
359 ``GMX_REQUIRE_SHELL_INIT``
360 require that shell positions are initiated.
362 ``GMX_REQUIRE_TABLES``
363 require the use of tabulated Coulombic
364 and van der Waals interactions.
367 should contain multiple masses used for test particle insertion into a cavity.
368 The center of mass of the last atoms is used for insertion into the cavity.
371 use graph for bonded interactions.
373 ``GMX_VERLET_BUFFER_RES``
374 resolution of buffer size in Verlet cutoff scheme. The default value is
375 0.001, but can be overridden with this environment variable.
378 Not strictly a |Gromacs| environment variable, but on large machines
379 the hwloc detection can take a few seconds if you have lots of MPI processes.
380 If you run the hwloc command :command:`lstopo out.xml` and set this environment
381 variable to point to the location of this file, the hwloc library will use
382 the cached information instead, which can be faster.
385 the ``mpirun`` command used by :ref:`gmx tune_pme`.
388 the :ref:`gmx mdrun` command used by :ref:`gmx tune_pme`.
390 ``GMX_DISABLE_DYNAMICPRUNING``
391 disables dynamic pair-list pruning. Note that :ref:`gmx mdrun` will
392 still tune nstlist to the optimal value picked assuming dynamic pruning. Thus
393 for good performance the -nstlist option should be used.
395 ``GMX_NSTLIST_DYNAMICPRUNING``
396 overrides the dynamic pair-list pruning interval chosen heuristically
397 by mdrun. Values should be between the pruning frequency value
398 (1 for CPU and 2 for GPU) and :mdp:`nstlist` ``- 1``.
400 .. _opencl-management:
404 Currently, several environment variables exist that help customize some aspects
405 of the OpenCL_ version of |Gromacs|. They are mostly related to the runtime
406 compilation of OpenCL kernels, but they are also used in device selection.
408 ``GMX_OCL_NOGENCACHE``
409 If set, disable caching for OpenCL kernel builds. Caching is
410 normally useful so that future runs can re-use the compiled
411 kernels from previous runs. Currently, caching is always
412 disabled, until we solve concurrency issues.
415 Enable OpenCL binary caching. Only intended to be used for
416 development and (expert) testing as neither concurrency
417 nor cache invalidation is implemented safely!
419 ``GMX_OCL_NOFASTGEN``
420 If set, generate and compile all algorithm flavors, otherwise
421 only the flavor required for the simulation is generated and
424 ``GMX_OCL_DISABLE_FASTMATH``
425 Prevents the use of ``-cl-fast-relaxed-math`` compiler option.
428 If defined, the OpenCL build log is always written to the
429 mdrun log file. Otherwise, the build log is written to the
430 log file only when an error occurs.
433 If defined, it enables verbose mode for OpenCL kernel build.
434 Currently available only for NVIDIA GPUs. See ``GMX_OCL_DUMP_LOG``
435 for details about how to obtain the OpenCL build log.
437 ``GMX_OCL_DUMP_INTERM_FILES``
439 If defined, intermediate language code corresponding to the
440 OpenCL build process is saved to file. Caching has to be
441 turned off in order for this option to take effect (see
442 ``GMX_OCL_NOGENCACHE``).
444 - NVIDIA GPUs: PTX code is saved in the current directory
445 with the name ``device_name.ptx``
446 - AMD GPUs: ``.IL/.ISA`` files will be created for each OpenCL
447 kernel built. For details about where these files are
448 created check AMD documentation for ``-save-temps`` compiler
452 Use in conjunction with ``OCL_FORCE_CPU`` or with an AMD device.
453 It adds the debug flag to the compiler options (-g).
456 Disable optimisations. Adds the option ``cl-opt-disable`` to the
459 ``GMX_OCL_FORCE_CPU``
460 Force the selection of a CPU device instead of a GPU. This
461 exists only for debugging purposes. Do not expect |Gromacs| to
462 function properly with this option on, it is solely for the
463 simplicity of stepping in a kernel and see what is happening.
465 ``GMX_OCL_DISABLE_I_PREFETCH``
466 Disables i-atom data (type or LJ parameter) prefetch allowing
469 ``GMX_OCL_ENABLE_I_PREFETCH``
470 Enables i-atom data (type or LJ parameter) prefetch allowing
471 testing on platforms where this behavior is not default.
473 ``GMX_OCL_FILE_PATH``
474 Use this parameter to force |Gromacs| to load the OpenCL
475 kernels from a custom location. Use it only if you want to
476 override |Gromacs| default behavior, or if you want to test
479 ``GMX_OCL_SHOW_DIAGNOSTICS``
480 Use Intel OpenCL extension to show additional runtime performance
483 Analysis and Core Functions
484 ---------------------------
487 used by :ref:`gmx do_dssp` to point to the ``dssp``
488 executable (not just its path).
490 ``GMX_DIPOLE_SPACING``
491 spacing used by :ref:`gmx dipoles`.
494 sets the maximum number of residues to be renumbered by
495 :ref:`gmx grompp`. A value of -1 indicates all residues should be renumbered.
497 ``GMX_NO_FFRTP_TER_RENAME``
498 Some force fields (like AMBER) use specific names for N- and C-
499 terminal residues (NXXX and CXXX) as :ref:`rtp` entries that are normally renamed. Setting
500 this environment variable disables this renaming.
503 name of X11 font used by :ref:`gmx view`.
506 the time unit used in output files, can be
507 anything in fs, ps, ns, us, ms, s, m or h.
510 name of the ``multiprot`` executable, used by the
511 contributed program ``do_multiprot``.
514 number of CPUs to be used for Gaussian QM calculation
517 name of the ``total`` executable used by the contributed
518 ``do_shift`` program.
521 make :ref:`gmx energy` and :ref:`gmx eneconv`
525 where to find VMD plug-ins. Needed to be
526 able to read file formats recognized only by a VMD plug-in.
529 base path of VMD installation.
532 sets viewer to ``xmgr`` (deprecated) instead of ``xmgrace``.