1 % Process from LaTeX via XML to XHTML with
2 % latexml --destination installguide.xml --xml installguide.tex
3 % latexmlpost --destination installguide.xhtml --format=xhtml installguide.xml
5 % Crude hack to remove ugly symbols:
6 % sed -e 's/§//g' -i installguide.xhtml
8 % Strip off header for pasting into the website at
9 % http://www.gromacs.org/Documentation/Installation_Instructions:
11 % grep -A 99999 "class=\"main\"" installguide.xhtml > installguide_web.xhtml
13 \documentclass{article}[12pt,a4paper,twoside]
15 % haven't made these work with LaTeXML yet...
16 %\usepackage[strings]{underscore}
17 %\usepackage[english]{babel}
19 \title{GROMACS installation guide}
21 % macros to keep style uniform
22 \newcommand{\gromacs}{GROMACS}
23 \newcommand{\nvidia}{NVIDIA}
24 \newcommand{\cuda}{CUDA}
25 \newcommand{\fftw}{FFTW}
26 \newcommand{\mkl}{MKL}
27 \newcommand{\mpi}{MPI}
28 \newcommand{\threadmpi}{ThreadMPI}
29 \newcommand{\openmpi}{OpenMPI}
30 \newcommand{\openmp}{OpenMP}
31 \newcommand{\openmm}{OpenMM}
32 \newcommand{\lammpi}{LAM/MPI}
33 \newcommand{\mpich}{MPICH}
34 \newcommand{\cmake}{CMake}
35 \newcommand{\sse}{SSE}
36 \newcommand{\ssetwo}{SSE2}
37 \newcommand{\avx}{AVX}
38 \newcommand{\fft}{FFT}
39 \newcommand{\blas}{BLAS}
40 \newcommand{\lapack}{LAPACK}
41 \newcommand{\vmd}{VMD}
42 \newcommand{\pymol}{PyMOL}
43 \newcommand{\grace}{Grace}
47 % later, make CMake keep this version current for us
48 \newcommand{\fftwversion}{3.3.2}
49 \newcommand{\cmakeversion}{2.8.0}
50 \newcommand{\cudaversion}{3.2}
53 \section{Building GROMACS}
55 These instructions pertain to building \gromacs{} 4.6 and newer releases
56 using our new CMake-based build system.
57 For installations instructions for old \gromacs{} versions,
58 see the documentation at
59 \url{http://www.gromacs.org/Documentation/Installation_Instructions_4.5}.
61 \section{Quick and dirty installation}
64 \item Get the latest version of your compiler.
65 \item Check you have \cmake{} version 2.8.x or later.
66 \item Unpack the \gromacs{} tarball.
67 \item Make a separate build directory and change to it.
68 \item Run \cmake{} with the path to the source as an argument
69 \item Run make and make install
71 Or, as a sequence of commands to execute:
73 tar xfz gromacs-4.6.1.tar.gz
77 cmake .. -DGMX_BUILD_OWN_FFTW=ON
81 This will download and build first the prerequisite FFT library followed by \gromacs{}. If you already have
82 FFTW installed, you can remove that argument to cmake. Overall, this build
83 of \gromacs{} will be correct and reasonably fast on the
84 machine upon which \cmake{} ran. It will generally be 30-50\% faster
85 than \gromacs{} 4.5.x, but if you want to get the maximum value
86 for your hardware with \gromacs{}, you'll have to read further.
87 Sadly, the interactions of hardware, libraries, and compilers
88 are only going to continue to get more complex.
90 \section{Prerequisites}
92 \gromacs{} can be compiled for any distribution of Linux, Mac OS X,
93 Windows (native, Cygwin or MinGW), BlueGene, Cray and many other architectures.
94 Technically, it can be compiled on any platform with an ANSI C
95 compiler and supporting libraries, such as the GNU C library. However, Gromacs
96 also comes with many hardware-specific extensions to provide very high performance
97 on those platforms, and to enable these we have slightly more specific requirements
98 since old compilers do not support new features, or they can be buggy.
100 \subsection{Compiler}
102 \gromacs{} requires an ANSI C compiler that complies with the C89
103 standard. For best performance, the \gromacs{} team strongly
104 recommends you get the most recent version of your preferred compiler
105 for your platform (e.g. GCC 4.7 or Intel 12.0 or newer on x86
106 hardware). There is a large amount of \gromacs{} code introduced in
107 version 4.6 that depends on effective compiler optimization to get
108 high performance - the old raw assembly-language kernel routines are all gone.
109 Unfortunately this makes \gromacs{} more sensitive to the compiler
110 used, and the binary will only work on the hardware for which it is compiled,
111 but the good news is that it has enabled us to significantly accelerate performance
112 compared to version 4.5.
115 \item On Intel-based x86 hardware, we recommend you to use
116 the Intel compiler for best performance. It is usually better at instruction
117 scheduling, although it does not hurt to try gcc too. Recent versions can
118 give icc a run for the money.
119 \item On AMD-based x86 hardware up through the Magny-Cours architecture
120 (e.g. Opteron 6100-series processors), it is worth using the Intel compiler for
121 better performance, but gcc-4.7 and later are also reasonable.
122 \item On the AMD Bulldozer architecture (Opteron 6200), AMD introduced fused multiply-add
123 instructions and an "FMA4" instruction format not available on Intel x86 processors. Thus,
124 on the most recent AMD processors you want to use gcc-4.7 or later for better performance!
125 icc will only generate code for the subset also supported by Intel processors, and that
126 is significantly slower right now.
127 \item If you are running on Mac OS X, the best option is the Intel compiler.
128 Both clang and gcc will work, but they produce lower performance and each have some
129 shortcomings. Clang does not fully support OpenMP, and the current gcc ports do not
130 support AVX instructions.
131 \item For all non-x86 platforms, your best option is typically to use the vendor's
132 default compiler, and check for specialized information below.
135 \subsubsection{Running in parallel}
137 \gromacs{} can run in parallel on multiple cores of a single
138 workstation using its built-in \threadmpi. No user action is required
139 in order to enable this.
141 If you wish to use the excellent new native GPU support in \gromacs,
143 \url{http://www.nvidia.com/object/cuda_home_new.html} version
144 \cudaversion{} software development kit is required, and the latest
145 version is strongly encouraged. \nvidia{} GPUs with at least \nvidia{} compute
146 capability 2.0 are required, e.g. Fermi or Kepler cards.
148 The GPU support from \gromacs{} version 4.5 using \openmm{}
149 \url{https://simtk.org/home/openmm} is still contained in the code,
150 but in the ``user contributions'' section (\verb+src/contrib+). You
152 \verb+-DGMX_OPENMM=on -DGMX_GPU=off -DGMX_MPI=off
153 -DGMX_THREAD_MPI=off\+ in order to build it. It also requires \cuda{},
154 and remains the only hardware-based acceleration available for
155 implicit solvent simulations in \gromacs{} at the moment. However, the
156 long-term plan is to enable this functionality in core Gromacs, and
157 not have the OpenMM interface supported by the \gromacs team.
159 If you wish to run in parallel on multiple machines across a network,
160 you will need to have
162 \item an \mpi{} library installed that supports the \mpi{} 1.3
164 \item wrapper compilers that will compile code using that library.
166 The \gromacs{} team recommends \openmpi{}
167 \url{http://www.open-mpi.org/} version 1.4.1 (or higher), \mpich{}
168 \url{http://www.mpich.org/} version 1.4.1 (or higher), or your
169 hardware vendor's \mpi{} installation. The most recent version of
170 either of this is likely to be the best. More specialized networks
171 might depend on accelerations only available in the vendor's library.
173 \url{http://www.lam-mpi.org/} might work, but since it has been
174 deprecated for years, it is not supported.
176 In some cases, \openmp{} parallelism is an advantage for \gromacs{},
177 but support for this is generally built into your compiler and detected
178 automatically. The one common exception is Mac OS X, where the default
179 clang compiler currently does not fully support OpenMP. You can install
180 gcc-4.7 instead, but the currently available binary distribution of gcc
181 uses an old system assembler that does not support AVX acceleration
182 instructions. There are some examples on the internet where people have
183 hacked this to work, but presently the only straightforward way to get
184 both OpenMP and AVX support on Mac OS X is to get the Intel compiler.
186 In summary, for maximum performance you will need to
187 examine how you will use \gromacs{}, what hardware you plan to run
188 on, and whether you can afford a non-free compiler for slightly better
189 performance. The only way to find out is unfortunately to test different
190 options and parallelization schemes for the actual simulations you
191 want to run. You will still get {\em good}\, performance with the default
192 build and runtime options (better than in version 4.5), but if you truly
193 want to push your hardware to the performance limit the days of just blindly
194 starting programs like '\verb+mdrun+' are gone.
198 From version 4.6, \gromacs{} uses the build system
199 \cmake{}. The previous build system that used \verb+configure+ from
200 the GNU autotools package has been removed permanently. \cmake{}
201 permits the \gromacs{} team to support a very wide range of hardware,
202 compilers and build configurations while continuing to provide the
203 portability, robustness and performance for which \gromacs{} is known.
205 \gromacs{} requires \cmake{} version \cmakeversion{} or higher. Lower
206 versions will not work. You can check whether \cmake{} is installed,
207 and what version it is, with \verb+cmake --version+. If you need to
208 install \cmake{}, then first check whether your platform's package
209 management system provides a suitable version, or visit
210 \url{http://www.cmake.org/cmake/help/install.html} for pre-compiled
211 binaries, source code and installation instructions. The \gromacs{}
212 team recommends you install the most recent version of \cmake{} you
213 can. If you need to compile \cmake{} yourself and have a really old environment,
214 you might first have to compile a moderately recent version (say, 2.6) to
215 bootstrap version 2.8. This is a one-time job, and you can find lots of
216 documentation on the \cmake{} website if you run into problems.
218 \subsection{Fast Fourier Transform library}
220 Many simulations in \gromacs{} make extensive use of fast Fourier transforms,
221 and a software library to perform these is always required. We
222 recommend \fftw{} \url{http://www.fftw.org/} (version 3 or higher
223 only) or Intel's \mkl{} \url{http://software.intel.com/en-us/intel-mkl}.
225 \subsubsection{\fftw{}}
227 \fftw{} is likely to be available for your platform via its package
228 management system, but there can be compatibility and significant
229 performance issues associated with these packages. In particular,
230 \gromacs{} simulations are normally run in single floating-point
231 precision whereas the default \fftw{} package is normally in double
232 precision, and good compiler options to use for \fftw{} when linked to
233 \gromacs{} may not have been used. Accordingly, the \gromacs{} team
236 \item that you permit the \gromacs{} installation to download and
237 build \fftw{} \fftwversion{} from source automatically for you (use
238 \verb+cmake -DGMX_BUILD_OWN_FFTW=ON+), or
239 \item that you build \fftw{} from the source code.
242 If you build \fftw{} from source yourself, get the most recent version
243 and follow its installation guide available from \url{http://www.fftw.org}.
244 Choose the precision (i.e. single or float vs.\ double) to match what you will
245 later require for \gromacs{}. There is no need to compile with
246 threading or \mpi{} support, but it does no harm. On x86 hardware,
247 compile \emph{only} with \verb+--enable-sse2+ (regardless of
248 precision) even if your processors can take advantage of \avx{}
249 extensions. Since \gromacs{} uses fairly short transform lengths we
250 do not benefit from the \fftw{} \avx{} acceleration, and because of
251 memory system performance limitations, it can even degrade \gromacs{}
252 performance by around 20\%. There is no way for \gromacs{} to
253 limit the use to \ssetwo{} acceleration at run time if \avx{}
254 support has been compiled into \fftw{}, so you need to set this at compile time.
256 \subsubsection{\mkl{}}
258 Using \mkl{} with \icc{} 11 or higher is very simple. Set up your
259 compiler environment correctly, perhaps with a command like
260 \verb+source /path/to/compilervars.sh intel64+ (or consult your local
261 documentation). Then set \verb+-DGMX_FFT_LIBRARY=mkl+ when you run
262 \cmake{}. In this case, \gromacs{} will also use \mkl{} for \blas{}
263 and \lapack{} (see \hyperref{linear-algebra}{here}).
265 Otherwise, you can configure \mkl{} by setting
266 \verb+-DGMX_FFT_LIBRARY=mkl
267 -DMKL_LIBRARIES="/full/path/to/libone.so;/full/path/to/libtwo.so"
268 -DMKL_INCLUDE_DIR="/full/path/to/mkl/include"+,
269 where the full list (and order!) of libraries you require are found in
270 Intel's \mkl{} documentation for your system.
272 \subsection{Optional build components}
275 \item Hardware-optimized \blas{} and \lapack{} libraries are useful
276 for a few of the \gromacs{} utilities focused on normal modes and
277 matrix manipulation, but they do not provide any benefits for normal
278 simulations. Configuring these are discussed
279 \hyperlink{linear-algebra}{here}.
280 \item The built-in \gromacs{} trajectory viewer \verb+ngmx+ requires
281 X11 and Motif/Lesstif libraries and header files. Generally, the
282 \gromacs{} team rather recommends you use third-party software for
283 visualization, such as \vmd{}
284 \url{http://www.ks.uiuc.edu/Research/vmd/} or \pymol{}
285 \url{http://www.pymol.org/}.
286 \item A few \gromacs{} tools get some extra functionality when linked with the
287 GNU scientific library GSL.
290 \section{Doing a build of \gromacs}
292 This section will cover a general build of \gromacs{} with \cmake{},
293 but it is not an exhaustive discussion of how to use \cmake{}. There
294 are many resources available on the web, which we suggest you search
295 for when you encounter problems not covered here. The material below
296 applies specifically to builds on Unix-like systems, including Linux,
297 Mac OS X, MinGW and Cygwin. For other platforms, see the specialist
300 \subsection{Configuring with \cmake{}}
302 \cmake{} will run many tests on your system and do its best to work
303 out how to build \gromacs{} for you. If you are building \gromacs{} on
304 hardware that is identical to that where you will run \verb+mdrun+,
305 then you can be sure that the defaults will be pretty good. The build
306 configuration will for instance attempt to detect the specific hardware
307 instructions available in your processor. However, if
308 you want to control aspects of the build, there are plenty of things you
311 The best way to use \cmake{} to configure \gromacs{} is to do an
312 ``out-of-source'' build, by making another directory from which you
313 will run \cmake{}. This can be a subdirectory or not, it doesn't
314 matter. It also means you can never corrupt your source code by trying
315 to build it! So, the only required argument on the \cmake{} command
316 line is the name of the directory containing the
317 \verb+CMakeLists.txt+ file of the code you want to build. For
318 example, download the source tarball and use
319 % TODO: keep up to date with new releases!
321 $ tar xfz gromacs-4.6.1.tgz
328 You will see \verb+cmake+ report the results of a large number of
329 tests on your system made by \cmake{} and by \gromacs{}. These are
330 written to the \cmake{} cache, kept in \verb+CMakeCache.txt+. You
331 can edit this file by hand, but this is not recommended because it is
332 easy to reach an inconsistent state. You should not attempt to move or
333 copy this file to do another build, because file paths are hard-coded
334 within it. If you mess things up, just delete this file and start
335 again with '\verb+cmake+'.
337 If there's 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're
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 \verb+cmake+ through \verb+less+ or \verb+tee+ can be
346 \cmake{} works in an iterative fashion, re-running each time a setting
347 is changed to try to make sure other things are consistent. Once
348 things seem consistent, the iterations stop. Once \verb+cmake+
349 returns, you can see all the settings that were chosen and information
350 about them by using e.g. the curses interface
354 You can actually use \verb+ccmake+ directly in the first step, but then
355 most of the status messages will merely blink in the lower part
356 of the terminal rather than be written to standard out. Some platforms
357 like Windows or Mac even have native graphical user interfaces for
358 \cmake{}, and it can create project files for almost any build environment
359 you want (including Visual Studio or Xcode).
360 Check out \url{http://www.cmake.org/cmake/help/runningcmake.html} for
361 general advice on what you are seeing and how to navigate and change
362 things. The settings you might normally want to change are already
363 presented. If you make any changes, then \verb+ccmake+ will notice
364 that and require that you re-configure (using '\verb+c+'), so that it
365 gets a chance to make changes that depend on yours and perform more
366 checking. This might require several configuration stages when you are
367 using \verb+ccmake+ - when you are using \verb+cmake+ the
368 iteration is done behind the scenes.
370 A key thing to consider here is the setting of
371 \verb+CMAKE_INSTALL_PREFIX+. You will need to be able to write to
372 this directory in order to install \gromacs{} later, and if you change
373 your mind later, changing it in the cache triggers a full re-build,
374 unfortunately. So if you do not have super-user privileges on your
375 machine, then you will need to choose a sensible location within your
376 home directory for your \gromacs{} installation.
378 When \verb+cmake+ or \verb+ccmake+ have completed iterating, the
379 cache is stable and a build tree can be generated, with '\verb+g+' in
380 \verb+ccmake+ or automatically with \verb+cmake+.
382 You should not attempt to change compilers after the initial run of
383 \cmake{}. If you need to change, clean up and start again.
385 \subsection{Using CMake command-line options}
386 Once you become comfortable with setting and changing options, you
387 may know in advance how you will configure GROMACS. If so, you can
388 speed things up by invoking \verb+cmake+ with a command like:
390 $ cmake .. -DGMX_GPU=ON -DGMX_MPI=ON -DCMAKE_INSTALL_PREFIX=/home/marydoe/programs
392 to build with GPUs, MPI and install in a custom location. You can even
393 save that in a shell script to make it even easier next time. You can
394 also do this kind of thing with \verb+ccmake+, but you should avoid
395 this, because the options set with '\verb+-D+' will not be able to be
396 changed interactively in that run of \verb+ccmake+.
398 \subsection{CMake advanced options}
399 The options that can be seen with \verb+ccmake+ are ones that we
400 think a reasonable number of users might want to consider
401 changing. There are a lot more options available, which you can see by
402 toggling the advanced mode in \verb+ccmake+ on and off with
403 '\verb+t+'. Even there, most of the variables that you might want to
404 change have a '\verb+CMAKE_+' or '\verb+GMX_+' prefix.
406 \subsection{Helping CMake find the right libraries/headers/programs}
408 If libraries are installed in non-default locations their location can
409 be specified using the following environment variables:
411 \item \verb+CMAKE_INCLUDE_PATH+ for header files
412 \item \verb+CMAKE_LIBRARY_PATH+ for libraries
413 \item \verb+CMAKE_PREFIX_PATH+ for header, libraries and binaries
414 (e.g. '\verb+/usr/local+').
416 The respective '\verb+include+', '\verb+lib+', or '\verb+bin+' is
417 appended to the path. For each of these variables, a list of paths can
418 be specified (on Unix seperated with ":"). Note that these are
419 enviroment variables (and not \cmake{} command-line arguments) and in
420 a '\verb+bash+' shell are used like:
422 $ CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
425 The \verb+CC+ and \verb+CXX+ environment variables are also useful
426 for indicating to \cmake{} which compilers to use, which can be very
427 important for maximising \gromacs{} performance. Similarly,
428 \verb+CFLAGS+/\verb+CXXFLAGS+ can be used to pass compiler
429 options, but note that these will be appended to those set by
430 \gromacs{} for your build platform and build type. You can customize
431 some of this with advanced options such as \verb+CMAKE_C_FLAGS+
434 See also: \url{http://cmake.org/Wiki/CMake_Useful_Variables#Environment_Variables}
436 \subsection{Linear algebra libraries}\hypertarget{linear-algebra}
437 As mentioned above, sometimes vendor \blas{} and \lapack{} libraries
438 can provide performance enhancements for \gromacs{} when doing
439 normal-mode analysis or covariance analysis. For simplicity, the text
440 below will refer only to \blas{}, but the same options are available
441 for \lapack{}. By default, the \cmake{} optionv
442 \verb+GMX_EXTERNAL_BLAS+ is on, which triggers \cmake{} to search for
443 \blas{}. If one is found, then it is used. Otherwise, \cmake{} falls
444 back on internal versions provided in the \gromacs{} source. These are
445 fine for normal use. If you need to specify a non-standard path to
446 search, use \verb+-DCMAKE_PREFIX_PATH=/path/to/search+.
448 If you are using Intel's \mkl{} for \fft{}, then the \blas{} and
449 \lapack{} it provides are used automatically.
451 On Apple platforms where the Accelerate Framework is available, these
452 will be automatically used for \blas{} and \lapack{}.
454 \subsection{Native GPU acceleration}
455 If you have the \cuda{} Software Development Kit installed, you can
458 cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
460 (or whichever path has your installation). Note that this will require
461 a working C++ compiler, and in some cases you might need to handle
462 this manually, e.g. with the advanced option
463 \verb+CUDA_HOST_COMPILER+.
465 Historically, Linux GPU builds have received most testing, but we
466 want to support GPU builds both under x86 Linux, Windows, Mac OS X and in the
467 future ARM. Any feedback on this build process (and fixes in particular) are very
470 \subsection{Static linking}
471 Dynamic linking of the \gromacs{} executables will lead to a
472 smaller disk footprint when installed, and so is the default on
473 platforms where we believe it has been tested repeatedly and found to work.
474 In general, this includes Linux, Windows, Mac OS X and BSD systems.
475 Static binaries take much more space, but on some hardware and/or under
476 some conditions they are necessary, most commonly when you are running a parallel
477 simulation using MPI libraries.
480 \item To link \gromacs{} binaries
481 statically against the internal \gromacs{} libraries, set
482 \verb+BUILD_SHARED_LIBS=OFF+.
483 \item To link statically against external
484 libraries as well, the \verb+GMX_PREFER_STATIC_LIBS=ON+ option can be
485 used. Note, that in general \cmake{} picks up whatever is available,
486 so this option only instructs \cmake{} to prefer static libraries when
487 both static and shared are available. If no static version of an
488 external library is available, even when the aforementioned option is
489 ON, the shared library will be used. Also note, that the resulting
490 binaries will still be dynamically linked against system libraries if
491 that is all that is available (common on Mac OS X).
494 \subsection{Changing the names of GROMACS binaries and libraries}
495 It is sometimes convenient to have different versions of the same
496 \gromacs{} libraries installed. The most common use cases have been
497 single and double precision, and with and without \mpi{}. By default,
498 \gromacs{} will suffix binaries and libraries for such builds with
499 '\verb+_d+' for double precision and/or '\verb+_mpi+' for \mpi{} (and
500 nothing otherwise). This can be controlled manually with
501 \verb+GMX_DEFAULT_SUFFIX (ON/OFF)+, \verb+GMX_BINARY_SUFFIX+ (takes
502 a string) and \verb+GMX_LIBS_SUFFIX+ (also takes a string).
503 This can also be useful for resolving libary-naming conflicts with
504 existing packges (\verb+GMX_PREFIX_LIBMD+ also can be useful).
505 For instance, to set a custom suffix for binaries and libraries,
509 cmake .. -DGMX_DEFAULT_SUFFIX=OFF -DGMX_BINARY_SUFFIX=_mod -DGMX_LIBS_SUFFIX=_mod
512 Thus the names of all binaries and libraries will be appended with
515 \subsection{Building \gromacs{}}
517 Once you have a stable cache, you can build \gromacs{}. If you're not
518 sure the cache is stable, you can re-run \verb+cmake ..+ or
519 \verb+ccmake ..+' to see. Then you can run \verb+make+ to start the
520 compilation. Before actual compilation starts, \verb+make+ checks
521 that the cache is stable, so if it isn't you will see \cmake{} run
524 So long as any changes you've made to the configuration are sensible,
525 it is expected that the \verb+make+ procedure will always complete
526 successfully. The tests \gromacs{} makes on the settings you choose
527 are pretty extensive, but there are probably a few cases we haven't
528 thought of yet. Search the web first for solutions to problems, but if
529 you need help, ask on gmx-users, being sure to provide as much
530 information as possible about what you did, the system you are
531 building on, and what went wrong.
533 If you have a multi-core or multi-CPU machine with \verb+N+
534 processors, then using
538 will generally speed things up by quite a bit.
540 \subsection{Installing \gromacs{}}
542 Finally, \verb+make install+ will install \gromacs{} in the
543 directory given in \verb+GMX_INSTALL_PREFIX+. If this is an system
544 directory, then you will need permission to write there, and you
545 should use super-user privileges only for \verb+make install+ and
546 not the whole procedure.
548 \subsection{Getting access to \gromacs{} after installation}
550 \gromacs{} installs the script \verb+GMXRC+ in the \verb+bin+
551 subdirectory of the installation directory
552 (e.g. \verb+/usr/local/gromacs/bin/GMXRC+), which you should source
555 $ source your-installation-prefix-here/bin/GMXRC
558 It will detect what kind of shell you are running and set up your
559 environment for using \gromacs{}. You may wish to arrange for your
560 login scripts to do this automatically; please search the web for
561 instructions on how to do this for your shell.
563 Many of the \gromacs{} programs rely on data installed in our
564 \verb+share/gromacs+ directory. By default, the programs will use
565 the environment variables set in the GMXRC script, and if this is not
566 available they will try to guess the path based on their own location.
567 This usually works well unless you change the names of directories
568 inside the install tree. If you still need to do that, you might want to recompile
569 with the new install location properly set, or edit the \verb+GMXRC+ script.
571 \subsection{Testing \gromacs{} for correctness}
572 Since 2011, the \gromacs{} development uses an automated system where
573 every new patch is subject to regression testing. While this improves
574 reliability quite a lot, not everything is tested, and since we
575 increasingly rely on cutting edge compiler features there is
576 non-negligible risk that the default compiler on your system could
577 have bugs. We have tried our best to test and refuse to use known bad
578 versions in \cmake{}, but we strongly recommend that you run through
579 the regression tests yourself. It only takes a few minutes, after
580 which you can trust your build.
582 The simplest way to run the checks is to build \gromacs{} with
583 \verb+-DREGRESSIONTEST_DOWNLOAD+, and run \verb+make check+.
584 \gromacs{} will automatically download and run the tests for you.
585 Alternatively, you can download and unpack the tarball yourself from
586 \url{http://gerrit.gromacs.org/download/regressiontests-4.6.1.tar.gz},
587 and use the advanced \cmake{} option \verb+REGRESSIONTEST_PATH+ to
588 specify the path to the unpacked tarball, which will then be used for
589 testing. If this doesn't work, then please read on.
591 The regression tests are available from the \gromacs{} website and ftp
592 site. Once you have downloaded them, unpack the tarball, source
593 \verb+GMXRC+ as described above, and run \verb+./gmxtest.pl all+
594 inside the regression tests folder. You can find more options
595 (e.g. adding \verb+double+ when using double precision) if you just
596 execute the script without options.
598 Hopefully you will get a report that all tests have passed. If there
599 are individual failed tests it could be a sign of a compiler bug, or
600 that a tolerance is just a tiny bit too tight. Check the output files
601 the script directs you too, and try a different or newer compiler if
602 the errors appear to be real. If you cannot get it to pass the
603 regression tests, you might try dropping a line to the gmx-users
604 mailing list, but then you should include a detailed description of
605 your hardware and an example logfile from mdrun (which contains
606 valuable information in the header).
608 \subsection{Testing \gromacs{} for performance}
609 We are still working on a set of benchmark systems for testing
610 the performance of \gromacs{}. Until that is ready, we recommend that
611 you start by comparing the performance to release 4.5, and also try
612 a few different parallelization options.
614 \subsection{Having difficulty?}
615 You're not alone - this can be a complex task! If you encounter a
616 problem with installing \gromacs{}, then there are a number of
617 locations where you can find assistance. It is recommended that you
618 follow these steps to find the solution:
621 \item Read the installation instructions again, taking note that you
622 have followed each and every step correctly.
623 \item Search the \gromacs{} website and users emailing list for
624 information on the error.
625 \item Search the internet using a search engine such as Google.
626 \item Post to the \gromacs{} users emailing list gmx-users for
627 assistance. Be sure to give a full description of what you have done
628 and why you think it didn't work. Give details about the system on
629 which you are installing.
630 Copy and paste your command line and as
631 much of the output as you think might be relevant - certainly from
632 the first indication of a problem. In particular, please try to include at
633 least the header from the mdrun logfile, and preferably the entire file.
634 People who might volunteer to
635 help you do not have time to ask you interactive detailed follow-up
636 questions, so you will get an answer faster if you provide as much
637 information as you think could possibly help. High quality bug reports
638 tend to receive rapid high quality answers.
641 \section{Special instructions for some platforms}
643 \subsection{Building on Windows}
644 Building on Cygwin/MinGW/etc. works just like Unix. Please see the
647 Building on Windows using native compilers is rather similar to
648 building on Unix, so please start by reading the above. Then, download
649 and unpack the GROMACS source archive. The UNIX-standard .tar.gz
650 format can be managed on Windows, but you may prefer to browse
651 \url{ftp://ftp.gromacs.org/pub/gromacs} to obtain a zip format file,
652 which doesn't need any external tools to unzip on recent Windows
653 systems. Make a folder in which to do the out-of-source build of
654 \gromacs{}. For example, make it within the folder unpacked from the
655 source archive, and call it ``build-cmake''.
657 For \cmake{}, you can either use the graphical user interface provided
658 on Windows, or you can use a command line shell with instructions
659 similar to the UNIX ones above. If you open a shell from within
660 your IDE (e.g. Microsoft Visual Studio), it will configure the
661 environment for you, but you might need to tweak this in order to
662 get either a 32-bit or 64-bit build environment. The latter provides the
663 fastest executable. If you use a normal Windows command shell, then
664 you will need to either set up the environment to find your compilers
665 and libraries yourself, or run the \verb+vcvarsall.bat+ batch script
666 provided by MSVC (just like sourcing a bash script under
669 With the graphical user interface you will be asked about what compilers
670 to use at the initial configuration stage, and if you use the command line
671 they can be set in a similar way as under UNIX.
672 You will probably make your life easier and faster by using the
673 new facility to download and install \fftw{} automatically.
675 For the build, you can either load the generated solutions file into
676 e.g. Visual Studio, or use the command line with \verb+cmake --build .+
677 so the right tools get used.
679 \subsection{Building on Cray}
681 Gromacs builds mostly out of the box on modern Cray machines,
682 but you want to use static libraries due to the peculiarities with
683 parallel job execution.
685 \subsection{Building on BlueGene}
687 \subsubsection{BlueGene/P}
689 There is currently no native acceleration on this platform, but the
690 default plain C kernels will work.
692 \subsubsection{BlueGene/Q}
694 There is currently no native acceleration on this platform, but the
695 default plain C kernels will work. We have accelerated kernels in
696 progress for this platform, but they are not quite done yet.
698 Only static linking with XL compilers is supported by \gromacs{}. Dynamic
699 linking would be supported by the architecture and \gromacs{}, but has no
700 advantages other than disk space, and is generally discouraged on
701 BlueGene for performance reasons.
703 Computation on BlueGene floating-point units is always done in
704 double-precision. However, single-precision builds of \gromacs{} are
705 still normal and encouraged since they use cache more efficiently.
706 The BlueGene hardware automatically
707 converts values stored in single precision in memory to double
708 precision in registers for computation, converts the results back to
709 single precision correctly, and does so for no additional cost. As
710 with other platforms, doing the whole computation in double precision
711 normally shows no improvement in accuracy and costs twice as much time
712 moving memory around.
714 You need to arrange for FFTW to be installed correctly, following the
717 mpicc is used for compiling and linking. This can make it awkward to
718 attempt to use IBM's optimized BLAS/LAPACK called ESSL. Since mdrun is
719 the only part of \gromacs{} that should normally run on the compute
720 nodes, and there is nearly no need for linear algebra support for
721 mdrun, it is recommended to use the \gromacs{} built-in linear algebra
722 routines - it is rare for this to be a bottleneck.
725 cmake .. -DCMAKE_TOOLCHAIN_FILE=BlueGeneQ-static-XL-C \
726 -DCMAKE_PREFIX_PATH=/your/fftw/installation/prefix
730 It is possible to configure and make the remaining \gromacs{} tools
731 with the compute node toolchain, but as none of those tools are
732 \mpi{}-aware, this would not normally be useful. Instead, these should
733 be planned to run on the login node, and a seperate \gromacs{}
734 installation performed for that using the login node's toolchain.
736 \subsubsection{Fujitsu PRIMEHPC}
738 This is the architecture of the K computer, which uses Fujitsu Sparc64viiifx
739 chips. Gromacs-4.6 will build with default C kernels on this architecture,
740 and Gromacs-4.6.2 will add accelerated kernels and a custom toolchain.
742 \section{Tested platforms}
744 While it is our best belief that \gromacs{} will build and run pretty
745 much everywhere, it's important that we tell you where we really know
746 it works because we've tested it. We do test on Linux, Windows, and
747 Mac with a range of compilers and libraries for a range of our
748 configuration options. Every commit in our git source code
749 repository is currently tested on x86 with gcc versions ranging
750 from 4.4 through 4.7, and versions 12 and 13 of the Intel compiler.
751 Under Windows we test both the visual studio compilers and icc,
753 We test irregularly on BlueGene/L, BlueGene/P, BlueGene/Q, Cray,
754 Fujitsu PRIMEHPC, Google nativeclient and other environments. In
755 the future we expect ARM to be an important test target too, but this
756 is currently not included.
758 Contributions to this section are welcome.
760 Later we might set up the ability for users to contribute test results
763 \section{Other issues}
765 The \gromacs{} utility programs often write data files in formats
766 suitable for the \grace{} plotting tool, but it is straightforward to
767 use these files in other plotting programs, too.