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