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.4.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.
228 Note that the GROMACS-managed download of the FFTW tarball has a
229 slight chance of posing a security risk. If you use this option, you
230 will see a warning that advises how you can eliminate this risk.
233 If you build \fftw{} from source yourself, get the most recent version
234 and follow its installation guide available from \url{http://www.fftw.org}.
235 Choose the precision (i.e. single or float vs.\ double) to match what you will
236 later require for \gromacs{}. There is no need to compile with
237 threading or \mpi{} support, but it does no harm. On x86 hardware,
238 compile \emph{only} with \verb+--enable-sse2+ (regardless of
239 precision) even if your processors can take advantage of \avx{}
240 extensions. Since \gromacs{} uses fairly short transform lengths we
241 do not benefit from the \fftw{} \avx{} acceleration, and because of
242 memory system performance limitations, it can even degrade \gromacs{}
243 performance by around 20\%. There is no way for \gromacs{} to
244 limit the use to \ssetwo{} acceleration at run time if \avx{}
245 support has been compiled into \fftw{}, so you need to set this at compile time.
247 \subsubsection{\mkl{}}
249 Using \mkl{} with icc 11 or higher is very simple. Set up your
250 compiler environment correctly, perhaps with a command like
251 \verb+source /path/to/compilervars.sh intel64+ (or consult your local
252 documentation). Then set \verb+-DGMX_FFT_LIBRARY=mkl+ when you run
253 \cmake{}. In this case, \gromacs{} will also use \mkl{} for \blas{}
254 and \lapack{} (see \hyperref{linear-algebra}{here}).
256 Otherwise, you can configure \mkl{} by setting
257 \verb+-DGMX_FFT_LIBRARY=mkl
258 -DMKL_LIBRARIES="/full/path/to/libone.so;/full/path/to/libtwo.so"
259 -DMKL_INCLUDE_DIR="/full/path/to/mkl/include"+,
260 where the full list (and order!) of libraries you require are found in
261 Intel's \mkl{} documentation for your system.
263 \subsection{Optional build components}
266 \item Hardware-optimized \blas{} and \lapack{} libraries are useful
267 for a few of the \gromacs{} utilities focused on normal modes and
268 matrix manipulation, but they do not provide any benefits for normal
269 simulations. Configuring these are discussed
270 \hyperlink{linear-algebra}{here}.
271 \item The built-in \gromacs{} trajectory viewer \verb+ngmx+ requires
272 X11 and Motif/Lesstif libraries and header files. Generally, the
273 \gromacs{} team rather recommends you use third-party software for
274 visualization, such as \vmd{}
275 \url{http://www.ks.uiuc.edu/Research/vmd/} or \pymol{}
276 \url{http://www.pymol.org/}.
277 \item A few \gromacs{} tools get some extra functionality when linked with the
278 GNU scientific library GSL.
281 \section{Doing a build of \gromacs}
283 This section will cover a general build of \gromacs{} with \cmake{},
284 but it is not an exhaustive discussion of how to use \cmake{}. There
285 are many resources available on the web, which we suggest you search
286 for when you encounter problems not covered here. The material below
287 applies specifically to builds on Unix-like systems, including Linux,
288 Mac OS X, MinGW and Cygwin. For other platforms, see the specialist
291 \subsection{Configuring with \cmake{}}
293 \cmake{} will run many tests on your system and do its best to work
294 out how to build \gromacs{} for you. If you are building \gromacs{} on
295 hardware that is identical to that where you will run \verb+mdrun+,
296 then you can be sure that the defaults will be pretty good. The build
297 configuration will for instance attempt to detect the specific hardware
298 instructions available in your processor. However, if
299 you want to control aspects of the build, there are plenty of things you
302 The best way to use \cmake{} to configure \gromacs{} is to do an
303 ``out-of-source'' build, by making another directory from which you
304 will run \cmake{}. This can be a subdirectory or not, it doesn't
305 matter. It also means you can never corrupt your source code by trying
306 to build it! So, the only required argument on the \cmake{} command
307 line is the name of the directory containing the
308 \verb+CMakeLists.txt+ file of the code you want to build. For
309 example, download the source tarball and use
310 % TODO: keep up to date with new releases!
312 $ tar xfz gromacs-4.6.4.tgz
319 You will see \verb+cmake+ report the results of a large number of
320 tests on your system made by \cmake{} and by \gromacs{}. These are
321 written to the \cmake{} cache, kept in \verb+CMakeCache.txt+. You
322 can edit this file by hand, but this is not recommended because it is
323 easy to reach an inconsistent state. You should not attempt to move or
324 copy this file to do another build, because file paths are hard-coded
325 within it. If you mess things up, just delete this file and start
326 again with '\verb+cmake+'.
328 If there's a serious problem detected at this stage, then you will see
329 a fatal error and some suggestions for how to overcome it. If you're
330 not sure how to deal with that, please start by searching on the web
331 (most computer problems already have known solutions!) and then
332 consult the gmx-users mailing list. There are also informational
333 warnings that you might like to take on board or not. Piping the
334 output of \verb+cmake+ through \verb+less+ or \verb+tee+ can be
337 \cmake{} works in an iterative fashion, re-running each time a setting
338 is changed to try to make sure other things are consistent. Once
339 things seem consistent, the iterations stop. Once \verb+cmake+
340 returns, you can see all the settings that were chosen and information
341 about them by using e.g. the curses interface
345 You can actually use \verb+ccmake+ directly in the first step, but then
346 most of the status messages will merely blink in the lower part
347 of the terminal rather than be written to standard out. Some platforms
348 like Windows or Mac even have native graphical user interfaces for
349 \cmake{}, and it can create project files for almost any build environment
350 you want (including Visual Studio or Xcode).
351 Check out \url{http://www.cmake.org/cmake/help/runningcmake.html} for
352 general advice on what you are seeing and how to navigate and change
353 things. The settings you might normally want to change are already
354 presented. If you make any changes, then \verb+ccmake+ will notice
355 that and require that you re-configure (using '\verb+c+'), so that it
356 gets a chance to make changes that depend on yours and perform more
357 checking. This might require several configuration stages when you are
358 using \verb+ccmake+ - when you are using \verb+cmake+ the
359 iteration is done behind the scenes.
361 A key thing to consider here is the setting of
362 \verb+CMAKE_INSTALL_PREFIX+. You will need to be able to write to
363 this directory in order to install \gromacs{} later, and if you change
364 your mind later, changing it in the cache triggers a full re-build,
365 unfortunately. So if you do not have super-user privileges on your
366 machine, then you will need to choose a sensible location within your
367 home directory for your \gromacs{} installation.
369 When \verb+cmake+ or \verb+ccmake+ have completed iterating, the
370 cache is stable and a build tree can be generated, with '\verb+g+' in
371 \verb+ccmake+ or automatically with \verb+cmake+.
373 You should not attempt to change compilers after the initial run of
374 \cmake{}. If you need to change, clean up and start again.
376 \subsection{Using CMake command-line options}
377 Once you become comfortable with setting and changing options, you
378 may know in advance how you will configure GROMACS. If so, you can
379 speed things up by invoking \verb+cmake+ with a command like:
381 $ cmake .. -DGMX_GPU=ON -DGMX_MPI=ON -DCMAKE_INSTALL_PREFIX=/home/marydoe/programs
383 to build with GPUs, MPI and install in a custom location. You can even
384 save that in a shell script to make it even easier next time. You can
385 also do this kind of thing with \verb+ccmake+, but you should avoid
386 this, because the options set with '\verb+-D+' will not be able to be
387 changed interactively in that run of \verb+ccmake+.
389 \subsection{CMake advanced options}
390 The options that can be seen with \verb+ccmake+ are ones that we
391 think a reasonable number of users might want to consider
392 changing. There are a lot more options available, which you can see by
393 toggling the advanced mode in \verb+ccmake+ on and off with
394 '\verb+t+'. Even there, most of the variables that you might want to
395 change have a '\verb+CMAKE_+' or '\verb+GMX_+' prefix.
397 \subsection{Helping CMake find the right libraries/headers/programs}
399 If libraries are installed in non-default locations their location can
400 be specified using the following environment variables:
402 \item \verb+CMAKE_INCLUDE_PATH+ for header files
403 \item \verb+CMAKE_LIBRARY_PATH+ for libraries
404 \item \verb+CMAKE_PREFIX_PATH+ for header, libraries and binaries
405 (e.g. '\verb+/usr/local+').
407 The respective '\verb+include+', '\verb+lib+', or '\verb+bin+' is
408 appended to the path. For each of these variables, a list of paths can
409 be specified (on Unix separated with ":"). Note that these are
410 enviroment variables (and not \cmake{} command-line arguments) and in
411 a '\verb+bash+' shell are used like:
413 $ CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
416 The \verb+CC+ and \verb+CXX+ environment variables are also useful
417 for indicating to \cmake{} which compilers to use, which can be very
418 important for maximising \gromacs{} performance. Similarly,
419 \verb+CFLAGS+/\verb+CXXFLAGS+ can be used to pass compiler
420 options, but note that these will be appended to those set by
421 \gromacs{} for your build platform and build type. You can customize
422 some of this with advanced options such as \verb+CMAKE_C_FLAGS+
425 See also: \url{http://cmake.org/Wiki/CMake_Useful_Variables#Environment_Variables}
427 \subsection{Linear algebra libraries}\hypertarget{linear-algebra}
428 As mentioned above, sometimes vendor \blas{} and \lapack{} libraries
429 can provide performance enhancements for \gromacs{} when doing
430 normal-mode analysis or covariance analysis. For simplicity, the text
431 below will refer only to \blas{}, but the same options are available
432 for \lapack{}. By default, CMake will search for \blas{}, use it if it
433 is found, and otherwise fall back on a version of \blas{} internal to
434 \gromacs{}. The \cmake{} option \verb+GMX_EXTERNAL_BLAS+ will be set
435 accordingly. The internal versions are fine for normal use. If you
436 need to specify a non-standard path to search, use
437 \verb+-DCMAKE_PREFIX_PATH=/path/to/search+. If you need to specify a
438 library with a non-standard name (e.g. ESSL on AIX or BlueGene), then
439 set \verb+-DGMX_BLAS_USER=/path/to/reach/lib/libwhatever.a+.
441 If you are using Intel's \mkl{} for \fft{}, then the \blas{} and
442 \lapack{} it provides are used automatically. This could be
443 over-ridden with \verb+GMX_BLAS_USER+, etc.
445 On Apple platforms where the Accelerate Framework is available, these
446 will be automatically used for \blas{} and \lapack{}. This could be
447 over-ridden with \verb+GMX_BLAS_USER+, etc.
449 \subsection{Native GPU acceleration}
450 If you have the \cuda{} Software Development Kit installed, you can
453 cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
455 (or whichever path has your installation). Note that this will require
456 a working C++ compiler, and in some cases you might need to handle
457 this manually, e.g. with the advanced option
458 \verb+CUDA_HOST_COMPILER+.
460 Historically, Linux GPU builds have received most testing, but we
461 want to support GPU builds both under x86 Linux, Windows, Mac OS X and in the
462 future ARM. Any feedback on this build process (and fixes in particular) are very
465 \subsection{Static linking}
466 Dynamic linking of the \gromacs{} executables will lead to a
467 smaller disk footprint when installed, and so is the default on
468 platforms where we believe it has been tested repeatedly and found to work.
469 In general, this includes Linux, Windows, Mac OS X and BSD systems.
470 Static binaries take much more space, but on some hardware and/or under
471 some conditions they are necessary, most commonly when you are running a parallel
472 simulation using MPI libraries.
475 \item To link \gromacs{} binaries
476 statically against the internal \gromacs{} libraries, set
477 \verb+BUILD_SHARED_LIBS=OFF+.
478 \item To link statically against external
479 libraries as well, the \verb+GMX_PREFER_STATIC_LIBS=ON+ option can be
480 used. Note, that in general \cmake{} picks up whatever is available,
481 so this option only instructs \cmake{} to prefer static libraries when
482 both static and shared are available. If no static version of an
483 external library is available, even when the aforementioned option is
484 ON, the shared library will be used. Also note, that the resulting
485 binaries will still be dynamically linked against system libraries if
486 that is all that is available (common on Mac OS X).
489 \subsection{Changing the names of GROMACS binaries and libraries}
490 It is sometimes convenient to have different versions of the same
491 \gromacs{} libraries installed. The most common use cases have been
492 single and double precision, and with and without \mpi{}. By default,
493 \gromacs{} will suffix binaries and libraries for such builds with
494 '\verb+_d+' for double precision and/or '\verb+_mpi+' for \mpi{} (and
495 nothing otherwise). This can be controlled manually with
496 \verb+GMX_DEFAULT_SUFFIX (ON/OFF)+, \verb+GMX_BINARY_SUFFIX+ (takes
497 a string) and \verb+GMX_LIBS_SUFFIX+ (also takes a string).
498 This can also be useful for resolving libary-naming conflicts with
499 existing packges (\verb+GMX_PREFIX_LIBMD+ also can be useful).
500 For instance, to set a custom suffix for binaries and libraries,
504 cmake .. -DGMX_DEFAULT_SUFFIX=OFF -DGMX_BINARY_SUFFIX=_mod -DGMX_LIBS_SUFFIX=_mod
507 Thus the names of all binaries and libraries will be appended with
510 \subsection{Building \gromacs{}}
512 Once you have a stable cache, you can build \gromacs{}. If you're not
513 sure the cache is stable, you can re-run \verb+cmake ..+ or
514 \verb+ccmake ..+' to see. Then you can run \verb+make+ to start the
515 compilation. Before actual compilation starts, \verb+make+ checks
516 that the cache is stable, so if it isn't you will see \cmake{} run
519 So long as any changes you've made to the configuration are sensible,
520 it is expected that the \verb+make+ procedure will always complete
521 successfully. The tests \gromacs{} makes on the settings you choose
522 are pretty extensive, but there are probably a few cases we haven't
523 thought of yet. Search the web first for solutions to problems, but if
524 you need help, ask on gmx-users, being sure to provide as much
525 information as possible about what you did, the system you are
526 building on, and what went wrong.
528 If you have a multi-core or multi-CPU machine with \verb+N+
529 processors, then using
533 will generally speed things up by quite a bit.
535 \subsection{Installing \gromacs{}}
537 Finally, \verb+make install+ will install \gromacs{} in the
538 directory given in \verb+CMAKE_INSTALL_PREFIX+. If this is an system
539 directory, then you will need permission to write there, and you
540 should use super-user privileges only for \verb+make install+ and
541 not the whole procedure.
543 \subsection{Getting access to \gromacs{} after installation}
545 \gromacs{} installs the script \verb+GMXRC+ in the \verb+bin+
546 subdirectory of the installation directory
547 (e.g. \verb+/usr/local/gromacs/bin/GMXRC+), which you should source
550 $ source your-installation-prefix-here/bin/GMXRC
553 It will detect what kind of shell you are running and set up your
554 environment for using \gromacs{}. You may wish to arrange for your
555 login scripts to do this automatically; please search the web for
556 instructions on how to do this for your shell.
558 Many of the \gromacs{} programs rely on data installed in our
559 \verb+share/gromacs+ directory. By default, the programs will use
560 the environment variables set in the GMXRC script, and if this is not
561 available they will try to guess the path based on their own location.
562 This usually works well unless you change the names of directories
563 inside the install tree. If you still need to do that, you might want to recompile
564 with the new install location properly set, or edit the \verb+GMXRC+ script.
566 \subsection{Testing \gromacs{} for correctness}
567 Since 2011, the \gromacs{} development uses an automated system where
568 every new patch is subject to regression testing. While this improves
569 reliability quite a lot, not everything is tested, and since we
570 increasingly rely on cutting edge compiler features there is
571 non-negligible risk that the default compiler on your system could
572 have bugs. We have tried our best to test and refuse to use known bad
573 versions in \cmake{}, but we strongly recommend that you run through
574 the regression tests yourself. It only takes a few minutes, after
575 which you can trust your build.
577 The simplest way to run the checks is to build \gromacs{} with
578 \verb+-DREGRESSIONTEST_DOWNLOAD+, and run \verb+make check+.
579 \gromacs{} will automatically download and run the tests for you.
580 Alternatively, you can download and unpack the tarball yourself from
581 \url{http://gerrit.gromacs.org/download/regressiontests-4.6.4.tar.gz},
582 and use the advanced \cmake{} option \verb+REGRESSIONTEST_PATH+ to
583 specify the path to the unpacked tarball, which will then be used for
584 testing. If this doesn't work, then please read on.
586 The regression tests are available from the \gromacs{} website and ftp
587 site. Once you have downloaded them, unpack the tarball, source
588 \verb+GMXRC+ as described above, and run \verb+./gmxtest.pl all+
589 inside the regression tests folder. You can find more options
590 (e.g. adding \verb+double+ when using double precision) if you just
591 execute the script without options.
593 Hopefully you will get a report that all tests have passed. If there
594 are individual failed tests it could be a sign of a compiler bug, or
595 that a tolerance is just a tiny bit too tight. Check the output files
596 the script directs you too, and try a different or newer compiler if
597 the errors appear to be real. If you cannot get it to pass the
598 regression tests, you might try dropping a line to the gmx-users
599 mailing list, but then you should include a detailed description of
600 your hardware and an example logfile from mdrun (which contains
601 valuable information in the header).
603 \subsection{Testing \gromacs{} for performance}
604 We are still working on a set of benchmark systems for testing
605 the performance of \gromacs{}. Until that is ready, we recommend that
606 you start by comparing the performance to release 4.5, and also try
607 a few different parallelization options.
609 \subsection{Having difficulty?}
610 You're not alone - this can be a complex task! If you encounter a
611 problem with installing \gromacs{}, then there are a number of
612 locations where you can find assistance. It is recommended that you
613 follow these steps to find the solution:
616 \item Read the installation instructions again, taking note that you
617 have followed each and every step correctly.
618 \item Search the \gromacs{} website and users emailing list for
619 information on the error.
620 \item Search the internet using a search engine such as Google.
621 \item Post to the \gromacs{} users emailing list gmx-users for
622 assistance. Be sure to give a full description of what you have done
623 and why you think it didn't work. Give details about the system on
624 which you are installing.
625 Copy and paste your command line and as
626 much of the output as you think might be relevant - certainly from
627 the first indication of a problem. In particular, please try to include at
628 least the header from the mdrun logfile, and preferably the entire file.
629 People who might volunteer to
630 help you do not have time to ask you interactive detailed follow-up
631 questions, so you will get an answer faster if you provide as much
632 information as you think could possibly help. High quality bug reports
633 tend to receive rapid high quality answers.
636 \section{Special instructions for some platforms}
638 \subsection{Building on Windows}
639 Building on Cygwin/MinGW/etc. works just like Unix. Please see the
642 Building on Windows using native compilers is rather similar to
643 building on Unix, so please start by reading the above. Then, download
644 and unpack the GROMACS source archive. The UNIX-standard .tar.gz
645 format can be managed on Windows, but you may prefer to browse
646 \url{ftp://ftp.gromacs.org/pub/gromacs} to obtain a zip format file,
647 which doesn't need any external tools to unzip on recent Windows
648 systems. Make a folder in which to do the out-of-source build of
649 \gromacs{}. For example, make it within the folder unpacked from the
650 source archive, and call it ``build-cmake''.
652 For \cmake{}, you can either use the graphical user interface provided
653 on Windows, or you can use a command line shell with instructions
654 similar to the UNIX ones above. If you open a shell from within
655 your IDE (e.g. Microsoft Visual Studio), it will configure the
656 environment for you, but you might need to tweak this in order to
657 get either a 32-bit or 64-bit build environment. The latter provides the
658 fastest executable. If you use a normal Windows command shell, then
659 you will need to either set up the environment to find your compilers
660 and libraries yourself, or run the \verb+vcvarsall.bat+ batch script
661 provided by MSVC (just like sourcing a bash script under
664 With the graphical user interface you will be asked about what compilers
665 to use at the initial configuration stage, and if you use the command line
666 they can be set in a similar way as under UNIX.
667 You will probably make your life easier and faster by using the
668 new facility to download and install \fftw{} automatically.
670 For the build, you can either load the generated solutions file into
671 e.g. Visual Studio, or use the command line with \verb+cmake --build .+
672 so the right tools get used.
674 \subsection{Building on Cray}
676 Gromacs builds mostly out of the box on modern Cray machines,
677 but you want to use static libraries due to the peculiarities with
678 parallel job execution.
680 \subsection{Building on BlueGene}
682 \subsubsection{BlueGene/P}
684 There is currently no native acceleration on this platform and no
685 plans to make one. The default plain C kernels will work.
687 \subsubsection{BlueGene/Q}
689 There is currently native acceleration on this platform for the Verlet
690 cut-off scheme. Accelerated kernels for the group cut-off scheme may
691 come in the future, but the default plain C kernels will work.
693 Only static linking with XL compilers is supported by \gromacs{}. Dynamic
694 linking would be supported by the architecture and \gromacs{}, but has no
695 advantages other than disk space, and is generally discouraged on
696 BlueGene for performance reasons.
698 Computation on BlueGene floating-point units is always done in
699 double-precision. However, single-precision builds of \gromacs{} are
700 still normal and encouraged since they use cache more efficiently.
701 The BlueGene hardware automatically
702 converts values stored in single precision in memory to double
703 precision in registers for computation, converts the results back to
704 single precision correctly, and does so for no additional cost. As
705 with other platforms, doing the whole computation in double precision
706 normally shows no improvement in accuracy and costs twice as much time
707 moving memory around.
709 You need to arrange for FFTW to be installed correctly, following the
712 mpicc is used for compiling and linking. This can make it awkward to
713 attempt to use IBM's optimized BLAS/LAPACK called ESSL (see the
714 section on linear algebra). Since mdrun is the only part of \gromacs{}
715 that should normally run on the compute nodes, and there is nearly no
716 need for linear algebra support for mdrun, it is recommended to use
717 the \gromacs{} built-in linear algebra routines - it is rare for this
720 The recommended configuration is to use
722 cmake .. -DCMAKE_TOOLCHAIN_FILE=Platform/BlueGeneQ-static-XL-CXX \
723 -DCMAKE_PREFIX_PATH=/your/fftw/installation/prefix \
725 -DGMX_BUILD_MDRUN_ONLY=ON
729 which will build a statically-linked MPI-enabled mdrun for the back
730 end. Otherwise, GROMACS default configuration behaviour applies.
732 It is possible to configure and make the remaining \gromacs{} tools
733 with the compute-node toolchain, but as none of those tools are
734 \mpi{}-aware and could then only run on the compute nodes, this
735 would not normally be useful. Instead, these should be planned
736 to run on the login node, and a separate \gromacs{} installation
737 performed for that using the login node's toolchain - not the
738 above platform file, or any other compute-node toolchain.
740 Note that only the MPI build is available for the compute-node
741 toolchains. The GROMACS thread-MPI or serial builds are not useful at
744 \subsubsection{Fujitsu PRIMEHPC}
746 This is the architecture of the K computer, which uses Fujitsu Sparc64viiifx
747 chips. Gromacs-4.6 will build with default C kernels on this architecture,
748 and Gromacs-4.6.2 added accelerated group kernels and a custom toolchain.
750 \section{Tested platforms}
752 While it is our best belief that \gromacs{} will build and run pretty
753 much everywhere, it's important that we tell you where we really know
754 it works because we've tested it. We do test on Linux, Windows, and
755 Mac with a range of compilers and libraries for a range of our
756 configuration options. Every commit in our git source code
757 repository is currently tested on x86 with gcc versions ranging
758 from 4.4 through 4.7, and versions 12 and 13 of the Intel compiler.
759 Under Windows we test both the visual studio compilers and icc,
761 We test irregularly on BlueGene/Q, Cray,
762 Fujitsu PRIMEHPC, Google nativeclient and other environments. In
763 the future we expect ARM to be an important test target too, but this
764 is currently not included.
766 Contributions to this section are welcome.
768 Later we might set up the ability for users to contribute test results
771 \section{Other issues}
773 The \gromacs{} utility programs often write data files in formats
774 suitable for the \grace{} plotting tool, but it is straightforward to
775 use these files in other plotting programs, too.