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