1 % Installation guide for GROMACS @PROJECT_VERSION@
5 These instructions pertain to building GROMACS
6 @PROJECT_VERSION@. Up-to-date installation instructions may be found
7 at <http://www.gromacs.org/Documentation/Installation_Instructions>.
9 # Quick and dirty installation #
11 1. Get the latest version of your C and C++ compilers.
12 2. Check that you have CMake version @GMX_CMAKE_MINIMUM_REQUIRED_VERSION@ or later.
13 3. Get and unpack the latest version of the GROMACS tarball.
14 4. Make a separate build directory and change to it.
15 5. Run `cmake` with the path to the source as an argument
16 6. Run `make` and `make install`
18 Or, as a sequence of commands to execute:
20 tar xfz gromacs-@PROJECT_VERSION@.tar.gz
21 cd gromacs-@PROJECT_VERSION@
24 cmake .. -DGMX_BUILD_OWN_FFTW=ON
27 source /usr/local/gromacs/bin/GMXRC
29 This will download and build first the prerequisite FFT library
30 followed by GROMACS. If you already have FFTW installed, you can
31 remove that argument to `cmake`. Overall, this build of GROMACS will
32 be correct and reasonably fast on the machine upon which `cmake`
33 ran. If you want to get the maximum value for your hardware with
34 GROMACS, you will have to read further. Sadly, the interactions of
35 hardware, libraries, and compilers are only going to continue to get
38 # Typical GROMACS installation #
40 As above, and with further details below, but you should consider
41 using the following [CMake options](#using-cmake-command-line-options) with the
42 appropriate value instead of `xxx` :
44 * `-DCMAKE_C_COMPILER=xxx` equal to the name of the C99 [compiler](#compiler) you wish to use (or the environment variable `CC`)
45 * `-DCMAKE_CXX_COMPILER=xxx` equal to the name of the C++98 [compiler](#compiler) you wish to use (or the environment variable `CXX`)
46 * `-DGMX_MPI=on` to build using an [MPI](#mpi-support) wrapper compiler
47 * `-DGMX_GPU=on` to build using nvcc to run with an NVIDIA [GPU](#native-gpu-acceleration)
48 * `-DGMX_SIMD=xxx` to specify the level of [SIMD support](#simd-support) of the node on which `mdrun` will run
49 * `-DGMX_BUILD_MDRUN_ONLY=on` to [build only the `mdrun` binary](#building-only-mdrun), e.g. for compute cluster back-end nodes
50 * `-DGMX_DOUBLE=on` to run GROMACS in double precision (slower, and not normally useful)
51 * `-DCMAKE_PREFIX_PATH=xxx` to add a non-standard location for CMake to [search for libraries](#helping-cmake-find-the-right-librariesheadersprograms)
52 * `-DCMAKE_INSTALL_PREFIX=xxx` to install GROMACS to a non-standard location (default `/usr/local/gromacs`)
53 * `-DBUILD_SHARED_LIBS=off` to turn off the building of [shared libraries](#static-linking)
54 * `-DGMX_FFT_LIBRARY=xxx` to select whether to use `fftw`, `mkl` or `fftpack` libraries for [FFT support](#fast-fourier-transform-library)
55 * `-DCMAKE_BUILD_TYPE=Debug` to build GROMACS in debug mode
57 # Building older GROMACS versions #
59 For installation instructions for old GROMACS versions, see the
61 <http://www.gromacs.org/Documentation/Installation_Instructions_4.5>
63 <http://www.gromacs.org/Documentation/Installation_Instructions_4.6>
69 GROMACS can be compiled for many operating systems and architectures.
70 These include any distribution of Linux, Mac OS X or Windows, and
71 architectures including x86, AMD64/x86-64, PPC, ARM v7 and SPARC VIII.
75 Technically, GROMACS can be compiled on any platform with an ANSI C99
76 and C++98 compiler, and their respective standard C/C++ libraries.
77 Getting good performance on an OS and architecture requires choosing a
78 good compiler. In practice, many compilers struggle to do a good job
79 optimizing the GROMACS architecture-optimized SIMD kernels.
81 For best performance, the GROMACS team strongly recommends you get the
82 most recent version of your preferred compiler for your platform.
83 There is a large amount of GROMACS code that depends on effective
84 compiler optimization to get high performance. This makes GROMACS
85 performance sensitive to the compiler used, and the binary will often
86 only work on the hardware for which it is compiled.
88 * In particular, GROMACS includes a lot of explicit SIMD
89 (single instruction, multiple data) optimization that can use
90 assembly instructions available on most modern processors. This
91 can have a substantial effect on performance, but for recent
92 processors you also need a similarly recent compiler that includes
93 support for the corresponding SIMD instruction set to get this
94 benefit. The configuration does a good job at detecting this,
95 and you will usually get warnings if GROMACS and your hardware
96 support a more recent instruction set than your compiler.
98 * On Intel-based x86 hardware, we recommend you to use the GNU
99 compilers version 4.7 or later or Intel compilers version 12 or later
100 for best performance. The Intel compiler has historically been better
101 at instruction scheduling, but recent gcc versions have proved to be
102 as fast or sometimes faster than Intel.
104 * The Intel and GNU compilers produce much faster GROMACS executables
105 than the PGI and Cray compilers.
107 * On AMD-based x86 hardware up through the "K10" microarchitecture
108 ("Family 10h") Thuban/Magny-Cours architecture (e.g. Opteron
109 6100-series processors), it is worth using the Intel compiler for
110 better performance, but gcc version 4.7 and later are also reasonable.
112 * On the AMD Bulldozer architecture (Opteron 6200), AMD introduced
113 fused multiply-add instructions and an "FMA4" instruction format not
114 available on Intel x86 processors. Thus, on the most recent AMD
115 processors you want to use gcc version 4.7 or later for best
116 performance! The Intel compiler will only generate code for the subset
117 also supported by Intel processors, and that is significantly slower.
119 * If you are running on Mac OS X, the best option is the Intel
120 compiler. Both clang and gcc will work, but they produce lower
121 performance and each have some shortcomings. Current Clang does not
122 support OpenMP. This may change when clang 3.5 becomes available.
124 * For all non-x86 platforms, your best option is typically to use the
125 vendor's default or recommended compiler, and check for specialized
128 ## Compiling with parallelization options ##
130 GROMACS can run in parallel on multiple cores of a single
131 workstation using its built-in thread-MPI. No user action is required
132 in order to enable this.
136 If you wish to use the excellent native GPU support in GROMACS,
137 NVIDIA's [CUDA](http://www.nvidia.com/object/cuda_home_new.html)
138 version @REQUIRED_CUDA_VERSION@ software development kit is required,
139 and the latest version is strongly encouraged. NVIDIA GPUs with at
140 least NVIDIA compute capability @REQUIRED_CUDA_COMPUTE_CAPABILITY@ are
141 required, e.g. Fermi or Kepler cards. You are strongly recommended to
142 get the latest CUDA version and driver supported by your hardware, but
143 beware of possible performance regressions in newer CUDA versions on
144 older hardware. Note that while some CUDA compilers (nvcc) might not
145 officially support recent versions of gcc as the back-end compiler, we
146 still recommend that you at least use a gcc version recent enough to
147 get the best SIMD support for your CPU, since GROMACS always runs some
148 code on the CPU. It is most reliable to use the same C++ compiler
149 version for GROMACS code as used as the back-end compiler for nvcc,
150 but it could be faster to mix compiler versions to suit particular
155 If you wish to run in parallel on multiple machines across a network,
156 you will need to have
158 * an MPI library installed that supports the MPI 1.3
160 * wrapper compilers that will compile code using that library.
162 The GROMACS team recommends [OpenMPI](http://www.open-mpi.org) version
163 1.6 (or higher), [MPICH](http://www.mpich.org) version 1.4.1 (or
164 higher), or your hardware vendor's MPI installation. The most recent
165 version of either of these is likely to be the best. More specialized
166 networks might depend on accelerations only available in the vendor's
167 library. [LAMMPI](http://www.lam-mpi.org) might work, but since it has
168 been deprecated for years, it is not supported.
170 Often [OpenMP](http://en.wikipedia.org/wiki/OpenMP) parallelism is an
171 advantage for GROMACS, but support for this is generally built into
172 your compiler and detected automatically.
174 In summary, for maximum performance you will need to examine how you
175 will use GROMACS, what hardware you plan to run on, and whether you
176 can afford a non-free compiler for slightly better
177 performance. Unfortunately, the only way to find out is to test
178 different options and parallelization schemes for the actual
179 simulations you want to run. You will still get *good*,
180 performance with the default build and runtime options, but if you
181 truly want to push your hardware to the performance limit, the days of
182 just blindly starting programs with `mdrun` are gone.
186 GROMACS @PROJECT_VERSION@ uses the CMake build system, and requires
187 version @GMX_CMAKE_MINIMUM_REQUIRED_VERSION@ or higher. Lower versions
188 will not work. You can check whether CMake is installed, and what
189 version it is, with `cmake --version`. If you need to install CMake,
190 then first check whether your platform's package management system
191 provides a suitable version, or visit
192 <http://www.cmake.org/cmake/help/install.html> for pre-compiled
193 binaries, source code and installation instructions. The GROMACS team
194 recommends you install the most recent version of CMake you can.
196 ## Fast Fourier Transform library ##
198 Many simulations in GROMACS make extensive use of fast Fourier
199 transforms, and a software library to perform these is always
200 required. We recommend [FFTW](http://www.fftw.org) (version 3 or
202 [Intel MKL](http://software.intel.com/en-us/intel-mkl). The choice of
203 library can be set with `cmake -DGMX_FFT_LIBRARY=<name>`, where
204 `<name>` is one of `fftw`, `mkl`, or `fftpack`. FFTPACK is bundled
205 with GROMACS as a fallback, and is acceptable if mdrun performance is
210 FFTW is likely to be available for your platform via its package
211 management system, but there can be compatibility and significant
212 performance issues associated with these packages. In particular,
213 GROMACS simulations are normally run in "mixed" floating-point
214 precision, which is suited for the use of single precision in
215 FFTW. The default FFTW package is normally in double
216 precision, and good compiler options to use for FFTW when linked to
217 GROMACS may not have been used. Accordingly, the GROMACS team
220 * that you permit the GROMACS installation to download and
221 build FFTW from source automatically for you (use
222 `cmake -DGMX_BUILD_OWN_FFTW=ON`), or
223 * that you build FFTW from the source code.
225 Note that the GROMACS-managed download of the FFTW tarball has a
226 slight chance of posing a security risk. If you use this option, you
227 will see a warning that advises how you can eliminate this risk
228 (before the opportunity has arisen).
230 If you build FFTW from source yourself, get the most recent version
231 and follow its [installation
232 guide](http://www.fftw.org/doc/Installation-and-Customization.html#Installation-and-Customization).
233 Choose the precision for FFTW (i.e. single or float vs. double) to
234 match whether you will later use mixed or double precision for
235 GROMACS. There is no need to compile FFTW with
236 threading or MPI support, but it does no harm. On x86 hardware,
237 compile *only* with `--enable-sse2` (regardless of precision) even if
238 your processors can take advantage of AVX extensions. Since GROMACS
239 uses fairly short transform lengths we do not benefit from the FFTW
240 AVX acceleration, and because of memory system performance
241 limitations, it can even degrade GROMACS performance by around
242 20%. There is no way for GROMACS to limit the use to SSE2 SIMD at run
243 time if AVX support has been compiled into FFTW, so you need to set
244 this at compile time.
248 Using MKL with the Intel Compilers version 11 or higher is very
249 simple. Set up your compiler environment correctly, perhaps with a
250 command like `source /path/to/compilervars.sh intel64` (or consult
251 your local documentation). Then set `-DGMX_FFT_LIBRARY=mkl` when you
252 run cmake. In this case, GROMACS will also use MKL for BLAS and LAPACK
254 [linear algebra libraries](#linear-algebra-libraries)). Generally,
255 there is no advantage in using MKL with GROMACS, and FFTW is often
258 Otherwise, you can get your hands dirty and configure MKL by setting
260 -DGMX_FFT_LIBRARY=mkl
261 -DMKL_LIBRARIES="/full/path/to/libone.so;/full/path/to/libtwo.so"
262 -DMKL_INCLUDE_DIR="/full/path/to/mkl/include"
264 where the full list (and order!) of libraries you require are found in
265 Intel's MKL documentation for your system.
267 ## Optional build components ##
269 * Compiling to run on NVIDIA GPUs requires CUDA
270 * An external Boost library can be used to provide better
271 implementation support for smart pointers and exception handling,
272 but the GROMACS source bundles a subset of Boost 1.55.0 as a fallback
273 * Hardware-optimized BLAS and LAPACK libraries are useful
274 for a few of the GROMACS utilities focused on normal modes and
275 matrix manipulation, but they do not provide any benefits for normal
276 simulations. Configuring these are discussed at
277 [linear algebra libraries](#linear-algebra-libraries).
278 * The built-in GROMACS trajectory viewer `gmx view` requires X11 and
279 Motif/Lesstif libraries and header files. You may prefer to use
280 third-party software for visualization, such as
281 [VMD](http://www.ks.uiuc.edu/Research/vmd) or
282 [PyMOL](http://www.pymol.org).
283 * An external TNG library for trajectory-file handling can be used,
284 but TNG 1.6 is bundled in the GROMACS source already
285 * zlib is used by TNG for compressing some kinds of trajectory data
286 * Running the GROMACS test suite requires libxml2
287 * Building the GROMACS documentation requires ImageMagick, pdflatex,
288 bibtex, doxygen and pandoc.
289 * The GROMACS utility programs often write data files in formats
290 suitable for the Grace plotting tool, but it is straightforward to
291 use these files in other plotting programs, too.
293 # Doing a build of GROMACS #
295 This section will cover a general build of GROMACS with CMake, but it
296 is not an exhaustive discussion of how to use CMake. There are many
297 resources available on the web, which we suggest you search for when
298 you encounter problems not covered here. The material below applies
299 specifically to builds on Unix-like systems, including Linux, and Mac
300 OS X. For other platforms, see the specialist instructions below.
302 ## Configuring with CMake ##
304 CMake will run many tests on your system and do its best to work out
305 how to build GROMACS for you. If your build machine is the same as
306 your target machine, then you can be sure that the defaults will be
307 pretty good. The build configuration will for instance attempt to
308 detect the specific hardware instructions available in your
309 processor. However, if you want to control aspects of the build, or
310 you are compiling on a cluster head node for back-end nodes with a
311 different architecture, there are plenty of things you can set
314 The best way to use CMake to configure GROMACS is to do an
315 "out-of-source" build, by making another directory from which you will
316 run CMake. This can be outside the source directory, or a subdirectory
317 of it. It also means you can never corrupt your source code by trying
318 to build it! So, the only required argument on the CMake command line
319 is the name of the directory containing the `CMakeLists.txt` file of
320 the code you want to build. For example, download the source tarball
323 $ tar xfz gromacs-@PROJECT_VERSION@.tgz
324 $ cd gromacs-@PROJECT_VERSION@
325 $ mkdir build-gromacs
329 You will see `cmake` report a sequence of results of tests and
330 detections done by the GROMACS build system. These are written to the
331 `cmake` cache, kept in `CMakeCache.txt`. You can edit this file by
332 hand, but this is not recommended because you could make a mistake.
333 You should not attempt to move or copy this file to do another build,
334 because file paths are hard-coded within it. If you mess things up,
335 just delete this file and start again with `cmake`.
337 If there is a serious problem detected at this stage, then you will see
338 a fatal error and some suggestions for how to overcome it. If you are
339 not sure how to deal with that, please start by searching on the web
340 (most computer problems already have known solutions!) and then
341 consult the gmx-users mailing list. There are also informational
342 warnings that you might like to take on board or not. Piping the
343 output of `cmake` through `less` or `tee` can be
346 Once `cmake` returns, you can see all the settings that were chosen
347 and information about them by using e.g. the curses interface
351 You can actually use `ccmake` (available on most Unix platforms,
352 if the curses library is supported) directly in the first step, but then
353 most of the status messages will merely blink in the lower part
354 of the terminal rather than be written to standard out. Most platforms
355 including Linux, Windows, and Mac OS X even have native graphical user interfaces for
356 `cmake`, and it can create project files for almost any build environment
357 you want (including Visual Studio or Xcode).
358 Check out <http://www.cmake.org/cmake/help/runningcmake.html> for
359 general advice on what you are seeing and how to navigate and change
360 things. The settings you might normally want to change are already
361 presented. You may make changes, then re-configure (using `c`), so that it
362 gets a chance to make changes that depend on yours and perform more
363 checking. It may take several configuration passes to reach the desired
364 configuration, in particular if you need to resolve errors.
366 A key thing to consider here is the setting of
367 `CMAKE_INSTALL_PREFIX`. You will need to be able to write to this
368 directory in order to install GROMACS later, and if you change your
369 mind later, changing it in the cache triggers a full re-build,
370 unfortunately. So if you do not have super-user privileges on your
371 machine, then you will need to choose a sensible location within your
372 home directory for your GROMACS installation. Even if you do have
373 super-user privileges, you should use them only for the installation
374 phase, and never for configuring, building, or running GROMACS!
376 When you have reached the desired configuration with `ccmake`, the
377 build system can be generated by pressing `g`. This requires that the previous
378 configuration pass did not reveal any additional settings (if it did, you need
379 to configure once more with `c`). With `cmake`, the build system is generated
380 after each pass that does not produce errors.
382 You cannot attempt to change compilers after the initial run of
383 `cmake`. If you need to change, clean up, and start again.
385 ### Using CMake command-line options ###
387 Once you become comfortable with setting and changing options, you may
388 know in advance how you will configure GROMACS. If so, you can speed
389 things up by invoking `cmake` and passing the various options at once
390 on the command line. This can be done by setting cache variable at the
391 cmake invocation using the `-DOPTION=VALUE`; note that some
392 environment variables are also taken into account, in particular
393 variables like CC, CXX, FCC (which may be familiar to autoconf users).
395 For example, the following command line
397 $ cmake .. -DGMX_GPU=ON -DGMX_MPI=ON -DCMAKE_INSTALL_PREFIX=/home/marydoe/programs
399 can be used to build with GPUs, MPI and install in a custom
400 location. You can even save that in a shell script to make it even
401 easier next time. You can also do this kind of thing with `ccmake`,
402 but you should avoid this, because the options set with `-D` will not
403 be able to be changed interactively in that run of `ccmake`.
407 GROMACS has extensive support for detecting and using the SIMD
408 capabilities of many modern HPC CPU architectures. If you are building
409 GROMACS on the same hardware you will run it on, then you don't need
410 to read more about this, unless you are getting configuration warnings
411 you do not understand. By default, the GROMACS build system will
412 detect the SIMD instruction set supported by the CPU architecture (on
413 which the configuring is done), and thus pick the best
414 available SIMD parallelization supported by GROMACS. The build system
415 will also check that the compiler and linker used also support the
416 selected SIMD instruction set and issue a fatal error if they
419 Valid values are listed below, and the
420 applicable value lowest on the list is generally the one you should
423 1. `None` For use only on an architecture either lacking SIMD,
424 or to which GROMACS has not yet been ported and none of the
425 options below are applicable.
426 2. `SSE2` This SIMD instruction set was introduced in Intel
427 processors in 2001, and AMD in 2003. Essentially all x86
428 machines in existence have this, so it might be a good choice if
429 you need to support dinosaur x86 computers too.
430 3. `SSE4.1` Present in all Intel core processors since 2007,
431 but notably not in AMD magny-cours. Still, almost all recent
432 processors support this, so this can also be considered a good
433 baseline if you are content with portability between reasonably
435 4. `AVX_128_FMA` AMD bulldozer processors (2011) have this.
436 Unfortunately Intel and AMD have diverged the last few years;
437 If you want good performance on modern AMD processors
438 you have to use this since it also allows the reset of the
439 code to use AMD 4-way fused multiply-add instructions. The drawback
440 is that your code will not run on Intel processors at all.
441 5. `AVX_256` This instruction set is present on Intel processors
442 since Sandy Bridge (2011), where it is the best choice unless
443 you have an even more recent CPU that supports AVX2. While this
444 code will work on recent AMD processors, it is significantly
445 less efficient than the AVX_128_FMA choice above - do not be
446 fooled to assume that 256 is better than 128 in this case.
447 6. `AVX2_256` Present on Intel Haswell processors released in 2013,
448 and it will also enable Intel 3-way fused multiply-add instructions.
449 This code will not work on AMD CPUs.
450 7. `IBM_QPX ` BlueGene/Q A2 cores have this.
451 8. `Sparc64_HPC_ACE` Fujitsu machines like the K computer have this.
453 The CMake configure system will check that the compiler you have
454 chosen can target the architecture you have chosen. `mdrun` will check
455 further at runtime, so if in doubt, choose the lowest setting you
456 think might work, and see what `mdrun` says. The configure system also
457 works around many known issues in many versions of common HPC
458 compilers. However, since the options also enable general compiler
459 flags for the platform in question, you can end up in situations
460 where e.g. an `AVX_128_FMA` binary will just crash on any
461 Intel machine, since the code will try to execute general illegal
462 instructions (inserted by the compiler) before `mdrun` gets to the
463 architecture detection routines.
465 A further `GMX_SIMD=Reference` option exists, which is a special
466 SIMD-like implementation written in plain C that developers can use
467 when developing support in GROMACS for new SIMD architectures. It is
468 not designed for use in production simulations, but if you are using
469 an architecture with SIMD support to which GROMACS has not yet been
470 ported, you may wish to try this option instead of the default
471 `GMX_SIMD=None`, as it can often out-perform this when the
472 auto-vectorization in your compiler does a good job. And post on the
473 GROMACS mailing lists, because GROMACS can probably be ported for new
474 SIMD architectures in a few days.
476 ### CMake advanced options ###
478 The options that are displayed in the default view of `ccmake` are
479 ones that we think a reasonable number of users might want to consider
480 changing. There are a lot more options available, which you can see by
481 toggling the advanced mode in `ccmake` on and off with `t`. Even
482 there, most of the variables that you might want to change have a
483 `CMAKE_` or `GMX_` prefix. There are also some options that will be
484 visible or not according to whether their preconditions are satisfied.
486 ### Helping CMake find the right libraries/headers/programs ###
488 If libraries are installed in non-default locations their location can
489 be specified using the following environment variables:
491 * `CMAKE_INCLUDE_PATH` for header files
492 * `CMAKE_LIBRARY_PATH` for libraries
493 * `CMAKE_PREFIX_PATH` for header, libraries and binaries
496 The respective `include`, `lib`, or `bin` is
497 appended to the path. For each of these variables, a list of paths can
498 be specified (on Unix, separated with ":"). Note that these are
499 enviroment variables (and not `cmake` command-line arguments) and in
500 a `bash` shell are used like:
502 $ CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
504 Alternatively, these variables are also `cmake` options, so they can
505 be set like `-DCMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda`.
507 The `CC` and `CXX` environment variables are also useful
508 for indicating to `cmake` which compilers to use, which can be very
509 important for maximising GROMACS performance. Similarly,
510 `CFLAGS`/`CXXFLAGS` can be used to pass compiler
511 options, but note that these will be appended to those set by
512 GROMACS for your build platform and build type. You can customize
513 some of this with advanced options such as `CMAKE_C_FLAGS`
516 See also: <http://cmake.org/Wiki/CMake_Useful_Variables#Environment_Variables>
518 ### Native GPU acceleration ###
519 If you have the CUDA Toolkit installed, you can use `cmake` with:
521 $ cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
523 (or whichever path has your installation). In some cases, you might
524 need to specify manually which of your C++ compilers should be used,
525 e.g. with the advanced option `CUDA_HOST_COMPILER`.
527 The GPU acceleration has been tested on AMD64/x86-64 platforms with
528 Linux, Mac OS X and Windows operating systems, but Linux is the
529 best-tested and supported of these. Linux running on ARM v7 (32 bit)
532 ### Static linking ###
533 Dynamic linking of the GROMACS executables will lead to a
534 smaller disk footprint when installed, and so is the default on
535 platforms where we believe it has been tested repeatedly and found to work.
536 In general, this includes Linux, Windows, Mac OS X and BSD systems.
537 Static binaries take much more space, but on some hardware and/or under
538 some conditions they are necessary, most commonly when you are running a parallel
539 simulation using MPI libraries (e.g. BlueGene, Cray).
541 * To link GROMACS binaries
542 statically against the internal GROMACS libraries, set
543 `-DBUILD_SHARED_LIBS=OFF`.
544 * To link statically against external (non-system) libraries as well,
545 the `-DGMX_PREFER_STATIC_LIBS=ON` option can be used. Note, that in
546 general `cmake` picks up whatever is available, so this option only
547 instructs `cmake` to prefer static libraries when both static and
548 shared are available. If no static version of an external library is
549 available, even when the aforementioned option is `ON`, the shared
550 library will be used. Also note, that the resulting binaries will
551 still be dynamically linked against system libraries on platforms
552 where that is the default. To use static system libraries, additional
553 compiler/linker flags are necessary, e.g. `-static-libgcc
556 ### Portability aspects ###
558 Here, we consider portability aspects related to CPU instruction sets,
559 for details on other topics like binaries with statical vs dynamic
560 linking please consult the relevant parts of this documentation or
561 other non-GROMACS specific resources.
563 A GROMACS build will normally not be portable, not even across
564 hardware with the same base instruction set like x86. Non-portable
565 hardware-specific optimizations are selected at configure-time, such
566 as the SIMD instruction set used in the compute-kernels. This
567 selection will be done by the build system based on the capabilities
568 of the build host machine or based on cross-compilation information
569 provided to `cmake` at configuration.
571 Often it is possible to ensure portability by choosing the least
572 common denominator of SIMD support, e.g. SSE2 for x86, and ensuring
573 the you use `cmake -DGMX_USE_RDTSCP=off` if any of the target CPU
574 architectures does not support the `RDTSCP` instruction. However, we
575 discourage attempts to use a single GROMACS installation when the
576 execution environment is heterogeneous, such as a mix of AVX and
577 earlier hardware, because this will lead to programs (especially
578 `mdrun`) that run slowly on the new hardware. Building two full
579 installations and locally managing how to call the correct one
580 (e.g. using the module system) is the recommended
581 approach. Alternatively, as at the moment the GROMACS tools do not
582 make strong use of SIMD acceleration, it can be convenient to create
583 an installation with tools portable across different x86 machines, but
584 with separate `mdrun` binaries for each architecture. To achieve this,
585 one can first build a full installation with the
586 least-common-denominator SIMD instruction set, e.g. `-DGMX_SIMD=SSE2`,
587 then build separate `mdrun` binaries for each architecture present in
588 the heterogeneous environment. By using custom binary and library
589 suffixes for the `mdrun`-only builds, these can be installed to the
590 same location as the "generic" tools installation. Building [only the
591 `mdrun` binary](#building-only-mdrun) is possible by setting the `-DGMX_BUILD_MDRUN_ONLY=ON`
594 ### Linear algebra libraries ###
596 As mentioned above, sometimes vendor BLAS and LAPACK libraries
597 can provide performance enhancements for GROMACS when doing
598 normal-mode analysis or covariance analysis. For simplicity, the text
599 below will refer only to BLAS, but the same options are available
600 for LAPACK. By default, CMake will search for BLAS, use it if it
601 is found, and otherwise fall back on a version of BLAS internal to
602 GROMACS. The `cmake` option `-DGMX_EXTERNAL_BLAS=on` will be set
603 accordingly. The internal versions are fine for normal use. If you
604 need to specify a non-standard path to search, use
605 `-DCMAKE_PREFIX_PATH=/path/to/search`. If you need to specify a
606 library with a non-standard name (e.g. ESSL on AIX or BlueGene), then
607 set `-DGMX_BLAS_USER=/path/to/reach/lib/libwhatever.a`.
609 If you are using Intel MKL for FFT, then the BLAS and
610 LAPACK it provides are used automatically. This could be
611 over-ridden with `GMX_BLAS_USER`, etc.
613 On Apple platforms where the Accelerate Framework is available, these
614 will be automatically used for BLAS and LAPACK. This could be
615 over-ridden with `GMX_BLAS_USER`, etc.
617 ### Changing the names of GROMACS binaries and libraries ###
619 It is sometimes convenient to have different versions of the same
620 GROMACS programs installed. The most common use cases have been single
621 and double precision, and with and without MPI. This mechanism can
622 also be used to install side-by-side multiple versions of `mdrun`
623 optimized for different CPU architectures, as mentioned previously.
625 By default, GROMACS will suffix programs and libraries for such builds
626 with `_d` for double precision and/or `_mpi` for MPI (and nothing
627 otherwise). This can be controlled manually with `GMX_DEFAULT_SUFFIX
628 (ON/OFF)`, `GMX_BINARY_SUFFIX` (takes a string) and `GMX_LIBS_SUFFIX`
629 (also takes a string). For instance, to set a custom suffix for
630 programs and libraries, one might specify:
632 cmake .. -DGMX_DEFAULT_SUFFIX=OFF -DGMX_BINARY_SUFFIX=_mod -DGMX_LIBS_SUFFIX=_mod
634 Thus the names of all programs and libraries will be appended with
637 ### Changing installation tree structure ###
639 By default, a few different directories under `CMAKE_INSTALL_PREFIX` are used
640 when when GROMACS is installed. Some of these can be changed, which is mainly
641 useful for packaging GROMACS for various distributions. The directories are
642 listed below, with additional notes about some of them. Unless otherwise noted,
643 the directories can be renamed by editing the installation paths in the main
647 : The standard location for executables, some scripts, and some symlinks.
648 Some of the scripts hardcode the absolute installation prefix, which needs
649 to be changed if the scripts are relocated.
651 : The standard location for installed headers.
653 : The standard location for libraries. The default depends on the system, and
654 is determined by CMake.
655 The name of the directory can be changed using `GMX_LIB_INSTALL_DIR` CMake
658 : Various data files and some documentation go here.
659 The `gromacs` part can be changed using `GMX_DATA_INSTALL_DIR`. Using this
660 CMake variable is the preferred way of changing the installation path for
661 `share/gromacs/top/`, since the path to this directory is built into
662 `libgromacs` as well as some scripts, both as a relative and as an absolute
663 path (the latter as a fallback if everything else fails).
665 : Installed man pages go here.
667 ## Building GROMACS ##
669 Once you have configured with `cmake`, you can build GROMACS. It is
670 expected that the `make` procedure will always complete successfully,
671 and give few or no warnings. The tests GROMACS makes on the settings
672 you choose are pretty extensive, but there are probably a few cases we
673 have not thought of yet. Search the web first for solutions to
674 problems, but if you need help, ask on gmx-users, being sure to
675 provide as much information as possible about what you did, the system
676 you are building on, and what went wrong. This may mean scrolling back
677 a long way through the output of `make` to find the first error
680 If you have a multi-core or multi-CPU machine with `N`
681 processors, then using
683 will generally speed things up by quite a bit. Other build generator systems
684 supported by `cmake` (e.g. `ninja`) also work well.
686 ### Building only mdrun ###
688 Past versions of the build system offered "mdrun" and "install-mdrun"
689 targets (similarly for other programs too) to build and install only
690 the mdrun program, respectively. Such a build is useful when the
691 configuration is only relevant for `mdrun` (such as with
692 parallelization options for MPI, SIMD, GPUs, or on BlueGene or Cray),
693 or the length of time for the compile-link-install cycle is relevant
696 This is now supported with the `cmake` option
697 `-DGMX_BUILD_MDRUN_ONLY=ON`, which will build a cut-down version of
698 `libgromacs` and/or the `mdrun` program (according to whether shared
699 or static). Naturally, now `make install` installs only those
700 products. By default, mdrun-only builds will default to static linking
701 against GROMACS libraries, because this is generally a good idea for
702 the targets for which an mdrun-only build is desirable. If you re-use
703 a build tree and change to the mdrun-only build, then you will inherit
704 the setting for `BUILD_SHARED_LIBS` from the old build, and will be
705 warned that you may wish to manage `BUILD_SHARED_LIBS` yourself.
707 ## Installing GROMACS ##
709 Finally, `make install` will install GROMACS in the
710 directory given in `CMAKE_INSTALL_PREFIX`. If this is a system
711 directory, then you will need permission to write there, and you
712 should use super-user privileges only for `make install` and
713 not the whole procedure.
715 ## Getting access to GROMACS after installation ##
717 GROMACS installs the script `GMXRC` in the `bin`
718 subdirectory of the installation directory
719 (e.g. `/usr/local/gromacs/bin/GMXRC`), which you should source
722 $ source /your/installation/prefix/here/bin/GMXRC
724 It will detect what kind of shell you are running and set up your
725 environment for using GROMACS. You may wish to arrange for your
726 login scripts to do this automatically; please search the web for
727 instructions on how to do this for your shell.
729 Many of the GROMACS programs rely on data installed in the
730 `share/gromacs` subdirectory of the installation directory. By
731 default, the programs will use the environment variables set in the
732 `GMXRC` script, and if this is not available they will try to guess the
733 path based on their own location. This usually works well unless you
734 change the names of directories inside the install tree. If you still
735 need to do that, you might want to recompile with the new install
736 location properly set, or edit the `GMXRC` script.
738 ## Testing GROMACS for correctness ##
740 Since 2011, the GROMACS development uses an automated system where
741 every new code change is subject to regression testing on a number of
742 platforms and software combinations. While this improves
743 reliability quite a lot, not everything is tested, and since we
744 increasingly rely on cutting edge compiler features there is
745 non-negligible risk that the default compiler on your system could
746 have bugs. We have tried our best to test and refuse to use known bad
747 versions in `cmake`, but we strongly recommend that you run through
748 the tests yourself. It only takes a few minutes, after which you can
751 The simplest way to run the checks is to build GROMACS with
752 `-DREGRESSIONTEST_DOWNLOAD`, and run `make check`.
753 GROMACS will automatically download and run the tests for you.
754 Alternatively, you can download and unpack the tarball yourself from
755 <http://gerrit.gromacs.org/download/regressiontests-@REGRESSIONTEST_VERSION@.tar.gz>,
756 and use the advanced `cmake` option `REGRESSIONTEST_PATH` to
757 specify the path to the unpacked tarball, which will then be used for
758 testing. If the above does not work, then please read on.
760 The regression tests are available from the GROMACS website and ftp
761 site. Once you have downloaded them, unpack the tarball, source
762 `GMXRC` as described above, and run `./gmxtest.pl all`
763 inside the regression tests folder. You can find more options
764 (e.g. adding `double` when using double precision, or
765 `-only expanded` to run just the tests whose names match
766 "expanded") if you just execute the script without options.
768 Hopefully, you will get a report that all tests have passed. If there
769 are individual failed tests it could be a sign of a compiler bug, or
770 that a tolerance is just a tiny bit too tight. Check the output files
771 the script directs you too, and try a different or newer compiler if
772 the errors appear to be real. If you cannot get it to pass the
773 regression tests, you might try dropping a line to the gmx-users
774 mailing list, but then you should include a detailed description of
775 your hardware, and the output of `mdrun -version` (which contains
776 valuable diagnostic information in the header).
778 A build with `-DGMX_BUILD_MDRUN_ONLY` cannot be tested with
779 `make check` from the build tree, because most of the tests
780 require a full build to run things like `grompp`. To test such an
781 mdrun fully requires installing it to the same location as a normal
782 build of GROMACS, downloading the regression tests tarball manually
783 as described above, sourcing the correct `GMXRC` and running the
784 perl script manually. For example, from your GROMACS source
789 $ cmake .. -DCMAKE_INSTALL_PREFIX=/your/installation/prefix/here
793 $ mkdir build-mdrun-only
794 $ cd build-mdrun-only
795 $ cmake .. -DGMX_MPI=ON -DGMX_GPU=ON -DGMX_BUILD_MDRUN_ONLY=ON -DCMAKE_INSTALL_PREFIX=/your/installation/prefix/here
798 $ cd /to/your/unpacked/regressiontests
799 $ source /your/installation/prefix/here/bin/GMXRC
800 $ ./gmxtest.pl all -np 2
802 If your `mdrun` program has been suffixed in a non-standard way, then
803 the `./gmxtest.pl -mdrun` option will let you specify that name to the
804 test machinery. You can use `./gmxtest.pl -double` to test the
805 double-precision version. You can use `./gmxtest.pl -crosscompiling`
806 to stop the test harness attempting to check that the programs can
810 ## Testing GROMACS for performance ##
811 We are still working on a set of benchmark systems for testing
812 the performance of GROMACS. Until that is ready, we recommend that
813 you try a few different parallelization options, and experiment with
814 tools such as `gmx tune_pme`.
816 ## Having difficulty? ##
817 You are not alone - this can be a complex task! If you encounter a
818 problem with installing GROMACS, then there are a number of
819 locations where you can find assistance. It is recommended that you
820 follow these steps to find the solution:
822 1. Read the installation instructions again, taking note that you
823 have followed each and every step correctly.
825 2. Search the GROMACS website and users emailing list for information
827 "site:https://mailman-1.sys.kth.se/pipermail/gromacs.org_gmx-users"
828 to a Google search may help filter better results.
830 3. Search the internet using a search engine such as Google.
832 4. Post to the GROMACS users emailing list gmx-users for
833 assistance. Be sure to give a full description of what you have
834 done and why you think it did not work. Give details about the
835 system on which you are installing. Copy and paste your command
836 line and as much of the output as you think might be relevant -
837 certainly from the first indication of a problem. In particular,
838 please try to include at least the header from the mdrun logfile,
839 and preferably the entire file. People who might volunteer to help
840 you do not have time to ask you interactive detailed follow-up
841 questions, so you will get an answer faster if you provide as much
842 information as you think could possibly help. High quality bug
843 reports tend to receive rapid high quality answers.
845 # Special instructions for some platforms #
847 ## Building on Windows ##
849 Building on Windows using native compilers is rather similar to
850 building on Unix, so please start by reading the above. Then, download
851 and unpack the GROMACS source archive. Make a folder in which to do
852 the out-of-source build of GROMACS. For example, make it within the
853 folder unpacked from the source archive, and call it `build-gromacs`.
855 For CMake, you can either use the graphical user interface provided on
856 Windows, or you can use a command line shell with instructions similar
857 to the UNIX ones above. If you open a shell from within your IDE
858 (e.g. Microsoft Visual Studio), it will configure the environment for
859 you, but you might need to tweak this in order to get either a 32-bit
860 or 64-bit build environment. The latter provides the fastest
861 executable. If you use a normal Windows command shell, then you will
862 need to either set up the environment to find your compilers and
863 libraries yourself, or run the `vcvarsall.bat` batch script provided
864 by MSVC (just like sourcing a bash script under Unix).
866 With the graphical user interface, you will be asked about what
867 compilers to use at the initial configuration stage, and if you use
868 the command line they can be set in a similar way as under UNIX. You
869 will probably make your life easier and faster by using the new
870 facility to download and install FFTW automatically.
872 For the build, you can either load the generated solutions file into
873 e.g. Visual Studio, or use the command line with `cmake --build` so
874 the right tools get used.
876 ## Building on Cray ##
878 GROMACS builds mostly out of the box on modern Cray machines, but
879 * you may need to specify the use of static or dynamic libraries
880 (depending on the machine) with `-DBUILD_SHARED_LIBS=off`,
881 * you may need to set the F77 environmental variable to `ftn` when
883 * you may need to use `-DCMAKE_SKIP_RPATH=YES`, and
884 * you may need to modify the CMakeLists.txt files to specify the
885 `BUILD_SEARCH_END_STATIC` target property.
887 ## Building on BlueGene ##
891 There is currently native acceleration on this platform for the Verlet
892 cut-off scheme. There are no plans to provide accelerated kernels for
893 the group cut-off scheme, but the default plain C kernels will work
896 Only static linking with XL compilers is supported by GROMACS. Dynamic
897 linking would be supported by the architecture and GROMACS, but has no
898 advantages other than disk space, and is generally discouraged on
899 BlueGene for performance reasons.
901 Computation on BlueGene floating-point units is always done in
902 double-precision. However, mixed-precision builds of GROMACS are still
903 normal and encouraged since they use cache more efficiently. The
904 BlueGene hardware automatically converts values stored in single
905 precision in memory to double precision in registers for computation,
906 converts the results back to single precision correctly, and does so
907 for no additional cost. As with other platforms, doing the whole
908 computation in double precision normally shows no improvement in
909 accuracy and costs twice as much time moving memory around.
911 You need to arrange for FFTW to be installed correctly, following the
914 `mpicc` is used for compiling and linking. This can make it awkward to
915 attempt to use IBM's optimized BLAS/LAPACK called ESSL (see the
917 [linear algebra libraries](#linear-algebra-libraries)). Since mdrun is
918 the only part of GROMACS that should normally run on the compute
919 nodes, and there is nearly no need for linear algebra support for
920 mdrun, it is recommended to use the GROMACS built-in linear algebra
921 routines - it is rare for this to run slowly.
923 The recommended configuration is to use
925 cmake .. -DCMAKE_TOOLCHAIN_FILE=Platform/BlueGeneQ-static-XL-CXX \
926 -DCMAKE_PREFIX_PATH=/your/fftw/installation/prefix \
928 -DGMX_BUILD_MDRUN_ONLY=ON
932 which will build a statically-linked MPI-enabled mdrun for the compute
933 nodes. Otherwise, GROMACS default configuration behaviour applies.
935 It is possible to configure and make the remaining GROMACS tools with
936 the compute-node toolchain, but as none of those tools are MPI-aware
937 and could then only run on the compute nodes, this would not normally
938 be useful. Instead, these should be planned to run on the login node,
939 and a separate GROMACS installation performed for that using the login
940 node's toolchain - not the above platform file, or any other
941 compute-node toolchain.
943 Note that only the MPI build is available for the compute-node
944 toolchains. The GROMACS thread-MPI or no-MPI builds are not useful at
949 There is currently no SIMD support on this platform and no plans to
950 add it. The default plain C kernels will work.
952 ### Fujitsu PRIMEHPC ###
954 This is the architecture of the K computer, which uses Fujitsu
955 `Sparc64VIIIfx` chips. On this platform, GROMACS @PROJECT_VERSION@ has
956 accelerated group kernels, no accelerated Verlet kernels, and a custom
959 ### Intel Xeon Phi ###
961 GROMACS @PROJECT_VERSION@ has preliminary support for Intel Xeon Phi. Only symmetric
962 (aka native) mode is supported. GROMACS is functional on Xeon Phi, but
963 it has so far not been optimized to the same level as other
964 architectures have. The performance depends among other factors on the
966 now the performance might not be faster than CPUs. Building for Xeon
967 Phi works almost as any other Unix. See the instructions above for
968 details. The recommended configuration is
970 cmake .. -DCMAKE_TOOLCHAIN_FILE=Platform/XeonPhi
976 While it is our best belief that GROMACS will build and run pretty
977 much everywhere, it is important that we tell you where we really know
978 it works because we have tested it. We do test on Linux, Windows, and
979 Mac with a range of compilers and libraries for a range of our
980 configuration options. Every commit in our git source code repository
981 is currently tested on x86 with gcc versions ranging from 4.4 through
982 4.7, and versions 12 and 13 of the Intel compiler as well as Clang
983 version 3.1 through 3.4. For this, we use a variety of GNU/Linux
984 flavors and versions as well as recent version of Mac OS X. Under
985 Windows we test both MSVC and the Intel compiler. For details, you can
986 have a look at the continuous integration server at
987 <http://jenkins.gromacs.org>.
989 We test irregularly on ARM v7, BlueGene/Q, Cray, Fujitsu PRIMEHPC, Google
990 Native Client and other environments, and with other compilers and
991 compiler versions, too.