1 .. Note that this must be a single rst file in order for Sphinx
2 to build into into a single plain-text file to place in the
13 Introduction to building |Gromacs|
14 ----------------------------------
16 These instructions pertain to building |Gromacs|
17 |version|. You might also want to check the `up-to-date installation instructions`_.
19 Quick and dirty installation
20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
21 1. Get the latest version of your C and C++ compilers.
22 2. Check that you have CMake version |CMAKE_MINIMUM_REQUIRED_VERSION| or later.
23 3. Get and unpack the latest version of the |Gromacs| tarball.
24 4. Make a separate build directory and change to it.
25 5. Run ``cmake`` with the path to the source as an argument
26 6. Run ``make``, ``make check``, and ``make install``
27 7. Source ``GMXRC`` to get access to |Gromacs|
29 Or, as a sequence of commands to execute:
33 tar xfz gromacs-|version|.tar.gz
37 cmake .. -DGMX_BUILD_OWN_FFTW=ON -DREGRESSIONTEST_DOWNLOAD=ON
41 source /usr/local/gromacs/bin/GMXRC
43 This will download and build first the prerequisite FFT library
44 followed by |Gromacs|. If you already have FFTW installed, you can
45 remove that argument to ``cmake``. Overall, this build of |Gromacs|
46 will be correct and reasonably fast on the machine upon which
47 ``cmake`` ran. On another machine, it may not run, or may not run
48 fast. If you want to get the maximum value for your hardware with
49 |Gromacs|, you will have to read further. Sadly, the interactions of
50 hardware, libraries, and compilers are only going to continue to get
53 Quick and dirty cluster installation
54 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
56 On a cluster where users are expected to be running across multiple
57 nodes using MPI, make one installation similar to the above, and
58 another using ``-DGMX_MPI=on``.
59 The latter will install binaries and libraries named using
60 a default suffix of ``_mpi`` ie ``gmx_mpi``. Hence it is safe
61 and common practice to install this into the same location where
62 the non-MPI build is installed.
67 As above, and with further details below, but you should consider
68 using the following `CMake options`_ with the
69 appropriate value instead of ``xxx`` :
71 * ``-DCMAKE_C_COMPILER=xxx`` equal to the name of the C99 `Compiler`_ you wish to use (or the environment variable ``CC``)
72 * ``-DCMAKE_CXX_COMPILER=xxx`` equal to the name of the C++17 `compiler`_ you wish to use (or the environment variable ``CXX``)
73 * ``-DGMX_MPI=on`` to build using `MPI support`_
74 * ``-DGMX_GPU=CUDA`` to build with NVIDIA CUDA support enabled.
75 * ``-DGMX_GPU=OpenCL`` to build with OpenCL_ support enabled.
76 * ``-DGMX_SIMD=xxx`` to specify the level of `SIMD support`_ of the node on which |Gromacs| will run
77 * ``-DGMX_DOUBLE=on`` to build |Gromacs| in double precision (slower, and not normally useful)
78 * ``-DCMAKE_PREFIX_PATH=xxx`` to add a non-standard location for CMake to `search for libraries, headers or programs`_
79 * ``-DCMAKE_INSTALL_PREFIX=xxx`` to install |Gromacs| to a `non-standard location`_ (default ``/usr/local/gromacs``)
80 * ``-DBUILD_SHARED_LIBS=off`` to turn off the building of shared libraries to help with `static linking`_
81 * ``-DGMX_FFT_LIBRARY=xxx`` to select whether to use ``fftw3``, ``mkl`` or ``fftpack`` libraries for `FFT support`_
82 * ``-DCMAKE_BUILD_TYPE=Debug`` to build |Gromacs| in debug mode
84 Building older versions
85 ^^^^^^^^^^^^^^^^^^^^^^^
87 Installation instructions for old |Gromacs| versions can be found at
88 the |Gromacs| `documentation page
89 <http://manual.gromacs.org/documentation>`_.
97 |Gromacs| can be compiled for many operating systems and
98 architectures. These include any distribution of Linux, Mac OS X or
99 Windows, and architectures including x86, AMD64/x86-64, several
100 PowerPC including POWER8, ARM v8, and SPARC VIII.
105 |Gromacs| can be compiled on any platform with ANSI C99 and C++17
106 compilers, and their respective standard C/C++ libraries. Good
107 performance on an OS and architecture requires choosing a good
108 compiler. We recommend gcc, because it is free, widely available and
109 frequently provides the best performance.
111 You should strive to use the most recent version of your
112 compiler. Since we require full C++17 support the minimum supported
113 compiler versions are
115 * GNU (gcc/libstdc++) 7
117 * LLVM (clang/libc++) 5
118 * Microsoft (MSVC) 2017 15.7
120 Other compilers may work (Cray, Pathscale, older clang) but do
121 not offer competitive performance. We recommend against PGI because
122 the performance with C++ is very bad.
124 The xlc compiler is not supported and version 16.1 does not compile on
125 POWER architectures for |Gromacs|\ -\ |version|. We recommend to use
126 the gcc compiler instead, as it is being extensively tested.
128 You may also need the most recent version of other compiler toolchain
129 components beside the compiler itself (e.g. assembler or linker);
130 these are often shipped by your OS distribution's binutils package.
132 C++17 support requires adequate support in both the compiler and the
133 C++ library. The gcc and MSVC compilers include their own standard
134 libraries and require no further configuration. If your vendor's
135 compiler also manages the standard library library via compiler flags,
136 these will be honored. For configuration of other compilers, read on.
138 On Linux, both the Intel and clang compiler use the libstdc++ which
139 comes with gcc as the default C++ library. For |Gromacs|, we require
140 the compiler to support libstc++ version 7.1 or higher. To select a
141 particular libstdc++ library, provide the path to g++ with
142 ``-DGMX_GPLUSPLUS_PATH=/path/to/g++``.
144 On Windows with the Intel compiler, the MSVC standard library is used,
145 and at least MSVC 2017 15.7 is required. Load the environment variables with
148 To build with clang and llvm's libcxx standard library, use
149 ``-DCMAKE_CXX_FLAGS=-stdlib=libc++``.
151 If you are running on Mac OS X, the best option is the Intel
152 compiler. Both clang and gcc will work, but they produce lower
153 performance and each have some shortcomings. clang 3.8 now offers
154 support for OpenMP, and so may provide decent performance.
156 For all non-x86 platforms, your best option is typically to use gcc or
157 the vendor's default or recommended compiler, and check for
158 specialized information below.
160 For updated versions of gcc to add to your Linux OS, see
162 * Ubuntu: `Ubuntu toolchain ppa page`_
163 * RHEL/CentOS: `EPEL page`_ or the RedHat Developer Toolset
165 Compiling with parallelization options
166 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
168 For maximum performance you will need to examine how you will use
169 |Gromacs| and what hardware you plan to run on. Often OpenMP_
170 parallelism is an advantage for |Gromacs|, but support for this is
171 generally built into your compiler and detected automatically.
178 |Gromacs| has excellent support for NVIDIA GPUs supported via CUDA.
179 On Linux, NVIDIA CUDA_ toolkit with minimum version |REQUIRED_CUDA_VERSION|
180 is required, and the latest version is strongly encouraged. NVIDIA GPUs with at
181 least NVIDIA compute capability |REQUIRED_CUDA_COMPUTE_CAPABILITY| are
182 required. You are strongly recommended to
183 get the latest CUDA version and driver that supports your hardware, but
184 beware of possible performance regressions in newer CUDA versions on
186 While some CUDA compilers (nvcc) might not
187 officially support recent versions of gcc as the back-end compiler, we
188 still recommend that you at least use a gcc version recent enough to
189 get the best SIMD support for your CPU, since |Gromacs| always runs some
190 code on the CPU. It is most reliable to use the same C++ compiler
191 version for |Gromacs| code as used as the host compiler for nvcc.
193 To make it possible to use other accelerators, |Gromacs| also includes
194 OpenCL_ support. The minimum OpenCL version required is
195 |REQUIRED_OPENCL_MIN_VERSION| and only 64-bit implementations are supported.
196 The current OpenCL implementation is recommended for
197 use with GCN-based AMD GPUs, and on Linux we recommend the ROCm runtime.
198 Intel integrated GPUs are supported with the Neo drivers.
199 OpenCL is also supported with NVIDIA GPUs, but using
200 the latest NVIDIA driver (which includes the NVIDIA OpenCL runtime) is
201 recommended. Also note that there are performance limitations (inherent
202 to the NVIDIA OpenCL runtime).
203 It is not possible to configure both CUDA and OpenCL
204 support in the same build of |Gromacs|, nor to support both
205 Intel and other vendors' GPUs with OpenCL. A 64-bit implementation
206 of OpenCL is required and therefore OpenCL is only supported on 64-bit platforms.
213 |Gromacs| can run in parallel on multiple cores of a single
214 workstation using its built-in thread-MPI. No user action is required
215 in order to enable this.
217 If you wish to run in parallel on multiple machines across a network,
218 you will need to have an MPI library installed that supports the MPI
219 2.0 standard. That's true for any MPI library version released since
220 about 2009, but the |Gromacs| team recommends the latest version (for
221 best performance) of either your vendor's library, OpenMPI_ or MPICH_.
223 To compile with MPI set your compiler to the normal (non-MPI) compiler
224 and add ``-DGMX_MPI=on`` to the cmake options. It is possible to set
225 the compiler to the MPI compiler wrapper but it is neither necessary
231 |Gromacs| builds with the CMake build system, requiring at least
232 version |CMAKE_MINIMUM_REQUIRED_VERSION|. You can check whether
233 CMake is installed, and what version it is, with ``cmake
234 --version``. If you need to install CMake, then first check whether
235 your platform's package management system provides a suitable version,
236 or visit the `CMake installation page`_ for pre-compiled binaries,
237 source code and installation instructions. The |Gromacs| team
238 recommends you install the most recent version of CMake you can.
242 Fast Fourier Transform library
243 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
245 Many simulations in |Gromacs| make extensive use of fast Fourier
246 transforms, and a software library to perform these is always
247 required. We recommend FFTW_ (version 3 or higher only) or Intel
248 MKL_. The choice of library can be set with ``cmake
249 -DGMX_FFT_LIBRARY=<name>``, where ``<name>`` is one of ``fftw3``,
250 ``mkl``, or ``fftpack``. FFTPACK is bundled with |Gromacs| as a
251 fallback, and is acceptable if simulation performance is not a
252 priority. When choosing MKL, |Gromacs| will also use MKL for BLAS and
253 LAPACK (see `linear algebra libraries`_). Generally, there is no
254 advantage in using MKL with |Gromacs|, and FFTW is often faster.
255 With PME GPU offload support using CUDA, a GPU-based FFT library
256 is required. The CUDA-based GPU FFT library cuFFT is part of the
257 CUDA toolkit (required for all CUDA builds) and therefore no additional
258 software component is needed when building with CUDA GPU acceleration.
263 FFTW_ is likely to be available for your platform via its package
264 management system, but there can be compatibility and significant
265 performance issues associated with these packages. In particular,
266 |Gromacs| simulations are normally run in "mixed" floating-point
267 precision, which is suited for the use of single precision in
268 FFTW. The default FFTW package is normally in double
269 precision, and good compiler options to use for FFTW when linked to
270 |Gromacs| may not have been used. Accordingly, the |Gromacs| team
273 * that you permit the |Gromacs| installation to download and
274 build FFTW from source automatically for you (use
275 ``cmake -DGMX_BUILD_OWN_FFTW=ON``), or
276 * that you build FFTW from the source code.
278 If you build FFTW from source yourself, get the most recent version
279 and follow the `FFTW installation guide`_. Choose the precision for
280 FFTW (i.e. single/float vs. double) to match whether you will later
281 use mixed or double precision for |Gromacs|. There is no need to
282 compile FFTW with threading or MPI support, but it does no harm. On
283 x86 hardware, compile with *both* ``--enable-sse2`` and
284 ``--enable-avx`` for FFTW-3.3.4 and earlier. From FFTW-3.3.5, you
285 should also add ``--enable-avx2`` also. On Intel processors supporting
286 512-wide AVX, including KNL, add ``--enable-avx512`` also.
287 FFTW will create a fat library with codelets for all different instruction sets,
288 and pick the fastest supported one at runtime.
289 On ARM architectures with SIMD support and IBM Power8 and later, you
290 definitely want version 3.3.5 or later,
291 and to compile it with ``--enable-neon`` and ``--enable-vsx``, respectively, for
292 SIMD support. If you are using a Cray, there is a special modified
293 (commercial) version of FFTs using the FFTW interface which can be
299 Use MKL bundled with Intel compilers by setting up the compiler
300 environment, e.g., through ``source /path/to/compilervars.sh intel64``
301 or similar before running CMake including setting
302 ``-DGMX_FFT_LIBRARY=mkl``.
304 If you need to customize this further, use
308 cmake -DGMX_FFT_LIBRARY=mkl \
309 -DMKL_LIBRARIES="/full/path/to/libone.so;/full/path/to/libtwo.so" \
310 -DMKL_INCLUDE_DIR="/full/path/to/mkl/include"
312 The full list and order(!) of libraries you require are found in Intel's MKL documentation for your system.
314 Using ARM Performance Libraries
315 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317 The ARM Performance Libraries provides FFT transforms implementation for ARM
319 Preliminary support is provided for ARMPL in |Gromacs| through its FFTW-compatible API.
320 Assuming that the ARM HPC toolchain environment including the ARMPL paths
321 are set up (e.g. through loading the appropriate modules like
322 ``module load Module-Prefix/arm-hpc-compiler-X.Y/armpl/X.Y``) use the following cmake
327 cmake -DGMX_FFT_LIBRARY=fftw3 \
328 -DFFTWF_LIBRARY="${ARMPL_DIR}/lib/libarmpl_lp64.so" \
329 -DFFTWF_INCLUDE_DIR=${ARMPL_DIR}/include
332 Other optional build components
333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
335 * Run-time detection of hardware capabilities can be improved by
336 linking with hwloc. By default this is turned off since it might
337 not be supported everywhere, but if you have hwloc installed it
338 should work by just setting ``-DGMX_HWLOC=ON``
339 * Hardware-optimized BLAS and LAPACK libraries are useful
340 for a few of the |Gromacs| utilities focused on normal modes and
341 matrix manipulation, but they do not provide any benefits for normal
342 simulations. Configuring these is discussed at
343 `linear algebra libraries`_.
344 * The built-in |Gromacs| trajectory viewer ``gmx view`` requires X11 and
345 Motif/Lesstif libraries and header files. You may prefer to use
346 third-party software for visualization, such as VMD_ or PyMol_.
347 * An external TNG library for trajectory-file handling can be used
348 by setting ``-DGMX_EXTERNAL_TNG=yes``, but TNG
349 |GMX_TNG_MINIMUM_REQUIRED_VERSION| is bundled in the |Gromacs|
351 * The lmfit library for Levenberg-Marquardt curve fitting is used in
352 |Gromacs|. Only lmfit |GMX_LMFIT_REQUIRED_VERSION| is supported. A
353 reduced version of that library is bundled in the |Gromacs|
354 distribution, and the default build uses it. That default may be
355 explicitly enabled with ``-DGMX_USE_LMFIT=internal``. To use an
356 external lmfit library, set ``-DGMX_USE_LMFIT=external``, and adjust
357 ``CMAKE_PREFIX_PATH`` as needed. lmfit support can be disabled with
358 ``-DGMX_USE_LMFIT=none``.
359 * zlib is used by TNG for compressing some kinds of trajectory data
360 * Building the |Gromacs| documentation is optional, and requires
361 ImageMagick, pdflatex, bibtex, doxygen, python 3.6, sphinx
362 |EXPECTED_SPHINX_VERSION|, and pygments.
363 * The |Gromacs| utility programs often write data files in formats
364 suitable for the Grace plotting tool, but it is straightforward to
365 use these files in other plotting programs, too.
366 * Set ``-DGMX_PYTHON_PACKAGE=ON`` when configuring |Gromacs| with CMake to
367 enable additional CMake targets for the gmxapi Python package and
368 sample_restraint package from the main |Gromacs| CMake build. This supports
369 additional testing and documentation generation.
371 Doing a build of |Gromacs|
372 --------------------------
374 This section will cover a general build of |Gromacs| with CMake_, but it
375 is not an exhaustive discussion of how to use CMake. There are many
376 resources available on the web, which we suggest you search for when
377 you encounter problems not covered here. The material below applies
378 specifically to builds on Unix-like systems, including Linux, and Mac
379 OS X. For other platforms, see the specialist instructions below.
383 Configuring with CMake
384 ^^^^^^^^^^^^^^^^^^^^^^
386 CMake will run many tests on your system and do its best to work out
387 how to build |Gromacs| for you. If your build machine is the same as
388 your target machine, then you can be sure that the defaults and
389 detection will be pretty good. However, if you want to control aspects
390 of the build, or you are compiling on a cluster head node for back-end
391 nodes with a different architecture, there are a few things you
392 should consider specifying.
394 The best way to use CMake to configure |Gromacs| is to do an
395 "out-of-source" build, by making another directory from which you will
396 run CMake. This can be outside the source directory, or a subdirectory
397 of it. It also means you can never corrupt your source code by trying
398 to build it! So, the only required argument on the CMake command line
399 is the name of the directory containing the ``CMakeLists.txt`` file of
400 the code you want to build. For example, download the source tarball
405 tar xfz gromacs-|version|.tgz
411 You will see ``cmake`` report a sequence of results of tests and
412 detections done by the |Gromacs| build system. These are written to the
413 ``cmake`` cache, kept in ``CMakeCache.txt``. You can edit this file by
414 hand, but this is not recommended because you could make a mistake.
415 You should not attempt to move or copy this file to do another build,
416 because file paths are hard-coded within it. If you mess things up,
417 just delete this file and start again with ``cmake``.
419 If there is a serious problem detected at this stage, then you will see
420 a fatal error and some suggestions for how to overcome it. If you are
421 not sure how to deal with that, please start by searching on the web
422 (most computer problems already have known solutions!) and then
423 consult the gmx-users mailing list. There are also informational
424 warnings that you might like to take on board or not. Piping the
425 output of ``cmake`` through ``less`` or ``tee`` can be
428 Once ``cmake`` returns, you can see all the settings that were chosen
429 and information about them by using e.g. the curses interface
435 You can actually use ``ccmake`` (available on most Unix platforms)
436 directly in the first step, but then
437 most of the status messages will merely blink in the lower part
438 of the terminal rather than be written to standard output. Most platforms
439 including Linux, Windows, and Mac OS X even have native graphical user interfaces for
440 ``cmake``, and it can create project files for almost any build environment
441 you want (including Visual Studio or Xcode).
442 Check out `running CMake`_ for
443 general advice on what you are seeing and how to navigate and change
444 things. The settings you might normally want to change are already
445 presented. You may make changes, then re-configure (using ``c``), so that it
446 gets a chance to make changes that depend on yours and perform more
447 checking. It may take several configuration passes to reach the desired
448 configuration, in particular if you need to resolve errors.
450 When you have reached the desired configuration with ``ccmake``, the
451 build system can be generated by pressing ``g``. This requires that the previous
452 configuration pass did not reveal any additional settings (if it did, you need
453 to configure once more with ``c``). With ``cmake``, the build system is generated
454 after each pass that does not produce errors.
456 You cannot attempt to change compilers after the initial run of
457 ``cmake``. If you need to change, clean up, and start again.
459 .. _non-standard location:
461 Where to install |Gromacs|
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~
464 |Gromacs| is installed in the directory to which
465 ``CMAKE_INSTALL_PREFIX`` points. It may not be the source directory or
466 the build directory. You require write permissions to this
467 directory. Thus, without super-user privileges,
468 ``CMAKE_INSTALL_PREFIX`` will have to be within your home directory.
469 Even if you do have super-user privileges, you should use them only
470 for the installation phase, and never for configuring, building, or
475 Using CMake command-line options
476 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
478 Once you become comfortable with setting and changing options, you may
479 know in advance how you will configure |Gromacs|. If so, you can speed
480 things up by invoking ``cmake`` and passing the various options at once
481 on the command line. This can be done by setting cache variable at the
482 cmake invocation using ``-DOPTION=VALUE``. Note that some
483 environment variables are also taken into account, in particular
484 variables like ``CC`` and ``CXX``.
486 For example, the following command line
490 cmake .. -DGMX_GPU=CUDA -DGMX_MPI=ON -DCMAKE_INSTALL_PREFIX=/home/marydoe/programs
492 can be used to build with CUDA GPUs, MPI and install in a custom
493 location. You can even save that in a shell script to make it even
494 easier next time. You can also do this kind of thing with ``ccmake``,
495 but you should avoid this, because the options set with ``-D`` will not
496 be able to be changed interactively in that run of ``ccmake``.
498 .. _gmx-simd-support:
503 |Gromacs| has extensive support for detecting and using the SIMD
504 capabilities of many modern HPC CPU architectures. If you are building
505 |Gromacs| on the same hardware you will run it on, then you don't need
506 to read more about this, unless you are getting configuration warnings
507 you do not understand. By default, the |Gromacs| build system will
508 detect the SIMD instruction set supported by the CPU architecture (on
509 which the configuring is done), and thus pick the best
510 available SIMD parallelization supported by |Gromacs|. The build system
511 will also check that the compiler and linker used also support the
512 selected SIMD instruction set and issue a fatal error if they
515 Valid values are listed below, and the applicable value with the
516 largest number in the list is generally the one you should choose.
517 In most cases, choosing an inappropriate higher number will lead
518 to compiling a binary that will not run. However, on a number of
519 processor architectures choosing the highest supported value can
520 lead to performance loss, e.g. on Intel Skylake-X/SP and AMD Zen.
522 1. ``None`` For use only on an architecture either lacking SIMD,
523 or to which |Gromacs| has not yet been ported and none of the
524 options below are applicable.
525 2. ``SSE2`` This SIMD instruction set was introduced in Intel
526 processors in 2001, and AMD in 2003. Essentially all x86
527 machines in existence have this, so it might be a good choice if
528 you need to support dinosaur x86 computers too.
529 3. ``SSE4.1`` Present in all Intel core processors since 2007,
530 but notably not in AMD Magny-Cours. Still, almost all recent
531 processors support this, so this can also be considered a good
532 baseline if you are content with slow simulations and prefer
533 portability between reasonably modern processors.
534 4. ``AVX_128_FMA`` AMD Bulldozer, Piledriver (and later Family 15h) processors have this.
535 5. ``AVX_256`` Intel processors since Sandy Bridge (2011). While this
536 code will work on the AMD Bulldozer and Piledriver processors, it is significantly less
537 efficient than the ``AVX_128_FMA`` choice above - do not be fooled
538 to assume that 256 is better than 128 in this case.
539 6. ``AVX2_128`` AMD Zen/Zen2 and Hygon Dhyana microarchitecture processors;
540 it will enable AVX2 with 3-way fused multiply-add instructions.
541 While these microarchitectures do support 256-bit AVX2 instructions,
542 hence ``AVX2_256`` is also supported, 128-bit will generally be faster,
543 in particular when the non-bonded tasks run on the CPU -- hence
544 the default ``AVX2_128``. With GPU offload however ``AVX2_256``
545 can be faster on Zen processors.
546 7. ``AVX2_256`` Present on Intel Haswell (and later) processors (2013),
547 and it will also enable Intel 3-way fused multiply-add instructions.
548 8. ``AVX_512`` Skylake-X desktop and Skylake-SP Xeon processors (2017);
549 it will generally be fastest on the higher-end desktop and server
550 processors with two 512-bit fused multiply-add units (e.g. Core i9
551 and Xeon Gold). However, certain desktop and server models
552 (e.g. Xeon Bronze and Silver) come with only one AVX512 FMA unit
553 and therefore on these processors ``AVX2_256`` is faster
554 (compile- and runtime checks try to inform about such cases).
555 Additionally, with GPU accelerated runs ``AVX2_256`` can also be
556 faster on high-end Skylake CPUs with both 512-bit FMA units enabled.
557 9. ``AVX_512_KNL`` Knights Landing Xeon Phi processors
558 10. ``IBM_VMX`` Power6 and similar Altivec processors have this.
559 11. ``IBM_VSX`` Power7, Power8, Power9 and later have this.
560 12. ``ARM_NEON`` 32-bit ARMv7 with NEON support.
561 13. ``ARM_NEON_ASIMD`` 64-bit ARMv8 and later.
562 14. ``ARM_SVE`` 64-bit ARMv8 and later with the Scalable Vector Extensions (SVE).
563 The SVE vector length is fixed at CMake configure time. The default vector
564 length is automatically detected, and this can be changed via the
565 ``GMX_SIMD_ARM_SVE_LENGTH`` CMake variable.
567 The CMake configure system will check that the compiler you have
568 chosen can target the architecture you have chosen. mdrun will check
569 further at runtime, so if in doubt, choose the lowest number you
570 think might work, and see what mdrun says. The configure system also
571 works around many known issues in many versions of common HPC
574 A further ``GMX_SIMD=Reference`` option exists, which is a special
575 SIMD-like implementation written in plain C that developers can use
576 when developing support in |Gromacs| for new SIMD architectures. It is
577 not designed for use in production simulations, but if you are using
578 an architecture with SIMD support to which |Gromacs| has not yet been
579 ported, you may wish to try this option instead of the default
580 ``GMX_SIMD=None``, as it can often out-perform this when the
581 auto-vectorization in your compiler does a good job. And post on the
582 |Gromacs| mailing lists, because |Gromacs| can probably be ported for new
583 SIMD architectures in a few days.
585 CMake advanced options
586 ~~~~~~~~~~~~~~~~~~~~~~
588 The options that are displayed in the default view of ``ccmake`` are
589 ones that we think a reasonable number of users might want to consider
590 changing. There are a lot more options available, which you can see by
591 toggling the advanced mode in ``ccmake`` on and off with ``t``. Even
592 there, most of the variables that you might want to change have a
593 ``CMAKE_`` or ``GMX_`` prefix. There are also some options that will be
594 visible or not according to whether their preconditions are satisfied.
596 .. _search for libraries, headers or programs:
598 Helping CMake find the right libraries, headers, or programs
599 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
601 If libraries are installed in non-default locations their location can
602 be specified using the following variables:
604 * ``CMAKE_INCLUDE_PATH`` for header files
605 * ``CMAKE_LIBRARY_PATH`` for libraries
606 * ``CMAKE_PREFIX_PATH`` for header, libraries and binaries
607 (e.g. ``/usr/local``).
609 The respective ``include``, ``lib``, or ``bin`` is
610 appended to the path. For each of these variables, a list of paths can
611 be specified (on Unix, separated with ":"). These can be set as
612 enviroment variables like:
616 CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
618 (assuming ``bash`` shell). Alternatively, these variables are also
619 ``cmake`` options, so they can be set like
620 ``-DCMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda``.
622 The ``CC`` and ``CXX`` environment variables are also useful
623 for indicating to ``cmake`` which compilers to use. Similarly,
624 ``CFLAGS``/``CXXFLAGS`` can be used to pass compiler
625 options, but note that these will be appended to those set by
626 |Gromacs| for your build platform and build type. You can customize
627 some of this with advanced CMake options such as ``CMAKE_C_FLAGS``
630 See also the page on `CMake environment variables`_.
632 .. _CUDA GPU acceleration:
634 CUDA GPU acceleration
635 ~~~~~~~~~~~~~~~~~~~~~
637 If you have the CUDA_ Toolkit installed, you can use ``cmake`` with:
641 cmake .. -DGMX_GPU=CUDA -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
643 (or whichever path has your installation). In some cases, you might
644 need to specify manually which of your C++ compilers should be used,
645 e.g. with the advanced option ``CUDA_HOST_COMPILER``.
647 By default, code will be generated for the most common CUDA architectures.
648 However, to reduce build time and binary size we do not generate code for
649 every single possible architecture, which in rare cases (say, Tegra systems)
650 can result in the default build not being able to use some GPUs.
651 If this happens, or if you want to remove some architectures to reduce
652 binary size and build time, you can alter the target CUDA architectures.
653 This can be done either with the ``GMX_CUDA_TARGET_SM`` or
654 ``GMX_CUDA_TARGET_COMPUTE`` CMake variables, which take a semicolon delimited
655 string with the two digit suffixes of CUDA (virtual) architectures names, for
656 instance "35;50;51;52;53;60". For details, see the "Options for steering GPU
657 code generation" section of the nvcc man / help or Chapter 6. of the nvcc
660 The GPU acceleration has been tested on AMD64/x86-64 platforms with
661 Linux, Mac OS X and Windows operating systems, but Linux is the
662 best-tested and supported of these. Linux running on POWER 8 and ARM v8
663 CPUs also works well.
665 Experimental support is available for compiling CUDA code, both for host and
666 device, using clang (version 6.0 or later).
667 A CUDA toolkit is still required but it is used only for GPU device code
668 generation and to link against the CUDA runtime library.
669 The clang CUDA support simplifies compilation and provides benefits for development
670 (e.g. allows the use code sanitizers in CUDA host-code).
671 Additionally, using clang for both CPU and GPU compilation can be beneficial
672 to avoid compatibility issues between the GNU toolchain and the CUDA toolkit.
673 clang for CUDA can be triggered using the ``GMX_CLANG_CUDA=ON`` CMake option.
674 Target architectures can be selected with ``GMX_CUDA_TARGET_SM``,
675 virtual architecture code is always embedded for all requested architectures
676 (hence GMX_CUDA_TARGET_COMPUTE is ignored).
677 Note that this is mainly a developer-oriented feature and it is not recommended
678 for production use as the performance can be significantly lower than that
679 of code compiled with nvcc (and it has also received less testing).
680 However, note that since clang 5.0 the performance gap is only moderate
681 (at the time of writing, about 20% slower GPU kernels), so this version
682 could be considered in non performance-critical use-cases.
685 OpenCL GPU acceleration
686 ~~~~~~~~~~~~~~~~~~~~~~~
688 The primary targets of the |Gromacs| OpenCL support is accelerating
689 simulations on AMD and Intel hardware. For AMD, we target both
690 discrete GPUs and APUs (integrated CPU+GPU chips), and for Intel we
691 target the integrated GPUs found on modern workstation and mobile
692 hardware. The |Gromacs| OpenCL on NVIDIA GPUs works, but performance
693 and other limitations make it less practical (for details see the user guide).
695 To build |Gromacs| with OpenCL_ support enabled, two components are
696 required: the OpenCL_ headers and the wrapper library that acts
697 as a client driver loader (so-called ICD loader).
698 The additional, runtime-only dependency is the vendor-specific GPU driver
699 for the device targeted. This also contains the OpenCL_ compiler.
700 As the GPU compute kernels are compiled on-demand at run time,
701 this vendor-specific compiler and driver is not needed for building |Gromacs|.
702 The former, compile-time dependencies are standard components,
703 hence stock versions can be obtained from most Linux distribution
704 repositories (e.g. ``opencl-headers`` and ``ocl-icd-libopencl1`` on Debian/Ubuntu).
705 Only the compatibility with the required OpenCL_ version |REQUIRED_OPENCL_MIN_VERSION|
707 Alternatively, the headers and library can also be obtained from vendor SDKs
708 (e.g. `from AMD <http://developer.amd.com/appsdk>`_),
709 which must be installed in a path found in ``CMAKE_PREFIX_PATH`` (or via the environment
710 variables ``AMDAPPSDKROOT`` or ``CUDA_PATH``).
712 To trigger an OpenCL_ build the following CMake flags must be set
716 cmake .. -DGMX_GPU=OpenCL
718 To build with support for Intel integrated GPUs, it is required
719 to add ``-DGMX_OPENCL_NB_CLUSTER_SIZE=4`` to the cmake command line,
720 so that the GPU kernels match the characteristics of the hardware.
721 The `Neo driver <https://github.com/intel/compute-runtime/releases>`_
724 On Mac OS, an AMD GPU can be used only with OS version 10.10.4 and
725 higher; earlier OS versions are known to run incorrectly.
727 By default, any clFFT library on the system will be used with
728 |Gromacs|, but if none is found then the code will fall back on a
729 version bundled with |Gromacs|. To require |Gromacs| to link with an
730 external library, use
734 cmake .. -DGMX_GPU=OpenCL -DclFFT_ROOT_DIR=/path/to/your/clFFT -DGMX_EXTERNAL_CLFFT=TRUE
739 Dynamic linking of the |Gromacs| executables will lead to a
740 smaller disk footprint when installed, and so is the default on
741 platforms where we believe it has been tested repeatedly and found to work.
742 In general, this includes Linux, Windows, Mac OS X and BSD systems.
743 Static binaries take more space, but on some hardware and/or under
744 some conditions they are necessary, most commonly when you are running a parallel
745 simulation using MPI libraries (e.g. Cray).
747 * To link |Gromacs| binaries statically against the internal |Gromacs|
748 libraries, set ``-DBUILD_SHARED_LIBS=OFF``.
749 * To link statically against external (non-system) libraries as well,
750 set ``-DGMX_PREFER_STATIC_LIBS=ON``. Note, that in
751 general ``cmake`` picks up whatever is available, so this option only
752 instructs ``cmake`` to prefer static libraries when both static and
753 shared are available. If no static version of an external library is
754 available, even when the aforementioned option is ``ON``, the shared
755 library will be used. Also note that the resulting binaries will
756 still be dynamically linked against system libraries on platforms
757 where that is the default. To use static system libraries,
758 additional compiler/linker flags are necessary, e.g. ``-static-libgcc
760 * To attempt to link a fully static binary set
761 ``-DGMX_BUILD_SHARED_EXE=OFF``. This will prevent CMake from explicitly
762 setting any dynamic linking flags. This option also sets
763 ``-DBUILD_SHARED_LIBS=OFF`` and ``-DGMX_PREFER_STATIC_LIBS=ON`` by
764 default, but the above caveats apply. For compilers which don't
765 default to static linking, the required flags have to be specified. On
766 Linux, this is usually ``CFLAGS=-static CXXFLAGS=-static``.
771 For dynamic linking builds and on non-Windows platforms, an extra library and
772 headers are installed by setting ``-DGMXAPI=ON`` (default).
773 Build targets ``gmxapi-cppdocs`` and ``gmxapi-cppdocs-dev`` produce documentation in
774 ``docs/api-user`` and ``docs/api-dev``, respectively.
775 For more project information and use cases,
776 refer to the tracked :issue:`2585`,
777 associated GitHub `gmxapi <https://github.com/kassonlab/gmxapi>`_ projects,
778 or DOI `10.1093/bioinformatics/bty484 <https://doi.org/10.1093/bioinformatics/bty484>`_.
780 gmxapi is not yet tested on Windows or with static linking, but these use cases
781 are targeted for future versions.
786 A |Gromacs| build will normally not be portable, not even across
787 hardware with the same base instruction set, like x86. Non-portable
788 hardware-specific optimizations are selected at configure-time, such
789 as the SIMD instruction set used in the compute kernels. This
790 selection will be done by the build system based on the capabilities
791 of the build host machine or otherwise specified to ``cmake`` during
794 Often it is possible to ensure portability by choosing the least
795 common denominator of SIMD support, e.g. SSE2 for x86. In rare cases
796 of very old x86 machines, ensure that
797 you use ``cmake -DGMX_USE_RDTSCP=off`` if any of the target CPU
798 architectures does not support the ``RDTSCP`` instruction. However, we
799 discourage attempts to use a single |Gromacs| installation when the
800 execution environment is heterogeneous, such as a mix of AVX and
801 earlier hardware, because this will lead to programs (especially
802 mdrun) that run slowly on the new hardware. Building two full
803 installations and locally managing how to call the correct one
804 (e.g. using a module system) is the recommended
805 approach. Alternatively, one can use different suffixes to install
806 several versions of |Gromacs| in the same location. To achieve this,
807 one can first build a full installation with the
808 least-common-denominator SIMD instruction set, e.g. ``-DGMX_SIMD=SSE2``,
809 in order for simple commands like ``gmx grompp`` to work on all machines,
810 then build specialized ``gmx`` binaries for each architecture present in
811 the heterogeneous environment. By using custom binary and library
812 suffixes (with CMake variables ``-DGMX_BINARY_SUFFIX=xxx`` and
813 ``-DGMX_LIBS_SUFFIX=xxx``), these can be installed to the same
816 Linear algebra libraries
817 ~~~~~~~~~~~~~~~~~~~~~~~~
819 As mentioned above, sometimes vendor BLAS and LAPACK libraries
820 can provide performance enhancements for |Gromacs| when doing
821 normal-mode analysis or covariance analysis. For simplicity, the text
822 below will refer only to BLAS, but the same options are available
823 for LAPACK. By default, CMake will search for BLAS, use it if it
824 is found, and otherwise fall back on a version of BLAS internal to
825 |Gromacs|. The ``cmake`` option ``-DGMX_EXTERNAL_BLAS=on`` will be set
826 accordingly. The internal versions are fine for normal use. If you
827 need to specify a non-standard path to search, use
828 ``-DCMAKE_PREFIX_PATH=/path/to/search``. If you need to specify a
829 library with a non-standard name (e.g. ESSL on Power machines
830 or ARMPL on ARM machines), then
831 set ``-DGMX_BLAS_USER=/path/to/reach/lib/libwhatever.a``.
833 If you are using Intel MKL_ for FFT, then the BLAS and
834 LAPACK it provides are used automatically. This could be
835 over-ridden with ``GMX_BLAS_USER``, etc.
837 On Apple platforms where the Accelerate Framework is available, these
838 will be automatically used for BLAS and LAPACK. This could be
839 over-ridden with ``GMX_BLAS_USER``, etc.
841 .. _installing with MiMiC:
843 Building with MiMiC QM/MM support
844 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
846 MiMiC QM/MM interface integration will require linking against MiMiC
847 communication library, that establishes the communication channel
848 between |Gromacs| and CPMD. The MiMiC Communication library can be
849 downloaded `here <https://gitlab.com/MiMiC-projects/CommLib>`__.
850 Compile and install it. Check that the installation folder of the
851 MiMiC library is added to CMAKE_PREFIX_PATH if it is installed in
852 non-standard location. Building QM/MM-capable version requires
853 double-precision version of |Gromacs| compiled with MPI support:
855 * ``-DGMX_DOUBLE=ON -DGMX_MPI -DGMX_MIMIC=ON``
859 Changing the names of |Gromacs| binaries and libraries
860 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
862 It is sometimes convenient to have different versions of the same
863 |Gromacs| programs installed. The most common use cases have been single
864 and double precision, and with and without MPI. This mechanism can
865 also be used to install side-by-side multiple versions of mdrun
866 optimized for different CPU architectures, as mentioned previously.
868 By default, |Gromacs| will suffix programs and libraries for such builds
869 with ``_d`` for double precision and/or ``_mpi`` for MPI (and nothing
870 otherwise). This can be controlled manually with ``GMX_DEFAULT_SUFFIX
871 (ON/OFF)``, ``GMX_BINARY_SUFFIX`` (takes a string) and ``GMX_LIBS_SUFFIX``
872 (also takes a string). For instance, to set a custom suffix for
873 programs and libraries, one might specify:
877 cmake .. -DGMX_DEFAULT_SUFFIX=OFF -DGMX_BINARY_SUFFIX=_mod -DGMX_LIBS_SUFFIX=_mod
879 Thus the names of all programs and libraries will be appended with
882 Changing installation tree structure
883 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
885 By default, a few different directories under ``CMAKE_INSTALL_PREFIX`` are used
886 when when |Gromacs| is installed. Some of these can be changed, which is mainly
887 useful for packaging |Gromacs| for various distributions. The directories are
888 listed below, with additional notes about some of them. Unless otherwise noted,
889 the directories can be renamed by editing the installation paths in the main
893 The standard location for executables and some scripts.
894 Some of the scripts hardcode the absolute installation prefix, which needs
895 to be changed if the scripts are relocated.
896 The name of the directory can be changed using ``CMAKE_INSTALL_BINDIR`` CMake
899 The standard location for installed headers.
901 The standard location for libraries. The default depends on the system, and
902 is determined by CMake.
903 The name of the directory can be changed using ``CMAKE_INSTALL_LIBDIR`` CMake
906 Information about the installed ``libgromacs`` library for ``pkg-config`` is
907 installed here. The ``lib/`` part adapts to the installation location of the
908 libraries. The installed files contain the installation prefix as absolute
911 CMake package configuration files are installed here.
913 Various data files and some documentation go here. The first part can
914 be changed using ``CMAKE_INSTALL_DATADIR``, and the second by using
915 ``GMX_INSTALL_DATASUBDIR`` Using these CMake variables is the preferred
916 way of changing the installation path for
917 ``share/gromacs/top/``, since the path to this directory is built into
918 ``libgromacs`` as well as some scripts, both as a relative and as an absolute
919 path (the latter as a fallback if everything else fails).
921 Installed man pages go here.
923 Compiling and linking
924 ^^^^^^^^^^^^^^^^^^^^^
926 Once you have configured with ``cmake``, you can build |Gromacs| with ``make``.
927 It is expected that this will always complete successfully, and
928 give few or no warnings. The CMake-time tests |Gromacs| makes on the settings
929 you choose are pretty extensive, but there are probably a few cases we
930 have not thought of yet. Search the web first for solutions to
931 problems, but if you need help, ask on gmx-users, being sure to
932 provide as much information as possible about what you did, the system
933 you are building on, and what went wrong. This may mean scrolling back
934 a long way through the output of ``make`` to find the first error
937 If you have a multi-core or multi-CPU machine with ``N``
938 processors, then using
944 will generally speed things up by quite a bit. Other build generator systems
945 supported by ``cmake`` (e.g. ``ninja``) also work well.
947 .. _building just the mdrun binary:
952 Finally, ``make install`` will install |Gromacs| in the
953 directory given in ``CMAKE_INSTALL_PREFIX``. If this is a system
954 directory, then you will need permission to write there, and you
955 should use super-user privileges only for ``make install`` and
956 not the whole procedure.
958 .. _getting access to |Gromacs|:
960 Getting access to |Gromacs| after installation
961 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
963 |Gromacs| installs the script ``GMXRC`` in the ``bin``
964 subdirectory of the installation directory
965 (e.g. ``/usr/local/gromacs/bin/GMXRC``), which you should source
970 source /your/installation/prefix/here/bin/GMXRC
972 It will detect what kind of shell you are running and set up your
973 environment for using |Gromacs|. You may wish to arrange for your
974 login scripts to do this automatically; please search the web for
975 instructions on how to do this for your shell.
977 Many of the |Gromacs| programs rely on data installed in the
978 ``share/gromacs`` subdirectory of the installation directory. By
979 default, the programs will use the environment variables set in the
980 ``GMXRC`` script, and if this is not available they will try to guess the
981 path based on their own location. This usually works well unless you
982 change the names of directories inside the install tree. If you still
983 need to do that, you might want to recompile with the new install
984 location properly set, or edit the ``GMXRC`` script.
986 |Gromacs| also installs a CMake toolchains file to help with building client
987 software. For an installation at ``/your/installation/prefix/here``, toolchain
988 files will be installed at
989 ``/your/installation/prefix/here/share/cmake/gromacs${GMX_LIBS_SUFFIX}/gromacs-toolchain${GMX_LIBS_SUFFIX}.cmake``
990 where ``${GMX_LIBS_SUFFIX}`` is :ref:`as documented above <suffixes>`.
992 Testing |Gromacs| for correctness
993 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
995 Since 2011, the |Gromacs| development uses an automated system where
996 every new code change is subject to regression testing on a number of
997 platforms and software combinations. While this improves
998 reliability quite a lot, not everything is tested, and since we
999 increasingly rely on cutting edge compiler features there is
1000 non-negligible risk that the default compiler on your system could
1001 have bugs. We have tried our best to test and refuse to use known bad
1002 versions in ``cmake``, but we strongly recommend that you run through
1003 the tests yourself. It only takes a few minutes, after which you can
1006 The simplest way to run the checks is to build |Gromacs| with
1007 ``-DREGRESSIONTEST_DOWNLOAD``, and run ``make check``.
1008 |Gromacs| will automatically download and run the tests for you.
1009 Alternatively, you can download and unpack the |Gromacs|
1010 regression test suite |gmx-regressiontests-package| tarball yourself
1011 and use the advanced ``cmake`` option ``REGRESSIONTEST_PATH`` to
1012 specify the path to the unpacked tarball, which will then be used for
1013 testing. If the above does not work, then please read on.
1015 The regression tests are also available from the download_ section.
1016 Once you have downloaded them, unpack the tarball, source
1017 ``GMXRC`` as described above, and run ``./gmxtest.pl all``
1018 inside the regression tests folder. You can find more options
1019 (e.g. adding ``double`` when using double precision, or
1020 ``-only expanded`` to run just the tests whose names match
1021 "expanded") if you just execute the script without options.
1023 Hopefully, you will get a report that all tests have passed. If there
1024 are individual failed tests it could be a sign of a compiler bug, or
1025 that a tolerance is just a tiny bit too tight. Check the output files
1026 the script directs you too, and try a different or newer compiler if
1027 the errors appear to be real. If you cannot get it to pass the
1028 regression tests, you might try dropping a line to the
1029 `|Gromacs| users forum <https://gromacs.bioexcel.eu/c/gromacs-user-forum>`__,
1030 but then you should include a detailed description of
1031 your hardware, and the output of ``gmx mdrun -version`` (which contains
1032 valuable diagnostic information in the header).
1037 If your ``gmx`` program has been suffixed in a non-standard way, then
1038 the ``./gmxtest.pl -suffix`` option will let you specify that suffix to the
1039 test machinery. You can use ``./gmxtest.pl -double`` to test the
1040 double-precision version. You can use ``./gmxtest.pl -crosscompiling``
1041 to stop the test harness attempting to check that the programs can
1042 be run. You can use ``./gmxtest.pl -mpirun srun`` if your command to
1043 run an MPI program is called ``srun``.
1045 Running MPI-enabled tests
1046 ~~~~~~~~~~~~~~~~~~~~~~~~~
1048 The ``make check`` target also runs integration-style tests that may run
1049 with MPI if ``GMX_MPI=ON`` was set. To make these work with various possible
1050 MPI libraries, you may need to
1051 set the CMake variables ``MPIEXEC``, ``MPIEXEC_NUMPROC_FLAG``,
1052 ``MPIEXEC_PREFLAGS`` and ``MPIEXEC_POSTFLAGS`` so that
1053 ``mdrun-mpi-test_mpi`` would run on multiple ranks via the shell command
1057 ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} ${NUMPROC} ${MPIEXEC_PREFLAGS} \
1058 mdrun-mpi-test_mpi ${MPIEXEC_POSTFLAGS} -otherflags
1060 A typical example for SLURM is
1064 cmake .. -DGMX_MPI=on -DMPIEXEC=srun -DMPIEXEC_NUMPROC_FLAG=-n -DMPIEXEC_PREFLAGS= -DMPIEXEC_POSTFLAGS=
1067 Testing |Gromacs| for performance
1068 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1070 We are still working on a set of benchmark systems for testing
1071 the performance of |Gromacs|. Until that is ready, we recommend that
1072 you try a few different parallelization options, and experiment with
1073 tools such as ``gmx tune_pme``.
1075 Validating |Gromacs| for source code modifications
1076 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1078 When building |Gromacs| from a release tarball, the build process automatically
1079 checks if any file contributing to the build process have been modified since they have
1080 been packed in the archive. This results in the marking of the version as either ``MODIFIED``
1081 (if the source files have been modified) or ``UNCHECKED`` (if no validation was possible, e.g.
1082 if no Python installation was found). The actual checking is performed by comparing a checksum
1083 stored in the release tarball against one generated by the ``createFileHash.py`` Python script
1084 during the build configuration. When running a |Gromacs| binary, the checksum is also printed
1085 in the log file, together with a message if there is a mismatch or no validation has been possible.
1087 This allows users to check whether the binary they are using was built from source code that is
1088 identical to the source code released by the |Gromacs| team. Thus unintentional modifications
1089 to the source code for building binaries that are used for running production simulations
1090 are easily detectable. Additionally, by manually setting a version tag using the
1091 GMX_VERSION_STRING_OF_FORK cmake option, users can mark a modified |Gromacs| release
1092 code with their custom version string suffix.
1097 You are not alone - this can be a complex task! If you encounter a
1098 problem with installing |Gromacs|, then there are a number of
1099 locations where you can find assistance. It is recommended that you
1100 follow these steps to find the solution:
1102 1. Read the installation instructions again, taking note that you
1103 have followed each and every step correctly.
1105 2. Search the |Gromacs| webpage_ and users emailing list for information
1106 on the error. Adding
1107 ``site:https://mailman-1.sys.kth.se/pipermail/gromacs.org_gmx-users``
1108 to a Google search may help filter better results.
1110 3. Search the internet using a search engine such as Google.
1112 4. Post to the |Gromacs| users emailing list gmx-users for
1113 assistance. Be sure to give a full description of what you have
1114 done and why you think it did not work. Give details about the
1115 system on which you are installing. Copy and paste your command
1116 line and as much of the output as you think might be relevant -
1117 certainly from the first indication of a problem. In particular,
1118 please try to include at least the header from the mdrun logfile,
1119 and preferably the entire file. People who might volunteer to help
1120 you do not have time to ask you interactive detailed follow-up
1121 questions, so you will get an answer faster if you provide as much
1122 information as you think could possibly help. High quality bug
1123 reports tend to receive rapid high quality answers.
1125 .. _gmx-special-build:
1127 Special instructions for some platforms
1128 ---------------------------------------
1133 Building on Windows using native compilers is rather similar to
1134 building on Unix, so please start by reading the above. Then, download
1135 and unpack the |Gromacs| source archive. Make a folder in which to do
1136 the out-of-source build of |Gromacs|. For example, make it within the
1137 folder unpacked from the source archive, and call it ``build-gromacs``.
1139 For CMake, you can either use the graphical user interface provided on
1140 Windows, or you can use a command line shell with instructions similar
1141 to the UNIX ones above. If you open a shell from within your IDE
1142 (e.g. Microsoft Visual Studio), it will configure the environment for
1143 you, but you might need to tweak this in order to get either a 32-bit
1144 or 64-bit build environment. The latter provides the fastest
1145 executable. If you use a normal Windows command shell, then you will
1146 need to either set up the environment to find your compilers and
1147 libraries yourself, or run the ``vcvarsall.bat`` batch script provided
1148 by MSVC (just like sourcing a bash script under Unix).
1150 With the graphical user interface, you will be asked about what
1151 compilers to use at the initial configuration stage, and if you use
1152 the command line they can be set in a similar way as under UNIX.
1154 Unfortunately ``-DGMX_BUILD_OWN_FFTW=ON`` (see `Using FFTW`_) does not
1155 work on Windows, because there is no supported way to build FFTW on
1156 Windows. You can either build FFTW some other way (e.g. MinGW), or
1157 use the built-in fftpack (which may be slow), or `using MKL`_.
1159 For the build, you can either load the generated solutions file into
1160 e.g. Visual Studio, or use the command line with ``cmake --build`` so
1161 the right tools get used.
1166 |Gromacs| builds mostly out of the box on modern Cray machines, but
1167 you may need to specify the use of static binaries with
1168 ``-DGMX_BUILD_SHARED_EXE=off``, and you may need to set the F77
1169 environmental variable to ``ftn`` when compiling FFTW.
1170 The ARM ThunderX2 Cray XC50 machines differ only in that the recommended
1171 compiler is the ARM HPC Compiler (``armclang``).
1177 The built-in |Gromacs| processor detection does not work on Solaris,
1178 so it is strongly recommended that you build |Gromacs| with
1179 ``-DGMX_HWLOC=on`` and ensure that the ``CMAKE_PREFIX_PATH`` includes
1180 the path where the hwloc headers and libraries can be found. At least
1181 version 1.11.8 of hwloc is recommended.
1183 Oracle Developer Studio is not a currently supported compiler (and
1184 does not currently compile |Gromacs| correctly, perhaps because the
1185 thread-MPI atomics are incorrectly implemented in |Gromacs|).
1190 Xeon Phi processors, hosted or self-hosted, are supported.
1191 Only symmetric (aka native) mode is supported on Knights Corner. The
1192 performance depends among other factors on the system size, and for
1193 now the performance might not be faster than CPUs. When building for it,
1194 the recommended configuration is
1198 cmake .. -DCMAKE_TOOLCHAIN_FILE=Platform/XeonPhi
1203 The Knights Landing-based Xeon Phi processors behave like standard x86 nodes,
1204 but support a special SIMD instruction set. When cross-compiling for such nodes,
1205 use the ``AVX_512_KNL`` SIMD flavor.
1206 Knights Landing processors support so-called "clustering modes" which
1207 allow reconfiguring the memory subsystem for lower latency. |Gromacs| can
1208 benefit from the quadrant or SNC clustering modes.
1209 Care needs to be taken to correctly pin threads. In particular, threads of
1210 an MPI rank should not cross cluster and NUMA boundaries.
1211 In addition to the main DRAM memory, Knights Landing has a high-bandwidth
1212 stacked memory called MCDRAM. Using it offers performance benefits if
1213 it is ensured that ``mdrun`` runs entirely from this memory; to do so
1214 it is recommended that MCDRAM is configured in "Flat mode" and ``mdrun`` is
1215 bound to the appropriate NUMA node (use e.g. ``numactl --membind 1`` with
1216 quadrant clustering mode).
1222 While it is our best belief that |Gromacs| will build and run pretty
1223 much everywhere, it is important that we tell you where we really know
1224 it works because we have tested it.
1225 Every commit in our git source code repository
1226 is currently tested with a range of configuration options on x86 with
1227 gcc versions 7 and 8,
1228 clang versions 8 and 9,
1230 a beta version of oneAPI containing Intel's compiler.
1231 For this testing, we use Ubuntu 18.04 or 20.04 operating system.
1232 Other compiler, library, and OS versions are tested less frequently.
1233 For details, you can have a look at the
1234 `continuous integration server used by GROMACS <https://gitlab.com/gromacs/gromacs/>`_,
1235 which uses GitLab runner on a local k8s x86 cluster with NVIDIA and
1238 We test irregularly on ARM v8, Cray, Power8, Power9,
1239 Google Native Client and other environments, and
1240 with other compilers and compiler versions, too.