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 an MPI wrapper compiler and which is `building only
59 mdrun`_, because that is the only component of |Gromacs| that uses
60 MPI. The latter will install a single simulation engine binary,
61 i.e. ``mdrun_mpi`` when the default suffix is used. Hence it is safe
62 and common practice to install this into the same location where
63 the non-MPI build is installed.
68 As above, and with further details below, but you should consider
69 using the following `CMake options`_ with the
70 appropriate value instead of ``xxx`` :
72 * ``-DCMAKE_C_COMPILER=xxx`` equal to the name of the C99 `Compiler`_ you wish to use (or the environment variable ``CC``)
73 * ``-DCMAKE_CXX_COMPILER=xxx`` equal to the name of the C++98 `compiler`_ you wish to use (or the environment variable ``CXX``)
74 * ``-DGMX_MPI=on`` to build using `MPI support`_ (generally good to combine with `building only mdrun`_)
75 * ``-DGMX_GPU=on`` to build using nvcc to run using NVIDIA `CUDA GPU acceleration`_ or an OpenCL_ GPU
76 * ``-DGMX_USE_OPENCL=on`` to build with OpenCL_ support enabled. ``GMX_GPU`` must also be set.
77 * ``-DGMX_SIMD=xxx`` to specify the level of `SIMD support`_ of the node on which |Gromacs| will run
78 * ``-DGMX_BUILD_MDRUN_ONLY=on`` for `building only mdrun`_, e.g. for compute cluster back-end nodes
79 * ``-DGMX_DOUBLE=on`` to build |Gromacs| in double precision (slower, and not normally useful)
80 * ``-DCMAKE_PREFIX_PATH=xxx`` to add a non-standard location for CMake to `search for libraries, headers or programs`_
81 * ``-DCMAKE_INSTALL_PREFIX=xxx`` to install |Gromacs| to a `non-standard location`_ (default ``/usr/local/gromacs``)
82 * ``-DBUILD_SHARED_LIBS=off`` to turn off the building of shared libraries to help with `static linking`_
83 * ``-DGMX_FFT_LIBRARY=xxx`` to select whether to use ``fftw3``, ``mkl`` or ``fftpack`` libraries for `FFT support`_
84 * ``-DCMAKE_BUILD_TYPE=Debug`` to build |Gromacs| in debug mode
86 Building older versions
87 ^^^^^^^^^^^^^^^^^^^^^^^
89 Installation instructions for old |Gromacs| versions can be found at
90 the |Gromacs| `documentation page
91 <http://manual.gromacs.org/documentation>`_.
99 |Gromacs| can be compiled for many operating systems and
100 architectures. These include any distribution of Linux, Mac OS X or
101 Windows, and architectures including x86, AMD64/x86-64, several
102 PowerPC including POWER8, ARM v7, ARM v8, and SPARC VIII.
107 |Gromacs| can be compiled on any platform with ANSI C99 and C++14
108 compilers, and their respective standard C/C++ libraries. Good
109 performance on an OS and architecture requires choosing a good
110 compiler. We recommend gcc, because it is free, widely available and
111 frequently provides the best performance.
113 You should strive to use the most recent version of your
114 compiler. Since we require full C++14 support the minimum supported
115 compiler versions are
120 * Microsoft (MSVC) 2017
122 Other compilers may work (Cray, Pathscale, older clang) but do
123 not offer competitive performance. We recommend against PGI because
124 the performance with C++ is very bad.
126 The xlc compiler is not supported and version 16.1 does not compile on
127 POWER architectures for |Gromacs|\ -\ |version|. We recommend to use
128 the gcc compiler instead, as it is being extensively tested.
130 You may also need the most recent version of other compiler toolchain
131 components beside the compiler itself (e.g. assembler or linker);
132 these are often shipped by your OS distribution's binutils package.
134 C++14 support requires adequate support in both the compiler and the
135 C++ library. The gcc and MSVC compilers include their own standard
136 libraries and require no further configuration. For configuration of
137 other compilers, read on.
139 On Linux, both the Intel and clang compiler use the libstdc++ which
140 comes with gcc as the default C++ library. For |Gromacs|, we require
141 the compiler to support libstc++ version 5.1 or higher. To select a
142 particular libstdc++ library, use:
144 * For Intel: ``-DCMAKE_CXX_FLAGS=-gcc-name=/path/to/gcc/binary``
145 or make sure that the correct gcc version is first in path (e.g. by
146 loading the gcc module). It can also be useful to add
147 ``-DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,/path/to/gcc/lib64
148 -L/path/to/gcc/lib64"`` to ensure linking works correctly.
150 ``-DCMAKE_CXX_FLAGS=--gcc-toolchain=/path/to/gcc/folder``. This
151 folder should contain ``include/c++``.
153 On Windows with the Intel compiler, the MSVC standard library is used,
154 and at least MSVC 2017 is required. Load the enviroment variables with
157 To build with clang and llvm's libcxx standard library, use
158 ``-DCMAKE_CXX_FLAGS=-stdlib=libc++``.
160 If you are running on Mac OS X, the best option is the Intel
161 compiler. Both clang and gcc will work, but they produce lower
162 performance and each have some shortcomings. clang 3.8 now offers
163 support for OpenMP, and so may provide decent performance.
165 For all non-x86 platforms, your best option is typically to use gcc or
166 the vendor's default or recommended compiler, and check for
167 specialized information below.
169 For updated versions of gcc to add to your Linux OS, see
171 * Ubuntu: `Ubuntu toolchain ppa page`_
172 * RHEL/CentOS: `EPEL page`_ or the RedHat Developer Toolset
174 Compiling with parallelization options
175 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
177 For maximum performance you will need to examine how you will use
178 |Gromacs| and what hardware you plan to run on. Often OpenMP_
179 parallelism is an advantage for |Gromacs|, but support for this is
180 generally built into your compiler and detected automatically.
187 |Gromacs| has excellent support for NVIDIA GPUs supported via CUDA.
188 On Linux, NVIDIA CUDA_ toolkit with minimum version |REQUIRED_CUDA_VERSION|
189 is required, and the latest version is strongly encouraged. Using
190 Microsoft MSVC compiler requires version 9.0. NVIDIA GPUs with at
191 least NVIDIA compute capability |REQUIRED_CUDA_COMPUTE_CAPABILITY| are
192 required. You are strongly recommended to
193 get the latest CUDA version and driver that supports your hardware, but
194 beware of possible performance regressions in newer CUDA versions on
196 While some CUDA compilers (nvcc) might not
197 officially support recent versions of gcc as the back-end compiler, we
198 still recommend that you at least use a gcc version recent enough to
199 get the best SIMD support for your CPU, since |Gromacs| always runs some
200 code on the CPU. It is most reliable to use the same C++ compiler
201 version for |Gromacs| code as used as the host compiler for nvcc.
203 To make it possible to use other accelerators, |Gromacs| also includes
204 OpenCL_ support. The minimum OpenCL version required is
205 |REQUIRED_OPENCL_MIN_VERSION|. The current OpenCL implementation is recommended for
206 use with GCN-based AMD GPUs, and on Linux we recommend the ROCm runtime.
207 Intel integrated GPUs are supported with the Neo drivers.
208 OpenCL is also supported with NVIDIA GPUs, but using
209 the latest NVIDIA driver (which includes the NVIDIA OpenCL runtime) is
210 recommended. Also note that there are performance limitations (inherent
211 to the NVIDIA OpenCL runtime).
212 It is not possible to configure both CUDA and OpenCL
213 support in the same build of |Gromacs|, nor to support both
214 Intel and other vendors' GPUs with OpenCL.
221 |Gromacs| can run in parallel on multiple cores of a single
222 workstation using its built-in thread-MPI. No user action is required
223 in order to enable this.
225 If you wish to run in parallel on multiple machines across a network,
226 you will need to have
228 * an MPI library installed that supports the MPI 1.3
230 * wrapper compilers that will compile code using that library.
232 The |Gromacs| team recommends OpenMPI_ version
233 1.6 (or higher), MPICH_ version 1.4.1 (or
234 higher), or your hardware vendor's MPI installation. The most recent
235 version of either of these is likely to be the best. More specialized
236 networks might depend on accelerations only available in the vendor's
237 library. LAM-MPI_ might work, but since it has
238 been deprecated for years, it is not supported.
243 |Gromacs| builds with the CMake build system, requiring at least
244 version |CMAKE_MINIMUM_REQUIRED_VERSION|. You can check whether
245 CMake is installed, and what version it is, with ``cmake
246 --version``. If you need to install CMake, then first check whether
247 your platform's package management system provides a suitable version,
248 or visit the `CMake installation page`_ for pre-compiled binaries,
249 source code and installation instructions. The |Gromacs| team
250 recommends you install the most recent version of CMake you can.
254 Fast Fourier Transform library
255 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
257 Many simulations in |Gromacs| make extensive use of fast Fourier
258 transforms, and a software library to perform these is always
259 required. We recommend FFTW_ (version 3 or higher only) or Intel
260 MKL_. The choice of library can be set with ``cmake
261 -DGMX_FFT_LIBRARY=<name>``, where ``<name>`` is one of ``fftw3``,
262 ``mkl``, or ``fftpack``. FFTPACK is bundled with |Gromacs| as a
263 fallback, and is acceptable if simulation performance is not a
264 priority. When choosing MKL, |Gromacs| will also use MKL for BLAS and
265 LAPACK (see `linear algebra libraries`_). Generally, there is no
266 advantage in using MKL with |Gromacs|, and FFTW is often faster.
267 With PME GPU offload support using CUDA, a GPU-based FFT library
268 is required. The CUDA-based GPU FFT library cuFFT is part of the
269 CUDA toolkit (required for all CUDA builds) and therefore no additional
270 software component is needed when building with CUDA GPU acceleration.
275 FFTW_ is likely to be available for your platform via its package
276 management system, but there can be compatibility and significant
277 performance issues associated with these packages. In particular,
278 |Gromacs| simulations are normally run in "mixed" floating-point
279 precision, which is suited for the use of single precision in
280 FFTW. The default FFTW package is normally in double
281 precision, and good compiler options to use for FFTW when linked to
282 |Gromacs| may not have been used. Accordingly, the |Gromacs| team
285 * that you permit the |Gromacs| installation to download and
286 build FFTW from source automatically for you (use
287 ``cmake -DGMX_BUILD_OWN_FFTW=ON``), or
288 * that you build FFTW from the source code.
290 If you build FFTW from source yourself, get the most recent version
291 and follow the `FFTW installation guide`_. Choose the precision for
292 FFTW (i.e. single/float vs. double) to match whether you will later
293 use mixed or double precision for |Gromacs|. There is no need to
294 compile FFTW with threading or MPI support, but it does no harm. On
295 x86 hardware, compile with *both* ``--enable-sse2`` and
296 ``--enable-avx`` for FFTW-3.3.4 and earlier. From FFTW-3.3.5, you
297 should also add ``--enable-avx2`` also. On Intel processors supporting
298 512-wide AVX, including KNL, add ``--enable-avx512`` also.
299 FFTW will create a fat library with codelets for all different instruction sets,
300 and pick the fastest supported one at runtime.
301 On ARM architectures with NEON SIMD support and IBM Power8 and later, you
302 definitely want version 3.3.5 or later,
303 and to compile it with ``--enable-neon`` and ``--enable-vsx``, respectively, for
304 SIMD support. If you are using a Cray, there is a special modified
305 (commercial) version of FFTs using the FFTW interface which can be
311 Use MKL bundled with Intel compilers by setting up the compiler
312 environment, e.g., through ``source /path/to/compilervars.sh intel64``
313 or similar before running CMake including setting
314 ``-DGMX_FFT_LIBRARY=mkl``.
316 If you need to customize this further, use
320 cmake -DGMX_FFT_LIBRARY=mkl \
321 -DMKL_LIBRARIES="/full/path/to/libone.so;/full/path/to/libtwo.so" \
322 -DMKL_INCLUDE_DIR="/full/path/to/mkl/include"
324 The full list and order(!) of libraries you require are found in Intel's MKL documentation for your system.
326 Using ARM Performance Libraries
327 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
329 The ARM Performance Libraries provides FFT transforms implementation for ARM
331 Preliminary support is provided for ARMPL in |Gromacs| through its FFTW-compatible API.
332 Assuming that the ARM HPC toolchain environment including the ARMPL paths
333 are set up (e.g. through loading the appropriate modules like
334 ``module load Module-Prefix/arm-hpc-compiler-X.Y/armpl/X.Y``) use the following cmake
339 cmake -DGMX_FFT_LIBRARY=fftw3 \
340 -DFFTWF_LIBRARY="${ARMPL_DIR}/lib/libarmpl_lp64.so" \
341 -DFFTWF_INCLUDE_DIR=${ARMPL_DIR}/include
344 Other optional build components
345 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
347 * Run-time detection of hardware capabilities can be improved by
348 linking with hwloc, which is automatically enabled if detected.
349 * Hardware-optimized BLAS and LAPACK libraries are useful
350 for a few of the |Gromacs| utilities focused on normal modes and
351 matrix manipulation, but they do not provide any benefits for normal
352 simulations. Configuring these is discussed at
353 `linear algebra libraries`_.
354 * The built-in |Gromacs| trajectory viewer ``gmx view`` requires X11 and
355 Motif/Lesstif libraries and header files. You may prefer to use
356 third-party software for visualization, such as VMD_ or PyMol_.
357 * An external TNG library for trajectory-file handling can be used
358 by setting ``-DGMX_EXTERNAL_TNG=yes``, but TNG
359 |GMX_TNG_MINIMUM_REQUIRED_VERSION| is bundled in the |Gromacs|
361 * The lmfit library for Levenberg-Marquardt curve fitting is used in
362 |Gromacs|. Only lmfit |GMX_LMFIT_REQUIRED_VERSION| is supported. A
363 reduced version of that library is bundled in the |Gromacs|
364 distribution, and the default build uses it. That default may be
365 explicitly enabled with ``-DGMX_USE_LMFIT=internal``. To use an
366 external lmfit library, set ``-DGMX_USE_LMFIT=external``, and adjust
367 ``CMAKE_PREFIX_PATH`` as needed. lmfit support can be disabled with
368 ``-DGMX_USE_LMFIT=none``.
369 * zlib is used by TNG for compressing some kinds of trajectory data
370 * Building the |Gromacs| documentation is optional, and requires
371 ImageMagick, pdflatex, bibtex, doxygen, python 2.7, sphinx
372 |EXPECTED_SPHINX_VERSION|, and pygments.
373 * The |Gromacs| utility programs often write data files in formats
374 suitable for the Grace plotting tool, but it is straightforward to
375 use these files in other plotting programs, too.
377 Doing a build of |Gromacs|
378 --------------------------
380 This section will cover a general build of |Gromacs| with CMake_, but it
381 is not an exhaustive discussion of how to use CMake. There are many
382 resources available on the web, which we suggest you search for when
383 you encounter problems not covered here. The material below applies
384 specifically to builds on Unix-like systems, including Linux, and Mac
385 OS X. For other platforms, see the specialist instructions below.
389 Configuring with CMake
390 ^^^^^^^^^^^^^^^^^^^^^^
392 CMake will run many tests on your system and do its best to work out
393 how to build |Gromacs| for you. If your build machine is the same as
394 your target machine, then you can be sure that the defaults and
395 detection will be pretty good. However, if you want to control aspects
396 of the build, or you are compiling on a cluster head node for back-end
397 nodes with a different architecture, there are a few things you
398 should consider specifying.
400 The best way to use CMake to configure |Gromacs| is to do an
401 "out-of-source" build, by making another directory from which you will
402 run CMake. This can be outside the source directory, or a subdirectory
403 of it. It also means you can never corrupt your source code by trying
404 to build it! So, the only required argument on the CMake command line
405 is the name of the directory containing the ``CMakeLists.txt`` file of
406 the code you want to build. For example, download the source tarball
411 tar xfz gromacs-|version|.tgz
417 You will see ``cmake`` report a sequence of results of tests and
418 detections done by the |Gromacs| build system. These are written to the
419 ``cmake`` cache, kept in ``CMakeCache.txt``. You can edit this file by
420 hand, but this is not recommended because you could make a mistake.
421 You should not attempt to move or copy this file to do another build,
422 because file paths are hard-coded within it. If you mess things up,
423 just delete this file and start again with ``cmake``.
425 If there is a serious problem detected at this stage, then you will see
426 a fatal error and some suggestions for how to overcome it. If you are
427 not sure how to deal with that, please start by searching on the web
428 (most computer problems already have known solutions!) and then
429 consult the gmx-users mailing list. There are also informational
430 warnings that you might like to take on board or not. Piping the
431 output of ``cmake`` through ``less`` or ``tee`` can be
434 Once ``cmake`` returns, you can see all the settings that were chosen
435 and information about them by using e.g. the curses interface
441 You can actually use ``ccmake`` (available on most Unix platforms)
442 directly in the first step, but then
443 most of the status messages will merely blink in the lower part
444 of the terminal rather than be written to standard output. Most platforms
445 including Linux, Windows, and Mac OS X even have native graphical user interfaces for
446 ``cmake``, and it can create project files for almost any build environment
447 you want (including Visual Studio or Xcode).
448 Check out `running CMake`_ for
449 general advice on what you are seeing and how to navigate and change
450 things. The settings you might normally want to change are already
451 presented. You may make changes, then re-configure (using ``c``), so that it
452 gets a chance to make changes that depend on yours and perform more
453 checking. It may take several configuration passes to reach the desired
454 configuration, in particular if you need to resolve errors.
456 When you have reached the desired configuration with ``ccmake``, the
457 build system can be generated by pressing ``g``. This requires that the previous
458 configuration pass did not reveal any additional settings (if it did, you need
459 to configure once more with ``c``). With ``cmake``, the build system is generated
460 after each pass that does not produce errors.
462 You cannot attempt to change compilers after the initial run of
463 ``cmake``. If you need to change, clean up, and start again.
465 .. _non-standard location:
467 Where to install |Gromacs|
468 ~~~~~~~~~~~~~~~~~~~~~~~~~~
470 |Gromacs| is installed in the directory to which
471 ``CMAKE_INSTALL_PREFIX`` points. It may not be the source directory or
472 the build directory. You require write permissions to this
473 directory. Thus, without super-user privileges,
474 ``CMAKE_INSTALL_PREFIX`` will have to be within your home directory.
475 Even if you do have super-user privileges, you should use them only
476 for the installation phase, and never for configuring, building, or
481 Using CMake command-line options
482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
484 Once you become comfortable with setting and changing options, you may
485 know in advance how you will configure |Gromacs|. If so, you can speed
486 things up by invoking ``cmake`` and passing the various options at once
487 on the command line. This can be done by setting cache variable at the
488 cmake invocation using ``-DOPTION=VALUE``. Note that some
489 environment variables are also taken into account, in particular
490 variables like ``CC`` and ``CXX``.
492 For example, the following command line
496 cmake .. -DGMX_GPU=ON -DGMX_MPI=ON -DCMAKE_INSTALL_PREFIX=/home/marydoe/programs
498 can be used to build with CUDA GPUs, MPI and install in a custom
499 location. You can even save that in a shell script to make it even
500 easier next time. You can also do this kind of thing with ``ccmake``,
501 but you should avoid this, because the options set with ``-D`` will not
502 be able to be changed interactively in that run of ``ccmake``.
504 .. _gmx-simd-support:
509 |Gromacs| has extensive support for detecting and using the SIMD
510 capabilities of many modern HPC CPU architectures. If you are building
511 |Gromacs| on the same hardware you will run it on, then you don't need
512 to read more about this, unless you are getting configuration warnings
513 you do not understand. By default, the |Gromacs| build system will
514 detect the SIMD instruction set supported by the CPU architecture (on
515 which the configuring is done), and thus pick the best
516 available SIMD parallelization supported by |Gromacs|. The build system
517 will also check that the compiler and linker used also support the
518 selected SIMD instruction set and issue a fatal error if they
521 Valid values are listed below, and the applicable value with the
522 largest number in the list is generally the one you should choose.
523 In most cases, choosing an inappropriate higher number will lead
524 to compiling a binary that will not run. However, on a number of
525 processor architectures choosing the highest supported value can
526 lead to performance loss, e.g. on Intel Skylake-X/SP and AMD Zen.
528 1. ``None`` For use only on an architecture either lacking SIMD,
529 or to which |Gromacs| has not yet been ported and none of the
530 options below are applicable.
531 2. ``SSE2`` This SIMD instruction set was introduced in Intel
532 processors in 2001, and AMD in 2003. Essentially all x86
533 machines in existence have this, so it might be a good choice if
534 you need to support dinosaur x86 computers too.
535 3. ``SSE4.1`` Present in all Intel core processors since 2007,
536 but notably not in AMD Magny-Cours. Still, almost all recent
537 processors support this, so this can also be considered a good
538 baseline if you are content with slow simulations and prefer
539 portability between reasonably modern processors.
540 4. ``AVX_128_FMA`` AMD Bulldozer, Piledriver (and later Family 15h) processors have this.
541 5. ``AVX_256`` Intel processors since Sandy Bridge (2011). While this
542 code will work on the AMD Bulldozer and Piledriver processors, it is significantly less
543 efficient than the ``AVX_128_FMA`` choice above - do not be fooled
544 to assume that 256 is better than 128 in this case.
545 6. ``AVX2_128`` AMD Zen microarchitecture processors (2017);
546 it will enable AVX2 with 3-way fused multiply-add instructions.
547 While the Zen microarchitecture does support 256-bit AVX2 instructions,
548 hence ``AVX2_256`` is also supported, 128-bit will generally be faster,
549 in particular when the non-bonded tasks run on the CPU -- hence
550 the default ``AVX2_128``. With GPU offload however ``AVX2_256``
551 can be faster on Zen processors.
552 7. ``AVX2_256`` Present on Intel Haswell (and later) processors (2013),
553 and it will also enable Intel 3-way fused multiply-add instructions.
554 8. ``AVX_512`` Skylake-X desktop and Skylake-SP Xeon processors (2017);
555 it will generally be fastest on the higher-end desktop and server
556 processors with two 512-bit fused multiply-add units (e.g. Core i9
557 and Xeon Gold). However, certain desktop and server models
558 (e.g. Xeon Bronze and Silver) come with only one AVX512 FMA unit
559 and therefore on these processors ``AVX2_256`` is faster
560 (compile- and runtime checks try to inform about such cases).
561 Additionally, with GPU accelerated runs ``AVX2_256`` can also be
562 faster on high-end Skylake CPUs with both 512-bit FMA units enabled.
563 9. ``AVX_512_KNL`` Knights Landing Xeon Phi processors
564 10. ``Sparc64_HPC_ACE`` Fujitsu machines like the K computer have this.
565 11. ``IBM_VMX`` Power6 and similar Altivec processors have this.
566 12. ``IBM_VSX`` Power7, Power8, Power9 and later have this.
567 13. ``ARM_NEON`` 32-bit ARMv7 with NEON support.
568 14. ``ARM_NEON_ASIMD`` 64-bit ARMv8 and later.
570 The CMake configure system will check that the compiler you have
571 chosen can target the architecture you have chosen. mdrun will check
572 further at runtime, so if in doubt, choose the lowest number you
573 think might work, and see what mdrun says. The configure system also
574 works around many known issues in many versions of common HPC
577 A further ``GMX_SIMD=Reference`` option exists, which is a special
578 SIMD-like implementation written in plain C that developers can use
579 when developing support in |Gromacs| for new SIMD architectures. It is
580 not designed for use in production simulations, but if you are using
581 an architecture with SIMD support to which |Gromacs| has not yet been
582 ported, you may wish to try this option instead of the default
583 ``GMX_SIMD=None``, as it can often out-perform this when the
584 auto-vectorization in your compiler does a good job. And post on the
585 |Gromacs| mailing lists, because |Gromacs| can probably be ported for new
586 SIMD architectures in a few days.
588 CMake advanced options
589 ~~~~~~~~~~~~~~~~~~~~~~
591 The options that are displayed in the default view of ``ccmake`` are
592 ones that we think a reasonable number of users might want to consider
593 changing. There are a lot more options available, which you can see by
594 toggling the advanced mode in ``ccmake`` on and off with ``t``. Even
595 there, most of the variables that you might want to change have a
596 ``CMAKE_`` or ``GMX_`` prefix. There are also some options that will be
597 visible or not according to whether their preconditions are satisfied.
599 .. _search for libraries, headers or programs:
601 Helping CMake find the right libraries, headers, or programs
602 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
604 If libraries are installed in non-default locations their location can
605 be specified using the following variables:
607 * ``CMAKE_INCLUDE_PATH`` for header files
608 * ``CMAKE_LIBRARY_PATH`` for libraries
609 * ``CMAKE_PREFIX_PATH`` for header, libraries and binaries
610 (e.g. ``/usr/local``).
612 The respective ``include``, ``lib``, or ``bin`` is
613 appended to the path. For each of these variables, a list of paths can
614 be specified (on Unix, separated with ":"). These can be set as
615 enviroment variables like:
619 CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
621 (assuming ``bash`` shell). Alternatively, these variables are also
622 ``cmake`` options, so they can be set like
623 ``-DCMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda``.
625 The ``CC`` and ``CXX`` environment variables are also useful
626 for indicating to ``cmake`` which compilers to use. Similarly,
627 ``CFLAGS``/``CXXFLAGS`` can be used to pass compiler
628 options, but note that these will be appended to those set by
629 |Gromacs| for your build platform and build type. You can customize
630 some of this with advanced CMake options such as ``CMAKE_C_FLAGS``
633 See also the page on `CMake environment variables`_.
635 .. _CUDA GPU acceleration:
637 CUDA GPU acceleration
638 ~~~~~~~~~~~~~~~~~~~~~
640 If you have the CUDA_ Toolkit installed, you can use ``cmake`` with:
644 cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
646 (or whichever path has your installation). In some cases, you might
647 need to specify manually which of your C++ compilers should be used,
648 e.g. with the advanced option ``CUDA_HOST_COMPILER``.
650 By default, code will be generated for the most common CUDA architectures.
651 However, to reduce build time and binary size we do not generate code for
652 every single possible architecture, which in rare cases (say, Tegra systems)
653 can result in the default build not being able to use some GPUs.
654 If this happens, or if you want to remove some architectures to reduce
655 binary size and build time, you can alter the target CUDA architectures.
656 This can be done either with the ``GMX_CUDA_TARGET_SM`` or
657 ``GMX_CUDA_TARGET_COMPUTE`` CMake variables, which take a semicolon delimited
658 string with the two digit suffixes of CUDA (virtual) architectures names, for
659 instance "35;50;51;52;53;60". For details, see the "Options for steering GPU
660 code generation" section of the nvcc man / help or Chapter 6. of the nvcc
663 The GPU acceleration has been tested on AMD64/x86-64 platforms with
664 Linux, Mac OS X and Windows operating systems, but Linux is the
665 best-tested and supported of these. Linux running on POWER 8, ARM v7 and v8
666 CPUs also works well.
668 Experimental support is available for compiling CUDA code, both for host and
669 device, using clang (version 3.9 or later).
670 A CUDA toolkit (>= v7.0) is still required but it is used only for GPU device code
671 generation and to link against the CUDA runtime library.
672 The clang CUDA support simplifies compilation and provides benefits for development
673 (e.g. allows the use code sanitizers in CUDA host-code).
674 Additionally, using clang for both CPU and GPU compilation can be beneficial
675 to avoid compatibility issues between the GNU toolchain and the CUDA toolkit.
676 clang for CUDA can be triggered using the ``GMX_CLANG_CUDA=ON`` CMake option.
677 Target architectures can be selected with ``GMX_CUDA_TARGET_SM``,
678 virtual architecture code is always embedded for all requested architectures
679 (hence GMX_CUDA_TARGET_COMPUTE is ignored).
680 Note that this is mainly a developer-oriented feature and it is not recommended
681 for production use as the performance can be significantly lower than that
682 of code compiled with nvcc (and it has also received less testing).
683 However, note that with clang 5.0 the performance gap is significantly narrowed
684 (at the time of writing, about 20% slower GPU kernels), so this version
685 could be considered in non performance-critical use-cases.
688 OpenCL GPU acceleration
689 ~~~~~~~~~~~~~~~~~~~~~~~
691 The primary targets of the |Gromacs| OpenCL support is accelerating
692 simulations on AMD and Intel hardware. For AMD, we target both
693 discrete GPUs and APUs (integrated CPU+GPU chips), and for Intel we
694 target the integrated GPUs found on modern workstation and mobile
695 hardware. The |Gromacs| OpenCL on NVIDIA GPUs works, but performance
696 and other limitations make it less practical (for details see the user guide).
698 To build |Gromacs| with OpenCL_ support enabled, two components are
699 required: the OpenCL_ headers and the wrapper library that acts
700 as a client driver loader (so-called ICD loader).
701 The additional, runtime-only dependency is the vendor-specific GPU driver
702 for the device targeted. This also contains the OpenCL_ compiler.
703 As the GPU compute kernels are compiled on-demand at run time,
704 this vendor-specific compiler and driver is not needed for building |Gromacs|.
705 The former, compile-time dependencies are standard components,
706 hence stock versions can be obtained from most Linux distribution
707 repositories (e.g. ``opencl-headers`` and ``ocl-icd-libopencl1`` on Debian/Ubuntu).
708 Only the compatibility with the required OpenCL_ version |REQUIRED_OPENCL_MIN_VERSION|
710 Alternatively, the headers and library can also be obtained from vendor SDKs
711 (e.g. `from AMD <http://developer.amd.com/appsdk>`_),
712 which must be installed in a path found in ``CMAKE_PREFIX_PATH`` (or via the environment
713 variables ``AMDAPPSDKROOT`` or ``CUDA_PATH``).
715 To trigger an OpenCL_ build the following CMake flags must be set
719 cmake .. -DGMX_GPU=ON -DGMX_USE_OPENCL=ON
721 To build with support for Intel integrated GPUs, it is required
722 to add ``-DGMX_OPENCL_NB_CLUSTER_SIZE=4`` to the cmake command line,
723 so that the GPU kernels match the characteristics of the hardware.
724 The `Neo driver <https://github.com/intel/compute-runtime/releases>`_
727 On Mac OS, an AMD GPU can be used only with OS version 10.10.4 and
728 higher; earlier OS versions are known to run incorrectly.
730 By default, any clFFT library on the system will be used with
731 |Gromacs|, but if none is found then the code will fall back on a
732 version bundled with |Gromacs|. To require |Gromacs| to link with an
733 external library, use
737 cmake .. -DGMX_GPU=ON -DGMX_USE_OPENCL=ON -DclFFT_ROOT_DIR=/path/to/your/clFFT -DGMX_EXTERNAL_CLFFT=TRUE
742 Dynamic linking of the |Gromacs| executables will lead to a
743 smaller disk footprint when installed, and so is the default on
744 platforms where we believe it has been tested repeatedly and found to work.
745 In general, this includes Linux, Windows, Mac OS X and BSD systems.
746 Static binaries take more space, but on some hardware and/or under
747 some conditions they are necessary, most commonly when you are running a parallel
748 simulation using MPI libraries (e.g. Cray).
750 * To link |Gromacs| binaries statically against the internal |Gromacs|
751 libraries, set ``-DBUILD_SHARED_LIBS=OFF``.
752 * To link statically against external (non-system) libraries as well,
753 set ``-DGMX_PREFER_STATIC_LIBS=ON``. Note, that in
754 general ``cmake`` picks up whatever is available, so this option only
755 instructs ``cmake`` to prefer static libraries when both static and
756 shared are available. If no static version of an external library is
757 available, even when the aforementioned option is ``ON``, the shared
758 library will be used. Also note that the resulting binaries will
759 still be dynamically linked against system libraries on platforms
760 where that is the default. To use static system libraries,
761 additional compiler/linker flags are necessary, e.g. ``-static-libgcc
763 * To attempt to link a fully static binary set
764 ``-DGMX_BUILD_SHARED_EXE=OFF``. This will prevent CMake from explicitly
765 setting any dynamic linking flags. This option also sets
766 ``-DBUILD_SHARED_LIBS=OFF`` and ``-DGMX_PREFER_STATIC_LIBS=ON`` by
767 default, but the above caveats apply. For compilers which don't
768 default to static linking, the required flags have to be specified. On
769 Linux, this is usually ``CFLAGS=-static CXXFLAGS=-static``.
774 For dynamic linking builds and on non-Windows platforms, an extra library and
775 headers are installed by setting ``-DGMXAPI=ON`` (default).
776 Build targets ``gmxapi-cppdocs`` and ``gmxapi-cppdocs-dev`` produce documentation in
777 ``docs/api-user`` and ``docs/api-dev``, respectively.
778 For more project information and use cases,
779 refer to the tracked :issue:`2585`,
780 associated GitHub `gmxapi <https://github.com/kassonlab/gmxapi>`_ projects,
781 or DOI `10.1093/bioinformatics/bty484 <https://doi.org/10.1093/bioinformatics/bty484>`_.
783 gmxapi is not yet tested on Windows or with static linking, but these use cases
784 are targeted for future versions.
789 A |Gromacs| build will normally not be portable, not even across
790 hardware with the same base instruction set, like x86. Non-portable
791 hardware-specific optimizations are selected at configure-time, such
792 as the SIMD instruction set used in the compute kernels. This
793 selection will be done by the build system based on the capabilities
794 of the build host machine or otherwise specified to ``cmake`` during
797 Often it is possible to ensure portability by choosing the least
798 common denominator of SIMD support, e.g. SSE2 for x86, and ensuring
799 the you use ``cmake -DGMX_USE_RDTSCP=off`` if any of the target CPU
800 architectures does not support the ``RDTSCP`` instruction. However, we
801 discourage attempts to use a single |Gromacs| installation when the
802 execution environment is heterogeneous, such as a mix of AVX and
803 earlier hardware, because this will lead to programs (especially
804 mdrun) that run slowly on the new hardware. Building two full
805 installations and locally managing how to call the correct one
806 (e.g. using a module system) is the recommended
807 approach. Alternatively, as at the moment the |Gromacs| tools do not
808 make strong use of SIMD acceleration, it can be convenient to create
809 an installation with tools portable across different x86 machines, but
810 with separate mdrun binaries for each architecture. To achieve this,
811 one can first build a full installation with the
812 least-common-denominator SIMD instruction set, e.g. ``-DGMX_SIMD=SSE2``,
813 then build separate mdrun binaries for each architecture present in
814 the heterogeneous environment. By using custom binary and library
815 suffixes for the mdrun-only builds, these can be installed to the
816 same location as the "generic" tools installation.
817 `Building just the mdrun binary`_ is possible by setting the
818 ``-DGMX_BUILD_MDRUN_ONLY=ON`` option.
820 Linear algebra libraries
821 ~~~~~~~~~~~~~~~~~~~~~~~~
823 As mentioned above, sometimes vendor BLAS and LAPACK libraries
824 can provide performance enhancements for |Gromacs| when doing
825 normal-mode analysis or covariance analysis. For simplicity, the text
826 below will refer only to BLAS, but the same options are available
827 for LAPACK. By default, CMake will search for BLAS, use it if it
828 is found, and otherwise fall back on a version of BLAS internal to
829 |Gromacs|. The ``cmake`` option ``-DGMX_EXTERNAL_BLAS=on`` will be set
830 accordingly. The internal versions are fine for normal use. If you
831 need to specify a non-standard path to search, use
832 ``-DCMAKE_PREFIX_PATH=/path/to/search``. If you need to specify a
833 library with a non-standard name (e.g. ESSL on Power machines
834 or ARMPL on ARM machines), then
835 set ``-DGMX_BLAS_USER=/path/to/reach/lib/libwhatever.a``.
837 If you are using Intel MKL_ for FFT, then the BLAS and
838 LAPACK it provides are used automatically. This could be
839 over-ridden with ``GMX_BLAS_USER``, etc.
841 On Apple platforms where the Accelerate Framework is available, these
842 will be automatically used for BLAS and LAPACK. This could be
843 over-ridden with ``GMX_BLAS_USER``, etc.
845 .. _installing with MiMiC:
847 Building with MiMiC QM/MM support
848 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
850 MiMiC QM/MM interface integration will require linking against MiMiC
851 communication library, that establishes the communication channel
852 between |Gromacs| and CPMD. The MiMiC Communication library can be
853 downloaded `here <https://gitlab.com/MiMiC-projects/CommLib>`__.
854 Compile and install it. Check that the installation folder of the
855 MiMiC library is added to CMAKE_PREFIX_PATH if it is installed in
856 non-standard location. Building QM/MM-capable version requires
857 double-precision version of |Gromacs| compiled with MPI support:
859 * ``-DGMX_DOUBLE=ON -DGMX_MPI -DGMX_MIMIC=ON``
861 Changing the names of |Gromacs| binaries and libraries
862 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
864 It is sometimes convenient to have different versions of the same
865 |Gromacs| programs installed. The most common use cases have been single
866 and double precision, and with and without MPI. This mechanism can
867 also be used to install side-by-side multiple versions of mdrun
868 optimized for different CPU architectures, as mentioned previously.
870 By default, |Gromacs| will suffix programs and libraries for such builds
871 with ``_d`` for double precision and/or ``_mpi`` for MPI (and nothing
872 otherwise). This can be controlled manually with ``GMX_DEFAULT_SUFFIX
873 (ON/OFF)``, ``GMX_BINARY_SUFFIX`` (takes a string) and ``GMX_LIBS_SUFFIX``
874 (also takes a string). For instance, to set a custom suffix for
875 programs and libraries, one might specify:
879 cmake .. -DGMX_DEFAULT_SUFFIX=OFF -DGMX_BINARY_SUFFIX=_mod -DGMX_LIBS_SUFFIX=_mod
881 Thus the names of all programs and libraries will be appended with
884 Changing installation tree structure
885 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
887 By default, a few different directories under ``CMAKE_INSTALL_PREFIX`` are used
888 when when |Gromacs| is installed. Some of these can be changed, which is mainly
889 useful for packaging |Gromacs| for various distributions. The directories are
890 listed below, with additional notes about some of them. Unless otherwise noted,
891 the directories can be renamed by editing the installation paths in the main
895 The standard location for executables and some scripts.
896 Some of the scripts hardcode the absolute installation prefix, which needs
897 to be changed if the scripts are relocated.
898 The name of the directory can be changed using ``CMAKE_INSTALL_BINDIR`` CMake
901 The standard location for installed headers.
903 The standard location for libraries. The default depends on the system, and
904 is determined by CMake.
905 The name of the directory can be changed using ``CMAKE_INSTALL_LIBDIR`` CMake
908 Information about the installed ``libgromacs`` library for ``pkg-config`` is
909 installed here. The ``lib/`` part adapts to the installation location of the
910 libraries. The installed files contain the installation prefix as absolute
913 CMake package configuration files are installed here.
915 Various data files and some documentation go here. The first part can
916 be changed using ``CMAKE_INSTALL_DATADIR``, and the second by using
917 ``GMX_INSTALL_DATASUBDIR`` Using these CMake variables is the preferred
918 way of changing the installation path for
919 ``share/gromacs/top/``, since the path to this directory is built into
920 ``libgromacs`` as well as some scripts, both as a relative and as an absolute
921 path (the latter as a fallback if everything else fails).
923 Installed man pages go here.
925 Compiling and linking
926 ^^^^^^^^^^^^^^^^^^^^^
928 Once you have configured with ``cmake``, you can build |Gromacs| with ``make``.
929 It is expected that this will always complete successfully, and
930 give few or no warnings. The CMake-time tests |Gromacs| makes on the settings
931 you choose are pretty extensive, but there are probably a few cases we
932 have not thought of yet. Search the web first for solutions to
933 problems, but if you need help, ask on gmx-users, being sure to
934 provide as much information as possible about what you did, the system
935 you are building on, and what went wrong. This may mean scrolling back
936 a long way through the output of ``make`` to find the first error
939 If you have a multi-core or multi-CPU machine with ``N``
940 processors, then using
946 will generally speed things up by quite a bit. Other build generator systems
947 supported by ``cmake`` (e.g. ``ninja``) also work well.
949 .. _building just the mdrun binary:
954 This is now supported with the ``cmake`` option
955 ``-DGMX_BUILD_MDRUN_ONLY=ON``, which will build a different version of
956 ``libgromacs`` and the ``mdrun`` program.
957 Naturally, now ``make install`` installs only those
958 products. By default, mdrun-only builds will default to static linking
959 against |Gromacs| libraries, because this is generally a good idea for
960 the targets for which an mdrun-only build is desirable.
965 Finally, ``make install`` will install |Gromacs| in the
966 directory given in ``CMAKE_INSTALL_PREFIX``. If this is a system
967 directory, then you will need permission to write there, and you
968 should use super-user privileges only for ``make install`` and
969 not the whole procedure.
971 .. _getting access to |Gromacs|:
973 Getting access to |Gromacs| after installation
974 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
976 |Gromacs| installs the script ``GMXRC`` in the ``bin``
977 subdirectory of the installation directory
978 (e.g. ``/usr/local/gromacs/bin/GMXRC``), which you should source
983 source /your/installation/prefix/here/bin/GMXRC
985 It will detect what kind of shell you are running and set up your
986 environment for using |Gromacs|. You may wish to arrange for your
987 login scripts to do this automatically; please search the web for
988 instructions on how to do this for your shell.
990 Many of the |Gromacs| programs rely on data installed in the
991 ``share/gromacs`` subdirectory of the installation directory. By
992 default, the programs will use the environment variables set in the
993 ``GMXRC`` script, and if this is not available they will try to guess the
994 path based on their own location. This usually works well unless you
995 change the names of directories inside the install tree. If you still
996 need to do that, you might want to recompile with the new install
997 location properly set, or edit the ``GMXRC`` script.
999 Testing |Gromacs| for correctness
1000 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1002 Since 2011, the |Gromacs| development uses an automated system where
1003 every new code change is subject to regression testing on a number of
1004 platforms and software combinations. While this improves
1005 reliability quite a lot, not everything is tested, and since we
1006 increasingly rely on cutting edge compiler features there is
1007 non-negligible risk that the default compiler on your system could
1008 have bugs. We have tried our best to test and refuse to use known bad
1009 versions in ``cmake``, but we strongly recommend that you run through
1010 the tests yourself. It only takes a few minutes, after which you can
1013 The simplest way to run the checks is to build |Gromacs| with
1014 ``-DREGRESSIONTEST_DOWNLOAD``, and run ``make check``.
1015 |Gromacs| will automatically download and run the tests for you.
1016 Alternatively, you can download and unpack the |Gromacs|
1017 regression test suite |gmx-regressiontests-package| tarball yourself
1018 and use the advanced ``cmake`` option ``REGRESSIONTEST_PATH`` to
1019 specify the path to the unpacked tarball, which will then be used for
1020 testing. If the above does not work, then please read on.
1022 The regression tests are also available from the download_ section.
1023 Once you have downloaded them, unpack the tarball, source
1024 ``GMXRC`` as described above, and run ``./gmxtest.pl all``
1025 inside the regression tests folder. You can find more options
1026 (e.g. adding ``double`` when using double precision, or
1027 ``-only expanded`` to run just the tests whose names match
1028 "expanded") if you just execute the script without options.
1030 Hopefully, you will get a report that all tests have passed. If there
1031 are individual failed tests it could be a sign of a compiler bug, or
1032 that a tolerance is just a tiny bit too tight. Check the output files
1033 the script directs you too, and try a different or newer compiler if
1034 the errors appear to be real. If you cannot get it to pass the
1035 regression tests, you might try dropping a line to the gmx-users
1036 mailing list, but then you should include a detailed description of
1037 your hardware, and the output of ``gmx mdrun -version`` (which contains
1038 valuable diagnostic information in the header).
1040 A build with ``-DGMX_BUILD_MDRUN_ONLY`` cannot be tested with
1041 ``make check`` from the build tree, because most of the tests
1042 require a full build to run things like ``grompp``. To test such an
1043 mdrun fully requires installing it to the same location as a normal
1044 build of |Gromacs|, downloading the regression tests tarball manually
1045 as described above, sourcing the correct ``GMXRC`` and running the
1046 perl script manually. For example, from your |Gromacs| source
1053 cmake .. -DCMAKE_INSTALL_PREFIX=/your/installation/prefix/here
1057 mkdir build-mdrun-only
1059 cmake .. -DGMX_MPI=ON -DGMX_GPU=ON -DGMX_BUILD_MDRUN_ONLY=ON -DCMAKE_INSTALL_PREFIX=/your/installation/prefix/here
1062 cd /to/your/unpacked/regressiontests
1063 source /your/installation/prefix/here/bin/GMXRC
1064 ./gmxtest.pl all -np 2
1066 If your mdrun program has been suffixed in a non-standard way, then
1067 the ``./gmxtest.pl -mdrun`` option will let you specify that name to the
1068 test machinery. You can use ``./gmxtest.pl -double`` to test the
1069 double-precision version. You can use ``./gmxtest.pl -crosscompiling``
1070 to stop the test harness attempting to check that the programs can
1071 be run. You can use ``./gmxtest.pl -mpirun srun`` if your command to
1072 run an MPI program is called ``srun``.
1074 The ``make check`` target also runs integration-style tests that may run
1075 with MPI if ``GMX_MPI=ON`` was set. To make these work with various possible
1076 MPI libraries, you may need to
1077 set the CMake variables ``MPIEXEC``, ``MPIEXEC_NUMPROC_FLAG``,
1078 ``MPIEXEC_PREFLAGS`` and ``MPIEXEC_POSTFLAGS`` so that
1079 ``mdrun-mpi-test_mpi`` would run on multiple ranks via the shell command
1083 ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} ${NUMPROC} ${MPIEXEC_PREFLAGS} \
1084 mdrun-mpi-test_mpi ${MPIEXEC_POSTFLAGS} -otherflags
1086 A typical example for SLURM is
1090 cmake .. -DGMX_MPI=on -DMPIEXEC=srun -DMPIEXEC_NUMPROC_FLAG=-n -DMPIEXEC_PREFLAGS= -DMPIEXEC_POSTFLAGS=
1093 Testing |Gromacs| for performance
1094 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1096 We are still working on a set of benchmark systems for testing
1097 the performance of |Gromacs|. Until that is ready, we recommend that
1098 you try a few different parallelization options, and experiment with
1099 tools such as ``gmx tune_pme``.
1104 You are not alone - this can be a complex task! If you encounter a
1105 problem with installing |Gromacs|, then there are a number of
1106 locations where you can find assistance. It is recommended that you
1107 follow these steps to find the solution:
1109 1. Read the installation instructions again, taking note that you
1110 have followed each and every step correctly.
1112 2. Search the |Gromacs| webpage_ and users emailing list for information
1113 on the error. Adding
1114 ``site:https://mailman-1.sys.kth.se/pipermail/gromacs.org_gmx-users``
1115 to a Google search may help filter better results.
1117 3. Search the internet using a search engine such as Google.
1119 4. Post to the |Gromacs| users emailing list gmx-users for
1120 assistance. Be sure to give a full description of what you have
1121 done and why you think it did not work. Give details about the
1122 system on which you are installing. Copy and paste your command
1123 line and as much of the output as you think might be relevant -
1124 certainly from the first indication of a problem. In particular,
1125 please try to include at least the header from the mdrun logfile,
1126 and preferably the entire file. People who might volunteer to help
1127 you do not have time to ask you interactive detailed follow-up
1128 questions, so you will get an answer faster if you provide as much
1129 information as you think could possibly help. High quality bug
1130 reports tend to receive rapid high quality answers.
1132 .. _gmx-special-build:
1134 Special instructions for some platforms
1135 ---------------------------------------
1140 Building on Windows using native compilers is rather similar to
1141 building on Unix, so please start by reading the above. Then, download
1142 and unpack the |Gromacs| source archive. Make a folder in which to do
1143 the out-of-source build of |Gromacs|. For example, make it within the
1144 folder unpacked from the source archive, and call it ``build-gromacs``.
1146 For CMake, you can either use the graphical user interface provided on
1147 Windows, or you can use a command line shell with instructions similar
1148 to the UNIX ones above. If you open a shell from within your IDE
1149 (e.g. Microsoft Visual Studio), it will configure the environment for
1150 you, but you might need to tweak this in order to get either a 32-bit
1151 or 64-bit build environment. The latter provides the fastest
1152 executable. If you use a normal Windows command shell, then you will
1153 need to either set up the environment to find your compilers and
1154 libraries yourself, or run the ``vcvarsall.bat`` batch script provided
1155 by MSVC (just like sourcing a bash script under Unix).
1157 With the graphical user interface, you will be asked about what
1158 compilers to use at the initial configuration stage, and if you use
1159 the command line they can be set in a similar way as under UNIX.
1161 Unfortunately ``-DGMX_BUILD_OWN_FFTW=ON`` (see `Using FFTW`_) does not
1162 work on Windows, because there is no supported way to build FFTW on
1163 Windows. You can either build FFTW some other way (e.g. MinGW), or
1164 use the built-in fftpack (which may be slow), or `using MKL`_.
1166 For the build, you can either load the generated solutions file into
1167 e.g. Visual Studio, or use the command line with ``cmake --build`` so
1168 the right tools get used.
1173 |Gromacs| builds mostly out of the box on modern Cray machines, but
1174 you may need to specify the use of static binaries with
1175 ``-DGMX_BUILD_SHARED_EXE=off``, and you may need to set the F77
1176 environmental variable to ``ftn`` when compiling FFTW.
1177 The ARM ThunderX2 Cray XC50 machines differ only in that the recommended
1178 compiler is the ARM HPC Compiler (``armclang``).
1184 The built-in |Gromacs| processor detection does not work on Solaris,
1185 so it is strongly recommended that you build |Gromacs| with
1186 ``-DGMX_HWLOC=on`` and ensure that the ``CMAKE_PREFIX_PATH`` includes
1187 the path where the hwloc headers and libraries can be found. At least
1188 version 1.11.8 of hwloc is recommended.
1190 Oracle Developer Studio is not a currently supported compiler (and
1191 does not currently compile |Gromacs| correctly, perhaps because the
1192 thread-MPI atomics are incorrectly implemented in |Gromacs|).
1197 This is the architecture of the K computer, which uses Fujitsu
1198 Sparc64VIIIfx chips. On this platform, |Gromacs| has
1199 accelerated group kernels using the HPC-ACE instructions, no
1200 accelerated Verlet kernels, and a custom build toolchain. Since this
1201 particular chip only does double precision SIMD, the default setup
1202 is to build |Gromacs| in double. Since most users only need single, we have added
1203 an option GMX_RELAXED_DOUBLE_PRECISION to accept single precision square root
1204 accuracy in the group kernels; unless you know that you really need 15 digits
1205 of accuracy in each individual force, we strongly recommend you use this. Note
1206 that all summation and other operations are still done in double.
1208 The recommended configuration is to use
1212 cmake .. -DCMAKE_TOOLCHAIN_FILE=Toolchain-Fujitsu-Sparc64-mpi.cmake \
1213 -DCMAKE_PREFIX_PATH=/your/fftw/installation/prefix \
1214 -DCMAKE_INSTALL_PREFIX=/where/gromacs/should/be/installed \
1216 -DGMX_BUILD_MDRUN_ONLY=ON \
1217 -DGMX_RELAXED_DOUBLE_PRECISION=ON
1224 Xeon Phi processors, hosted or self-hosted, are supported.
1225 Only symmetric (aka native) mode is supported on Knights Corner. The
1226 performance depends among other factors on the system size, and for
1227 now the performance might not be faster than CPUs. When building for it,
1228 the recommended configuration is
1232 cmake .. -DCMAKE_TOOLCHAIN_FILE=Platform/XeonPhi
1237 The Knights Landing-based Xeon Phi processors behave like standard x86 nodes,
1238 but support a special SIMD instruction set. When cross-compiling for such nodes,
1239 use the ``AVX_512_KNL`` SIMD flavor.
1240 Knights Landing processors support so-called "clustering modes" which
1241 allow reconfiguring the memory subsystem for lower latency. |Gromacs| can
1242 benefit from the quadrant or SNC clustering modes.
1243 Care needs to be taken to correctly pin threads. In particular, threads of
1244 an MPI rank should not cross cluster and NUMA boundaries.
1245 In addition to the main DRAM memory, Knights Landing has a high-bandwidth
1246 stacked memory called MCDRAM. Using it offers performance benefits if
1247 it is ensured that ``mdrun`` runs entirely from this memory; to do so
1248 it is recommended that MCDRAM is configured in "Flat mode" and ``mdrun`` is
1249 bound to the appropriate NUMA node (use e.g. ``numactl --membind 1`` with
1250 quadrant clustering mode).
1256 While it is our best belief that |Gromacs| will build and run pretty
1257 much everywhere, it is important that we tell you where we really know
1258 it works because we have tested it. We do test on Linux, Windows, and
1259 Mac with a range of compilers and libraries for a range of our
1260 configuration options. Every commit in our git source code repository
1261 is currently tested on x86 with a number of gcc versions ranging from 5.1
1262 through 8.1, version 19 of the Intel compiler, and Clang
1263 versions 3.6 through 7. For this, we use a variety of GNU/Linux
1264 flavors and versions as well as recent versions of Windows. Under
1265 Windows, we test both MSVC 2017 and version 16 of the Intel compiler.
1266 Other compiler, library, and OS versions are tested less frequently.
1267 For details, you can
1268 have a look at the `continuous integration server used by GROMACS`_,
1269 which runs Jenkins_.
1271 We test irregularly on ARM v7, ARM v8, Cray, Fujitsu
1272 PRIMEHPC, Power8, Google Native Client and other environments, and
1273 with other compilers and compiler versions, too.