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, CMake will search for \blas{}, use it if it
430 is found, and otherwise fall back on a version of \blas{} internal to
431 \gromacs{}. The \cmake{} option \verb+GMX_EXTERNAL_BLAS+ will be set
432 accordingly. The internal versions are fine for normal use. If you
433 need to specify a non-standard path to search, use
434 \verb+-DCMAKE_PREFIX_PATH=/path/to/search+. If you need to specify a
435 library with a non-standard name (e.g. ESSL on AIX), then set
436 \verb+-DGMX_BLAS_USER=/path/to/reach/lib/libwhatever.a+.
438 If you are using Intel's \mkl{} for \fft{}, then the \blas{} and
439 \lapack{} it provides are used automatically. This could be
440 over-ridden with \verb+GMX_BLAS_USER+, etc.
442 On Apple platforms where the Accelerate Framework is available, these
443 will be automatically used for \blas{} and \lapack{}. This could be
444 over-ridden with \verb+GMX_BLAS_USER+, etc.
446 \subsection{Native GPU acceleration}
447 If you have the \cuda{} Software Development Kit installed, you can
450 cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
452 (or whichever path has your installation). Note that this will require
453 a working C++ compiler, and in some cases you might need to handle
454 this manually, e.g. with the advanced option
455 \verb+CUDA_HOST_COMPILER+.
457 Historically, Linux GPU builds have received most testing, but we
458 want to support GPU builds both under x86 Linux, Windows, Mac OS X and in the
459 future ARM. Any feedback on this build process (and fixes in particular) are very
462 \subsection{Static linking}
463 Dynamic linking of the \gromacs{} executables will lead to a
464 smaller disk footprint when installed, and so is the default on
465 platforms where we believe it has been tested repeatedly and found to work.
466 In general, this includes Linux, Windows, Mac OS X and BSD systems.
467 Static binaries take much more space, but on some hardware and/or under
468 some conditions they are necessary, most commonly when you are running a parallel
469 simulation using MPI libraries.
472 \item To link \gromacs{} binaries
473 statically against the internal \gromacs{} libraries, set
474 \verb+BUILD_SHARED_LIBS=OFF+.
475 \item To link statically against external
476 libraries as well, the \verb+GMX_PREFER_STATIC_LIBS=ON+ option can be
477 used. Note, that in general \cmake{} picks up whatever is available,
478 so this option only instructs \cmake{} to prefer static libraries when
479 both static and shared are available. If no static version of an
480 external library is available, even when the aforementioned option is
481 ON, the shared library will be used. Also note, that the resulting
482 binaries will still be dynamically linked against system libraries if
483 that is all that is available (common on Mac OS X).
486 \subsection{Changing the names of GROMACS binaries and libraries}
487 It is sometimes convenient to have different versions of the same
488 \gromacs{} libraries installed. The most common use cases have been
489 single and double precision, and with and without \mpi{}. By default,
490 \gromacs{} will suffix binaries and libraries for such builds with
491 '\verb+_d+' for double precision and/or '\verb+_mpi+' for \mpi{} (and
492 nothing otherwise). This can be controlled manually with
493 \verb+GMX_DEFAULT_SUFFIX (ON/OFF)+, \verb+GMX_BINARY_SUFFIX+ (takes
494 a string) and \verb+GMX_LIBS_SUFFIX+ (also takes a string).
495 This can also be useful for resolving libary-naming conflicts with
496 existing packges (\verb+GMX_PREFIX_LIBMD+ also can be useful).
497 For instance, to set a custom suffix for binaries and libraries,
501 cmake .. -DGMX_DEFAULT_SUFFIX=OFF -DGMX_BINARY_SUFFIX=_mod -DGMX_LIBS_SUFFIX=_mod
504 Thus the names of all binaries and libraries will be appended with
507 \subsection{Building \gromacs{}}
509 Once you have a stable cache, you can build \gromacs{}. If you're not
510 sure the cache is stable, you can re-run \verb+cmake ..+ or
511 \verb+ccmake ..+' to see. Then you can run \verb+make+ to start the
512 compilation. Before actual compilation starts, \verb+make+ checks
513 that the cache is stable, so if it isn't you will see \cmake{} run
516 So long as any changes you've made to the configuration are sensible,
517 it is expected that the \verb+make+ procedure will always complete
518 successfully. The tests \gromacs{} makes on the settings you choose
519 are pretty extensive, but there are probably a few cases we haven't
520 thought of yet. Search the web first for solutions to problems, but if
521 you need help, ask on gmx-users, being sure to provide as much
522 information as possible about what you did, the system you are
523 building on, and what went wrong.
525 If you have a multi-core or multi-CPU machine with \verb+N+
526 processors, then using
530 will generally speed things up by quite a bit.
532 \subsection{Installing \gromacs{}}
534 Finally, \verb+make install+ will install \gromacs{} in the
535 directory given in \verb+GMX_INSTALL_PREFIX+. If this is an system
536 directory, then you will need permission to write there, and you
537 should use super-user privileges only for \verb+make install+ and
538 not the whole procedure.
540 \subsection{Getting access to \gromacs{} after installation}
542 \gromacs{} installs the script \verb+GMXRC+ in the \verb+bin+
543 subdirectory of the installation directory
544 (e.g. \verb+/usr/local/gromacs/bin/GMXRC+), which you should source
547 $ source your-installation-prefix-here/bin/GMXRC
550 It will detect what kind of shell you are running and set up your
551 environment for using \gromacs{}. You may wish to arrange for your
552 login scripts to do this automatically; please search the web for
553 instructions on how to do this for your shell.
555 Many of the \gromacs{} programs rely on data installed in our
556 \verb+share/gromacs+ directory. By default, the programs will use
557 the environment variables set in the GMXRC script, and if this is not
558 available they will try to guess the path based on their own location.
559 This usually works well unless you change the names of directories
560 inside the install tree. If you still need to do that, you might want to recompile
561 with the new install location properly set, or edit the \verb+GMXRC+ script.
563 \subsection{Testing \gromacs{} for correctness}
564 Since 2011, the \gromacs{} development uses an automated system where
565 every new patch is subject to regression testing. While this improves
566 reliability quite a lot, not everything is tested, and since we
567 increasingly rely on cutting edge compiler features there is
568 non-negligible risk that the default compiler on your system could
569 have bugs. We have tried our best to test and refuse to use known bad
570 versions in \cmake{}, but we strongly recommend that you run through
571 the regression tests yourself. It only takes a few minutes, after
572 which you can trust your build.
574 The simplest way to run the checks is to build \gromacs{} with
575 \verb+-DREGRESSIONTEST_DOWNLOAD+, and run \verb+make check+.
576 \gromacs{} will automatically download and run the tests for you.
577 Alternatively, you can download and unpack the tarball yourself from
578 \url{http://gerrit.gromacs.org/download/regressiontests-4.6.1.tar.gz},
579 and use the advanced \cmake{} option \verb+REGRESSIONTEST_PATH+ to
580 specify the path to the unpacked tarball, which will then be used for
581 testing. If this doesn't work, then please read on.
583 The regression tests are available from the \gromacs{} website and ftp
584 site. Once you have downloaded them, unpack the tarball, source
585 \verb+GMXRC+ as described above, and run \verb+./gmxtest.pl all+
586 inside the regression tests folder. You can find more options
587 (e.g. adding \verb+double+ when using double precision) if you just
588 execute the script without options.
590 Hopefully you will get a report that all tests have passed. If there
591 are individual failed tests it could be a sign of a compiler bug, or
592 that a tolerance is just a tiny bit too tight. Check the output files
593 the script directs you too, and try a different or newer compiler if
594 the errors appear to be real. If you cannot get it to pass the
595 regression tests, you might try dropping a line to the gmx-users
596 mailing list, but then you should include a detailed description of
597 your hardware and an example logfile from mdrun (which contains
598 valuable information in the header).
600 \subsection{Testing \gromacs{} for performance}
601 We are still working on a set of benchmark systems for testing
602 the performance of \gromacs{}. Until that is ready, we recommend that
603 you start by comparing the performance to release 4.5, and also try
604 a few different parallelization options.
606 \subsection{Having difficulty?}
607 You're not alone - this can be a complex task! If you encounter a
608 problem with installing \gromacs{}, then there are a number of
609 locations where you can find assistance. It is recommended that you
610 follow these steps to find the solution:
613 \item Read the installation instructions again, taking note that you
614 have followed each and every step correctly.
615 \item Search the \gromacs{} website and users emailing list for
616 information on the error.
617 \item Search the internet using a search engine such as Google.
618 \item Post to the \gromacs{} users emailing list gmx-users for
619 assistance. Be sure to give a full description of what you have done
620 and why you think it didn't work. Give details about the system on
621 which you are installing.
622 Copy and paste your command line and as
623 much of the output as you think might be relevant - certainly from
624 the first indication of a problem. In particular, please try to include at
625 least the header from the mdrun logfile, and preferably the entire file.
626 People who might volunteer to
627 help you do not have time to ask you interactive detailed follow-up
628 questions, so you will get an answer faster if you provide as much
629 information as you think could possibly help. High quality bug reports
630 tend to receive rapid high quality answers.
633 \section{Special instructions for some platforms}
635 \subsection{Building on Windows}
636 Building on Cygwin/MinGW/etc. works just like Unix. Please see the
639 Building on Windows using native compilers is rather similar to
640 building on Unix, so please start by reading the above. Then, download
641 and unpack the GROMACS source archive. The UNIX-standard .tar.gz
642 format can be managed on Windows, but you may prefer to browse
643 \url{ftp://ftp.gromacs.org/pub/gromacs} to obtain a zip format file,
644 which doesn't need any external tools to unzip on recent Windows
645 systems. Make a folder in which to do the out-of-source build of
646 \gromacs{}. For example, make it within the folder unpacked from the
647 source archive, and call it ``build-cmake''.
649 For \cmake{}, you can either use the graphical user interface provided
650 on Windows, or you can use a command line shell with instructions
651 similar to the UNIX ones above. If you open a shell from within
652 your IDE (e.g. Microsoft Visual Studio), it will configure the
653 environment for you, but you might need to tweak this in order to
654 get either a 32-bit or 64-bit build environment. The latter provides the
655 fastest executable. If you use a normal Windows command shell, then
656 you will need to either set up the environment to find your compilers
657 and libraries yourself, or run the \verb+vcvarsall.bat+ batch script
658 provided by MSVC (just like sourcing a bash script under
661 With the graphical user interface you will be asked about what compilers
662 to use at the initial configuration stage, and if you use the command line
663 they can be set in a similar way as under UNIX.
664 You will probably make your life easier and faster by using the
665 new facility to download and install \fftw{} automatically.
667 For the build, you can either load the generated solutions file into
668 e.g. Visual Studio, or use the command line with \verb+cmake --build .+
669 so the right tools get used.
671 \subsection{Building on Cray}
673 Gromacs builds mostly out of the box on modern Cray machines,
674 but you want to use static libraries due to the peculiarities with
675 parallel job execution.
677 \subsection{Building on BlueGene}
679 \subsubsection{BlueGene/P}
681 There is currently no native acceleration on this platform, but the
682 default plain C kernels will work.
684 \subsubsection{BlueGene/Q}
686 There is currently no native acceleration on this platform, but the
687 default plain C kernels will work. We have accelerated kernels in
688 progress for this platform, but they are not quite done yet.
690 Only static linking with XL compilers is supported by \gromacs{}. Dynamic
691 linking would be supported by the architecture and \gromacs{}, but has no
692 advantages other than disk space, and is generally discouraged on
693 BlueGene for performance reasons.
695 Computation on BlueGene floating-point units is always done in
696 double-precision. However, single-precision builds of \gromacs{} are
697 still normal and encouraged since they use cache more efficiently.
698 The BlueGene hardware automatically
699 converts values stored in single precision in memory to double
700 precision in registers for computation, converts the results back to
701 single precision correctly, and does so for no additional cost. As
702 with other platforms, doing the whole computation in double precision
703 normally shows no improvement in accuracy and costs twice as much time
704 moving memory around.
706 You need to arrange for FFTW to be installed correctly, following the
709 mpicc is used for compiling and linking. This can make it awkward to
710 attempt to use IBM's optimized BLAS/LAPACK called ESSL. Since mdrun is
711 the only part of \gromacs{} that should normally run on the compute
712 nodes, and there is nearly no need for linear algebra support for
713 mdrun, it is recommended to use the \gromacs{} built-in linear algebra
714 routines - it is rare for this to be a bottleneck.
717 cmake .. -DCMAKE_TOOLCHAIN_FILE=BlueGeneQ-static-XL-C \
718 -DCMAKE_PREFIX_PATH=/your/fftw/installation/prefix \
719 -DGMX_BUILD_MDRUN_ONLY=ON
723 It is possible to configure and make the remaining \gromacs{} tools
724 with the compute node toolchain, but as none of those tools are
725 \mpi{}-aware, this would not normally be useful. Instead, these should
726 be planned to run on the login node, and a seperate \gromacs{}
727 installation performed for that using the login node's toolchain.
729 \subsubsection{Fujitsu PRIMEHPC}
731 This is the architecture of the K computer, which uses Fujitsu Sparc64viiifx
732 chips. Gromacs-4.6 will build with default C kernels on this architecture,
733 and Gromacs-4.6.2 will add accelerated kernels and a custom toolchain.
735 \section{Tested platforms}
737 While it is our best belief that \gromacs{} will build and run pretty
738 much everywhere, it's important that we tell you where we really know
739 it works because we've tested it. We do test on Linux, Windows, and
740 Mac with a range of compilers and libraries for a range of our
741 configuration options. Every commit in our git source code
742 repository is currently tested on x86 with gcc versions ranging
743 from 4.4 through 4.7, and versions 12 and 13 of the Intel compiler.
744 Under Windows we test both the visual studio compilers and icc,
746 We test irregularly on BlueGene/L, BlueGene/P, BlueGene/Q, Cray,
747 Fujitsu PRIMEHPC, Google nativeclient and other environments. In
748 the future we expect ARM to be an important test target too, but this
749 is currently not included.
751 Contributions to this section are welcome.
753 Later we might set up the ability for users to contribute test results
756 \section{Other issues}
758 The \gromacs{} utility programs often write data files in formats
759 suitable for the \grace{} plotting tool, but it is straightforward to
760 use these files in other plotting programs, too.