admin/installguide/installguide.xhtml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3c.org/TR/MathML2/dtd/xhtml-math11-f.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:svg="http://www.w3.org/2000/svg">
   4   <head>
   5     <title>GROMACS installation guide</title>
   6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
   7     <link rel="stylesheet" type="text/css" href="core.css"/>
   8   </head>
   9   <body>
  10     <div class="navbar">
  11   <ul class="toc">
  12   <li class="tocentry"><span class="ref toc here">GROMACS installation guide</span>
  13   <ul class="toc">
  14   <li class="tocentry"><a href="#S1" title="1. Building GROMACS in GROMACS installation guide" class="ref toc">1 Building GROMACS</a></li>
  15   <li class="tocentry"><a href="#S2" title="2. Prerequisites in GROMACS installation guide" class="ref toc">2 Prerequisites</a>
  16   <ul class="toc">
  17   <li class="tocentry"><a href="#S2.SS1" title="2.1. Platform in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.1 Platform</a></li>
  18   <li class="tocentry"><a href="#S2.SS2" title="2.2. Compiler in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.2 Compiler</a>
  19   <ul class="toc">
  20   <li class="tocentry"><a href="#S2.SS2.SSS1" title="2.2.1. Running in parallel in 2.2. Compiler in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.2.1 Running in parallel</a></li>
  21     </ul></li>
  22   <li class="tocentry"><a href="#S2.SS3" title="2.3. CMake in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.3 CMake</a></li>
  23   <li class="tocentry"><a href="#S2.SS4" title="2.4. Fast Fourier Transform library in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.4 Fast Fourier Transform library</a>
  24   <ul class="toc">
  25   <li class="tocentry"><a href="#S2.SS4.SSS1" title="2.4.1. FFTW in 2.4. Fast Fourier Transform library in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.4.1 FFTW</a></li>
  26   <li class="tocentry"><a href="#S2.SS4.SSS2" title="2.4.2. MKL in 2.4. Fast Fourier Transform library in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.4.2 MKL</a></li>
  27     </ul></li>
  28   <li class="tocentry"><a href="#S2.SS5" title="2.5. Optional build components in 2. Prerequisites in GROMACS installation guide" class="ref toc">2.5 Optional build components</a></li>
  29     </ul></li>
  30   <li class="tocentry"><a href="#S3" title="3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3 Doing a build of GROMACS</a>
  31   <ul class="toc">
  32   <li class="tocentry"><a href="#S3.SS1" title="3.1. Configuring with CMake in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.1 Configuring with CMake</a></li>
  33   <li class="tocentry"><a href="#S3.SS2" title="3.2. Using CMake command-line options in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.2 Using CMake command-line options</a></li>
  34   <li class="tocentry"><a href="#S3.SS3" title="3.3. CMake advanced options in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.3 CMake advanced options</a></li>
  35   <li class="tocentry"><a href="#S3.SS4" title="3.4. Helping CMake find the right libraries/headers/programs in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.4 Helping CMake find the right libraries/headers/programs</a></li>
  36   <li class="tocentry"><a href="#S3.SS5" title="3.5. CMake advice during the GROMACS 4.6 beta phase in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.5 CMake advice during the GROMACS 4.6 beta phase</a></li>
  37   <li class="tocentry"><a href="#S3.SS6" title="3.6. Native GPU acceleration in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.6 Native GPU acceleration</a></li>
  38   <li class="tocentry"><a href="#S3.SS7" title="3.7. Static linking in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.7 Static linking</a></li>
  39   <li class="tocentry"><a href="#S3.SS8" title="3.8. Suffixes for binaries and libraries in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.8 Suffixes for binaries and libraries</a></li>
  40   <li class="tocentry"><a href="#S3.SS9" title="3.9. Building GROMACS in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.9 Building GROMACS</a></li>
  41   <li class="tocentry"><a href="#S3.SS10" title="3.10. Installing GROMACS in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.10 Installing GROMACS</a></li>
  42   <li class="tocentry"><a href="#S3.SS11" title="3.11. Getting access to GROMACS after installation in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.11 Getting access to GROMACS after installation</a></li>
  43   <li class="tocentry"><a href="#S3.SS12" title="3.12. Testing GROMACS for correctness in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.12 Testing GROMACS for correctness</a></li>
  44   <li class="tocentry"><a href="#S3.SS13" title="3.13. Testing GROMACS for performance in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.13 Testing GROMACS for performance</a></li>
  45   <li class="tocentry"><a href="#S3.SS14" title="3.14. Having difficulty? in 3. Doing a build of GROMACS in GROMACS installation guide" class="ref toc">3.14 Having difficulty?</a></li>
  46     </ul></li>
  47   <li class="tocentry"><a href="#S4" title="4. Special instructions for some platforms in GROMACS installation guide" class="ref toc">4 Special instructions for some platforms</a>
  48   <ul class="toc">
  49   <li class="tocentry"><a href="#S4.SS1" title="4.1. Building on Windows in 4. Special instructions for some platforms in GROMACS installation guide" class="ref toc">4.1 Building on Windows</a></li>
  50   <li class="tocentry"><a href="#S4.SS2" title="4.2. Building on Cray in 4. Special instructions for some platforms in GROMACS installation guide" class="ref toc">4.2 Building on Cray</a></li>
  51   <li class="tocentry"><a href="#S4.SS3" title="4.3. Building on BlueGene in 4. Special instructions for some platforms in GROMACS installation guide" class="ref toc">4.3 Building on BlueGene</a>
  52   <ul class="toc">
  53   <li class="tocentry"><a href="#S4.SS3.SSS1" title="4.3.1. BlueGene/P in 4.3. Building on BlueGene in 4. Special instructions for some platforms in GROMACS installation guide" class="ref toc">4.3.1 BlueGene/P</a></li>
  54   <li class="tocentry"><a href="#S4.SS3.SSS2" title="4.3.2. BlueGene/Q in 4.3. Building on BlueGene in 4. Special instructions for some platforms in GROMACS installation guide" class="ref toc">4.3.2 BlueGene/Q</a></li>
  55     </ul></li>
  56     </ul></li>
  57   <li class="tocentry"><a href="#S5" title="5. Tested platforms in GROMACS installation guide" class="ref toc">5 Tested platforms</a></li>
  58   <li class="tocentry"><a href="#S6" title="6. Other issues in GROMACS installation guide" class="ref toc">6 Other issues</a></li>
  59     </ul></li>
  60     </ul>
  61       </div>
  62     <div class="main">
  63     <div class="content">
  64     <div class="document">
  65     <h1 class="title document-title">GROMACS installation guide</h1>
  66     <div class="section" id="S1">
  67     <h2 class="title section-title"> 1. Building GROMACS</h2>
  68   <div class="para" id="S1.p1">
  69     <p class="p">These instructions pertain to building GROMACS 4.6 beta releases
  70 and newer. For installations instructions for old GROMACS versions,
  71 see here
  72 <a href="http://www.gromacs.org/Documentation/Installation_Instructions_4.5" title="" class="ref url"><span style="" class="text typewriter">http://www.gromacs.org/Documentation/Installation_Instructions_4.5</span></a>.</p>
  73   </div>
  74
  75     </div>
  76
  77     <div class="section" id="S2">
  78     <h2 class="title section-title"> 2. Prerequisites</h2>
  79     <div class="subsection" id="S2.SS1">
  80     <h3 class="title subsection-title"> 2.1. Platform</h3>
  81   <div class="para" id="S2.SS1.p1">
  82     <p class="p">GROMACS can be compiled for any distribution of Linux, Mac OS X,
  83 Windows (native, Cygwin or MinGW), BlueGene, Cray and probably others.
  84 Technically, it can be compiled on any platform with an ANSI C
  85 compiler and supporting libraries, such as the GNU C library. It can
  86 even compile on an iPhone! Later, there will be a detailed list of
  87 hardware, platform and compilers upon which we do build and regression
  88 testing.</p>
  89   </div>
  90
  91     </div>
  92
  93     <div class="subsection" id="S2.SS2">
  94     <h3 class="title subsection-title"> 2.2. Compiler</h3>
  95   <div class="para" id="S2.SS2.p1">
  96     <p class="p">GROMACS requires an ANSI C compiler that complies with the C89
  97 standard. For best performance, the GROMACS team strongly
  98 recommends you get the most recent version of your preferred compiler
  99 for your platform (e.g. GCC 4.7 or Intel 12.0 or newer on x86
 100 hardware). There is a large amount of GROMACS code introduced in
 101 version 4.6 that depends on effective compiler optimization to get
 102 high performance - the old assembly-language routines have all
 103 gone. For other platforms, use the vendor's compiler, and check for
 104 specialized information below.</p>
 105   </div>
 106
 107     <div class="subsubsection" id="S2.SS2.SSS1">
 108     <h4 class="title subsubsection-title"> 2.2.1. Running in parallel</h4>
 109   <div class="para" id="S2.SS2.SSS1.p1">
 110     <p class="p">GROMACS can run in parallel on multiple cores of a single
 111 workstation using its built-in ThreadMPI. No user action is required
 112 in order to enable this.</p>
 113   </div>
 114
 115   <div class="para" id="S2.SS2.SSS1.p2">
 116     <p class="p">If you wish to use the excellent new native GPU support in GROMACS,
 117 NVIDIA's CUDA
 118 <a href="http://www.nvidia.com/object/cuda_home_new.html" title="" class="ref url"><span style="" class="text typewriter">http://www.nvidia.com/object/cuda_home_new.html</span></a> version
 119 3.2 software development kit is required, and the latest
 120 version is encouraged. NVIDIA GPUs with at least NVIDIA compute
 121 capability 2.0 are required, e.g. Fermi or Kepler cards.</p>
 122   </div>
 123
 124   <div class="para" id="S2.SS2.SSS1.p3">
 125     <p class="p">The GPU support from GROMACS version 4.5 using OpenMM
 126 <a href="https://simtk.org/home/openmm" title="" class="ref url"><span style="" class="text typewriter">https://simtk.org/home/openmm</span></a> is still available, also requires
 127 CUDA, and remains the only hardware-based acceleration available
 128 for implicit solvent simulations in GROMACS. This parallelization
 129 path may not be maintained in the future.</p>
 130   </div>
 131
 132   <div class="para" id="S2.SS2.SSS1.p4">
 133     <p class="p">If you wish to run in parallel on multiple machines across a network,
 134 you will need to have</p>
 135
 136     <ul class="itemize" id="I1">
 137
 138         <li class="item" id="I1.i1">
 139
 140   <div class="para" id="I1.i1.p1">
 141     <p class="p">an MPI library installed that supports the MPI 1.3
 142 standard, and</p>
 143   </div>
 144
 145         </li>
 146
 147         <li class="item" id="I1.i2">
 148
 149   <div class="para" id="I1.i2.p1">
 150     <p class="p">wrapper compilers that will compile code using that library.</p>
 151   </div>
 152
 153         </li>
 154
 155     </ul>
 156
 157     <p class="p">The GROMACS team recommends OpenMPI
 158 <a href="http://www.open-mpi.org/" title="" class="ref url"><span style="" class="text typewriter">http://www.open-mpi.org/</span></a> version 1.4.1 (or higher), MPICH
 159 <a href="http://www.mpich.org/" title="" class="ref url"><span style="" class="text typewriter">http://www.mpich.org/</span></a> version 1.4.1 (or higher), or your
 160 hardware vendor's MPI installation. The most recent version of
 161 either of this is likely to be the best. LAM/MPI
 162 <a href="http://www.lam-mpi.org/" title="" class="ref url"><span style="" class="text typewriter">http://www.lam-mpi.org/</span></a> may work, but since it has been
 163 deprecated for years, it is not supported.</p>
 164   </div>
 165
 166   <div class="para" id="S2.SS2.SSS1.p5">
 167     <p class="p">In some cases, OpenMP parallelism is an advantage for GROMACS,
 168 but support for this is generally built into your compiler and you
 169 need to make no advance preparation for this. The performance gain you
 170 might achieve can vary with the compiler.</p>
 171   </div>
 172
 173   <div class="para" id="S2.SS2.SSS1.p6">
 174     <p class="p">It is important to examine how you will use GROMACS and upon what
 175 hardware and with what compilers in deciding which parallelization
 176 paths to make available. Testing the performance of different options
 177 is unfortunately mandatory. The days of being able to just build and
 178 run '<code class="verbatim">mdrun</code>' and get decent performance by default on your
 179 hardware are long gone. GROMACS will always run correctly, and does
 180 a decent job of trying to maximize your performance, but if you want
 181 to approach close to the optimum, you will need to do some work for
 182 it!</p>
 183   </div>
 184
 185     </div>
 186
 187     </div>
 188
 189     <div class="subsection" id="S2.SS3">
 190     <h3 class="title subsection-title"> 2.3. CMake</h3>
 191   <div class="para" id="S2.SS3.p1">
 192     <p class="p">From version 4.6, GROMACS has moved to use the build system
 193 CMake. The previous build system that used <span style="" class="text typewriter">configure</span> from
 194 the GNU autotools package has been removed permanently. CMake
 195 permits the GROMACS team to support a very wide range of hardware,
 196 compilers and build configurations while continuing to provide the
 197 portability, robustness and performance for which GROMACS is known.</p>
 198   </div>
 199
 200   <div class="para" id="S2.SS3.p2">
 201     <p class="p">GROMACS requires CMake version 2.8.0 or higher. Lower
 202 versions will not work. You can check whether CMake is installed,
 203 and what version it is, with <span style="" class="text typewriter">cmake --version</span>. If you need to
 204 install CMake, then first check whether your platform's package
 205 management system provides a suitable version, or visit
 206 <a href="http://www.cmake.org/cmake/help/install.html" title="" class="ref url"><span style="" class="text typewriter">http://www.cmake.org/cmake/help/install.html</span></a> for pre-compiled
 207 binaries, source code and installation instructions. The GROMACS
 208 team recommends you install the most recent version of CMake you
 209 can.
 210 </p>
 211   </div>
 212
 213     </div>
 214
 215     <div class="subsection" id="S2.SS4">
 216     <h3 class="title subsection-title"> 2.4. Fast Fourier Transform library</h3>
 217   <div class="para" id="S2.SS4.p1">
 218     <p class="p">Many simulations in GROMACS make extensive use of Fourier transforms,
 219 and a software library to perform these is always required. We
 220 recommend FFTW <a href="http://www.fftw.org/" title="" class="ref url"><span style="" class="text typewriter">http://www.fftw.org/</span></a> (version 3 or higher
 221 only) or Intel's MKL
 222 <a href="http://software.intel.com/en-us/intel-mkl" title="" class="ref url"><span style="" class="text typewriter">http://software.intel.com/en-us/intel-mkl</span></a>.</p>
 223   </div>
 224
 225     <div class="subsubsection" id="S2.SS4.SSS1">
 226     <h4 class="title subsubsection-title"> 2.4.1. FFTW</h4>
 227   <div class="para" id="S2.SS4.SSS1.p1">
 228     <p class="p">FFTW is likely to be available for your platform via its package
 229 management system, but there can be compatibility and significant
 230 performance issues associated with these packages. In particular,
 231 GROMACS simulations are normally run in single floating-point
 232 precision whereas the default FFTW package is normally in double
 233 precision, and good compiler options to use for FFTW when linked to
 234 GROMACS may not have been used. Accordingly, the GROMACS team
 235 recommends either</p>
 236
 237     <ul class="itemize" id="I2">
 238
 239         <li class="item" id="I2.i1">
 240
 241   <div class="para" id="I2.i1.p1">
 242     <p class="p">that you permit the GROMACS installation to download and
 243 build FFTW 3.3.2 from source automatically
 244 for you, or</p>
 245   </div>
 246
 247         </li>
 248
 249         <li class="item" id="I2.i2">
 250
 251   <div class="para" id="I2.i2.p1">
 252     <p class="p">that you build FFTW from the source code.</p>
 253   </div>
 254
 255         </li>
 256
 257     </ul>
 258   </div>
 259
 260   <div class="para" id="S2.SS4.SSS1.p2">
 261     <p class="p">If you build FFTW from source yourself, get the most recent version
 262 and follow its installation guide
 263 (e.g. <a href="http://www.fftw.org/fftw3_doc/Installation-and-Customization.html" title="" class="ref url"><span style="" class="text typewriter">http://www.fftw.org/fftw3_doc/Installation-and-Customization.html</span></a>). Choose
 264 the precision (i.e. single or float vs double) to match what you will
 265 later require for GROMACS. There is no need to compile with
 266 threading or MPI support, but it does no harm. On x86 hardware,
 267 compile <em class="emph">only</em> with <span style="" class="text typewriter">--enable-sse2</span> (regardless of
 268 precision) even if your processors can take advantage of AVX
 269 extensions to SSE. The way GROMACS uses Fourier transforms
 270 cannot take advantage of this feature in FFTW because of memory
 271 system performance limitations, it can degrade performance by around
 272 20%, and there is no way for GROMACS to require the use of the
 273 SSE2 at run time if AVX support has been compiled into FFTW.</p>
 274   </div>
 275
 276     </div>
 277
 278     <div class="subsubsection" id="S2.SS4.SSS2">
 279     <h4 class="title subsubsection-title"> 2.4.2. MKL</h4>
 280   <div class="para" id="S2.SS4.SSS2.p1">
 281     <p class="p">Using MKL requires a set of linker flags that GROMACS is not
 282 able to detect for you, so setting up optimal linking is tricky at the
 283 moment. Need better documentation later.</p>
 284   </div>
 285
 286     </div>
 287
 288     </div>
 289
 290     <div class="subsection" id="S2.SS5">
 291     <h3 class="title subsection-title"> 2.5. Optional build components</h3>
 292   <div class="para" id="S2.SS5.p1">
 293     <ul class="itemize" id="I3">
 294
 295         <li class="item" id="I3.i1">
 296
 297   <div class="para" id="I3.i1.p1">
 298     <p class="p">A hardware-optimized BLAS or LAPACK library is useful for
 299 some of the GROMACS utilities, but is not needed for running
 300 simulations.</p>
 301   </div>
 302
 303         </li>
 304
 305         <li class="item" id="I3.i2">
 306
 307   <div class="para" id="I3.i2.p1">
 308     <p class="p">The built-in GROMACS trajectory viewer <span style="" class="text typewriter">ngmx</span> requires
 309 X11 and Motif/Lesstif libraries and header files. Generally, the
 310 GROMACS team recommends you use third-party software for
 311 visualization, such as VMD
 312 <a href="http://www.ks.uiuc.edu/Research/vmd/" title="" class="ref url"><span style="" class="text typewriter">http://www.ks.uiuc.edu/Research/vmd/</span></a> or PyMOL
 313 <a href="http://www.pymol.org/" title="" class="ref url"><span style="" class="text typewriter">http://www.pymol.org/</span></a>.</p>
 314   </div>
 315
 316         </li>
 317
 318     </ul>
 319   </div>
 320
 321     </div>
 322
 323     </div>
 324
 325     <div class="section" id="S3">
 326     <h2 class="title section-title"> 3. Doing a build of GROMACS</h2>
 327   <div class="para" id="S3.p1">
 328     <p class="p">This section will cover a general build of GROMACS with CMake,
 329 but it is not an exhaustive discussion of how to use CMake. There
 330 are many resources available on the web, which we suggest you search
 331 for when you encounter problems not covered here. The material below
 332 applies specifically to builds on Unix-like systems, including Linux,
 333 Mac OS X, MinGW and Cygwin. For other platforms, see the specialist
 334 instructions below.</p>
 335   </div>
 336
 337     <div class="subsection" id="S3.SS1">
 338     <h3 class="title subsection-title"> 3.1. Configuring with CMake</h3>
 339   <div class="para" id="S3.SS1.p1">
 340     <p class="p">CMake will run many tests on your system and do its best to work
 341 out how to build GROMACS for you. If you are building GROMACS on
 342 hardware that is identical to that where you will run <span style="" class="text typewriter">mdrun</span>,
 343 then you can be sure that the defaults will be pretty good. Howver, if
 344 you want to control aspects of the build, there's plenty of things you
 345 can set, too.</p>
 346   </div>
 347
 348   <div class="para" id="S3.SS1.p2">
 349     <p class="p">The best way to use CMake to configure GROMACS is to do an
 350 “out-of-source” build, by making another directory from which you
 351 will run CMake. This can be a subdirectory or not, it doesn't
 352 matter. It also means you can never corrupt your source code by trying
 353 to build it! So, the only required argument on the CMake command
 354 line is the name of the directory containing the
 355 <span style="" class="text typewriter">CMakeLists.txt</span> file of the code you want to build. For
 356 example, download the source tarball and use
 357 </p>
 358   <pre class="verbatim">
 359 $ tar xfz gromacs-4.6-beta1-src.tgz
 360 $ cd gromacs-4.6-beta1
 361 $ mkdir build-cmake
 362 $ cd build-cmake
 363 $ cmake ..
 364 </pre></div>
 365
 366   <div class="para" id="S3.SS1.p3">
 367     <p class="p">You will see <span style="" class="text typewriter">cmake</span> report the results of a large number of
 368 tests on your system made by CMake and by GROMACS. These are
 369 written to the CMake cache, kept in <span style="" class="text typewriter">CMakeCache.txt</span>. You
 370 can edit this file by hand, but this is not recommended because it is
 371 easy to reach an inconsistent state. You should not attempt to move or
 372 copy this file to do another build, because the paths are hard-coded
 373 within it. If you mess things up, just delete this file and start
 374 again with '<code class="verbatim">cmake</code>'.</p>
 375   </div>
 376
 377   <div class="para" id="S3.SS1.p4">
 378     <p class="p">If there's a serious problem detected at this stage, then you will see
 379 a fatal error and some suggestions for how to overcome it. If you're
 380 not sure how to deal with that, please start by searching on the web
 381 (most computer problems already have known solutions!) and then
 382 consult the <span style="" class="text typewriter">gmx-users</span> mailing list. There are also
 383 informational warnings that you might like to take on board or
 384 not. Piping the output of <span style="" class="text typewriter">cmake</span> through <span style="" class="text typewriter">less</span> or
 385 <span style="" class="text typewriter">tee</span> can be useful, too.</p>
 386   </div>
 387
 388   <div class="para" id="S3.SS1.p5">
 389     <p class="p">CMake works in an iterative fashion, re-running each time a setting
 390 is changed to try to make sure other things are consistent. Once
 391 things seem consistent, the iterations stop. Once <span style="" class="text typewriter">cmake</span>
 392 returns, you can see all the settings that were chosen and information
 393 about them by using</p>
 394   <pre class="verbatim">
 395 $ ccmake ..
 396 </pre>
 397     <p class="p">Check out <a href="http://www.cmake.org/cmake/help/runningcmake.html" title="" class="ref url"><span style="" class="text typewriter">http://www.cmake.org/cmake/help/runningcmake.html</span></a> for
 398 general advice on what you are seeing and how to navigate and change
 399 things. The settings you might normally want to change are already
 400 presented. If you make any changes, then <span style="" class="text typewriter">ccmake</span> will notice
 401 that and require that you re-configure (using '<code class="verbatim">c</code>'), so that it
 402 gets a chance to make changes that depend on yours and perform more
 403 checking. This might require several configuration stages when you are
 404 using <span style="" class="text typewriter">ccmake</span> - when you are using <span style="" class="text typewriter">cmake</span> the
 405 iteration is done behind the scenes.</p>
 406   </div>
 407
 408   <div class="para" id="S3.SS1.p6">
 409     <p class="p">A key thing to consider here is the setting of
 410 <span style="" class="text typewriter">GMX_INSTALL_PREFIX</span>. You will need to be able to write to this
 411 directory in order to install GROMACS later, and if you change your
 412 mind later, changing it in the cache triggers a full re-build,
 413 unfortunately. So if you do not have super-user privileges on your
 414 machine, then you will need to choose a sensible location within your
 415 home directory for your GROMACS installation.</p>
 416   </div>
 417
 418   <div class="para" id="S3.SS1.p7">
 419     <p class="p">When <span style="" class="text typewriter">cmake</span> or <span style="" class="text typewriter">ccmake</span> have completed iterating, the
 420 cache is stable and a build tree can be generated, with '<code class="verbatim">g</code>' in
 421 <span style="" class="text typewriter">ccmake</span> or automatically with <span style="" class="text typewriter">cmake</span>.</p>
 422   </div>
 423
 424     </div>
 425
 426     <div class="subsection" id="S3.SS2">
 427     <h3 class="title subsection-title"> 3.2. Using CMake command-line options</h3>
 428   <div class="para" id="S3.SS2.p1">
 429     <p class="p">Once you become comfortable with setting and changing options, you
 430 may know in advance how you will configure GROMACS. If so, you can
 431 speed things up by invoking <span style="" class="text typewriter">cmake</span> with a command like:</p>
 432   <pre class="verbatim">
 433 $ cmake .. -DGMX_GPU=ON -DGMX_MPI=ON -DGMX_INSTALL_PREFIX=/home/marydoe/programs
 434 </pre>
 435     <p class="p">to build with GPUs, MPI and install in a custom location. You can even
 436 save that in a shell script to make it even easier next time. You can
 437 also do this kind of thing with <span style="" class="text typewriter">ccmake</span>, but you should avoid
 438 this, because the options set with '<code class="verbatim">-D</code>' will not be able to be
 439 changed interactively in that run of <span style="" class="text typewriter">ccmake</span>.</p>
 440   </div>
 441
 442     </div>
 443
 444     <div class="subsection" id="S3.SS3">
 445     <h3 class="title subsection-title"> 3.3. CMake advanced options</h3>
 446   <div class="para" id="S3.SS3.p1">
 447     <p class="p">The options that can be seen with <span style="" class="text typewriter">ccmake</span> are ones that we
 448 think a reasonable number of users might want to consider
 449 changing. There are a lot more options available, which you can see by
 450 toggling the advanced mode in <span style="" class="text typewriter">ccmake</span> on and off with
 451 '<code class="verbatim">t</code>'. Even there, most of the variables that you might want to
 452 change have a '<code class="verbatim">CMAKE_</code>' or '<code class="verbatim">GMX_</code>' prefix.</p>
 453   </div>
 454
 455     </div>
 456
 457     <div class="subsection" id="S3.SS4">
 458     <h3 class="title subsection-title"> 3.4. Helping CMake find the right libraries/headers/programs</h3>
 459   <div class="para" id="S3.SS4.p1">
 460     <p class="p">If libraries are installed in non-default locations their location can
 461 be specified using the following environment variables:</p>
 462
 463     <ul class="itemize" id="I4">
 464
 465         <li class="item" id="I4.i1">
 466
 467   <div class="para" id="I4.i1.p1">
 468     <p class="p"><span style="" class="text typewriter">CMAKE_INCLUDE_PATH</span> for header files</p>
 469   </div>
 470
 471         </li>
 472
 473         <li class="item" id="I4.i2">
 474
 475   <div class="para" id="I4.i2.p1">
 476     <p class="p"><span style="" class="text typewriter">CMAKE_LIBRARY_PATH</span> for libraries</p>
 477   </div>
 478
 479         </li>
 480
 481         <li class="item" id="I4.i3">
 482
 483   <div class="para" id="I4.i3.p1">
 484     <p class="p"><span style="" class="text typewriter">CMAKE_PREFIX_PATH</span> for header, libraries and binaries
 485 (e.g. '<code class="verbatim">/usr/local</code>').</p>
 486   </div>
 487
 488         </li>
 489
 490     </ul>
 491
 492     <p class="p">The respective '<code class="verbatim">include</code>', '<code class="verbatim">lib</code>', or '<code class="verbatim">bin</code>' is
 493 appended to the path. For each of these variables, a list of paths can
 494 be specified (on Unix seperated with ”:”). Note that these are
 495 enviroment variables (and not CMake command-line arguments) and in
 496 a '<code class="verbatim">bash</code>' shell are used like:</p>
 497   <pre class="verbatim">
 498 $ CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
 499 </pre></div>
 500
 501   <div class="para" id="S3.SS4.p2">
 502     <p class="p">The <span style="" class="text typewriter">CC</span> and <span style="" class="text typewriter">CXX</span> environment variables are also useful
 503 for indicating to CMake which compilers to use, which can be very
 504 important for maximising GROMACS performance. Similarly,
 505 <span style="" class="text typewriter">CFLAGS</span>/<span style="" class="text typewriter">CXXFLAGS</span> can be used to pass compiler
 506 options, but note that these will be appended to those set by
 507 GROMACS for your build platform and build type. You can customize
 508 some of this with advanced options such as <span style="" class="text typewriter">CMAKE_C_FLAGS</span>
 509 and its relatives.</p>
 510   </div>
 511
 512   <div class="para" id="S3.SS4.p3">
 513     <p class="p">See also: <a href="http://cmake.org/Wiki/CMake_Useful_Variables#Environment_Variables" title="" class="ref url"><span style="" class="text typewriter">http://cmake.org/Wiki/CMake_Useful_Variables#Environment_Variables</span></a></p>
 514   </div>
 515
 516     </div>
 517
 518     <div class="subsection" id="S3.SS5">
 519     <h3 class="title subsection-title"> 3.5. CMake advice during the GROMACS 4.6 beta phase</h3>
 520   <div class="para" id="S3.SS5.p1">
 521     <p class="p">We'd like users to have the ability to change any setting and still
 522 have the CMake cache stable; ie. not have things you set
 523 mysteriously change, or (worse) the whole thing breaks. We're not
 524 there yet. If you know in advance you will want to use a particular
 525 setting, set that on the initial <span style="" class="text typewriter">cmake</span> command line. If you
 526 have to change compilers, do that there, or immediately afterwards in
 527 <span style="" class="text typewriter">ccmake</span>. Gross changes like GPU or shared libraries on/off are
 528 more likely to work if you do them on the initial command line,
 529 because that's how we've been doing it while developing and
 530 testing. If you do make a mess of things, there's a great thing about
 531 an out-of-source build - you can just do '<code class="verbatim">rm -rf *</code>' and start
 532 again. Easy!</p>
 533   </div>
 534
 535   <div class="para" id="S3.SS5.p2">
 536     <p class="p">We are interested in learning how you managed to break things. If you
 537 can reproducibly reach a state where CMake can't proceed, or
 538 subsequent compilation/linking/running fails, then we need to know so
 539 we can fix it!</p>
 540   </div>
 541
 542     </div>
 543
 544     <div class="subsection" id="S3.SS6">
 545     <h3 class="title subsection-title"> 3.6. Native GPU acceleration</h3>
 546   <div class="para" id="S3.SS6.p1">
 547     <p class="p">If you have the CUDA SDK installed, you can use CMake
 548 with:</p>
 549   <pre class="verbatim">
 550 cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
 551 </pre>
 552     <p class="p">(or whichever path has your installation). Note that this will require
 553 a working C++ compiler, and in some cases you might need to handle
 554 this manually, e.g. with the advanced option
 555 <span style="" class="text typewriter">CUDA_HOST_COMPILER</span>.</p>
 556   </div>
 557
 558   <div class="para" id="S3.SS6.p2">
 559     <p class="p">More documentation needed here - particular discussion of fiddly
 560 details on Windows, Linux and Mac required. Not all compilers on all
 561 systems can be made to work.</p>
 562   </div>
 563
 564     </div>
 565
 566     <div class="subsection" id="S3.SS7">
 567     <h3 class="title subsection-title"> 3.7. Static linking</h3>
 568   <div class="para" id="S3.SS7.p1">
 569     <p class="p">Dynamic linking of the GROMACS executables will lead to a smaller
 570 disk footprint when installed, and so is the default. However, on some
 571 hardware or under some circumstances you might need to do static
 572 linking. To link GROMACS binaries statically against the internal
 573 GROMACS libraries, set <span style="" class="text typewriter">BUILD_SHARED_LIBS=OFF</span>. To link
 574 statically against external libraries as well, the
 575 <span style="" class="text typewriter">GMX_PREFER_STATIC_LIBS=ON</span> option can be used. Note, that
 576 in general CMake picks up whatever is available, so this option
 577 only instructs CMake to prefer static libraries when both static
 578 and shared are available. If no static version of an external library
 579 is available, even when the aforementioned option is ON, the shared
 580 library will be used. Also note, that the resulting binaries will
 581 still be dynamically linked against system libraries if that is all
 582 that is available.</p>
 583   </div>
 584
 585     </div>
 586
 587     <div class="subsection" id="S3.SS8">
 588     <h3 class="title subsection-title"> 3.8. Suffixes for binaries and libraries</h3>
 589   <div class="para" id="S3.SS8.p1">
 590     <p class="p">It is sometimes convenient to have different versions of the same
 591 GROMACS libraries installed. The most common use cases have been
 592 single and double precision, and with and without MPI. By default,
 593 GROMACS will suffix binaries and libraries for such builds with
 594 '<code class="verbatim">_d</code>' for double precision and/or '<code class="verbatim">_mpi</code>' for MPI (and
 595 nothing otherwise). This can be controlled manually with
 596 <span style="" class="text typewriter">GMX_DEFAULT_SUFFIX</span>, <span style="" class="text typewriter">GMX_BINARY_SUFFIX</span> and
 597 <span style="" class="text typewriter">GMX_LIBRARY_SUFFIX</span>.</p>
 598   </div>
 599
 600     </div>
 601
 602     <div class="subsection" id="S3.SS9">
 603     <h3 class="title subsection-title"> 3.9. Building GROMACS</h3>
 604   <div class="para" id="S3.SS9.p1">
 605     <p class="p">Once you have a stable cache, you can build GROMACS. If you're not
 606 sure the cache is stable, you can re-run <code class="verbatim">cmake ..</code> or
 607 <code class="verbatim">ccmake ..</code>' to see. Then you can run <span style="" class="text typewriter">make</span> to start the
 608 compilation. Before actual compilation starts, <span style="" class="text typewriter">make</span> checks
 609 that the cache is stable, so if it isn't you will see CMake run
 610 again.</p>
 611   </div>
 612
 613   <div class="para" id="S3.SS9.p2">
 614     <p class="p">So long as any changes you've made to the configuration are sensible,
 615 it is expected that the <span style="" class="text typewriter">make</span> procedure will always complete
 616 successfully. The tests GROMACS makes on the settings you choose
 617 are pretty extensive, but there are probably a few cases we haven't
 618 thought of yet. Search the web first for solutions to problems,
 619 but if you need help, ask on <span style="" class="text typewriter">gmx-users</span>, being sure to provide
 620 as much information as possible about what you did, the system you are
 621 building on, and what went wrong.</p>
 622   </div>
 623
 624   <div class="para" id="S3.SS9.p3">
 625     <p class="p">If you have a multi-core or multi-CPU machine with <span style="" class="text typewriter">N</span>
 626 processors, then using
 627 </p>
 628   <pre class="verbatim">
 629 $ make -j N
 630 </pre>
 631     <p class="p">will generally speed things up by quite a bit.</p>
 632   </div>
 633
 634     </div>
 635
 636     <div class="subsection" id="S3.SS10">
 637     <h3 class="title subsection-title"> 3.10. Installing GROMACS</h3>
 638   <div class="para" id="S3.SS10.p1">
 639     <p class="p">Finally, <span style="" class="text typewriter">make install</span> will install GROMACS in the
 640 directory given in <span style="" class="text typewriter">GMX_INSTALL_PREFIX</span>. If this is an system
 641 directory, then you will need permission to write there, and you
 642 should use super-user privileges only for <span style="" class="text typewriter">make install</span> and
 643 not the whole procedure.</p>
 644   </div>
 645
 646     </div>
 647
 648     <div class="subsection" id="S3.SS11">
 649     <h3 class="title subsection-title"> 3.11. Getting access to GROMACS after installation</h3>
 650   <div class="para" id="S3.SS11.p1">
 651     <p class="p">GROMACS installs the script <span style="" class="text typewriter">GMXRC</span> in the <span style="" class="text typewriter">bin</span>
 652 subdirectory of the installation directory
 653 (e.g. <span style="" class="text typewriter">/usr/local/gromacs/bin/GMXRC</span>), which you should source
 654 from your shell:</p>
 655   <pre class="verbatim">
 656 $ source your-installation-prefix-here/bin/GMXRC
 657 </pre></div>
 658
 659   <div class="para" id="S3.SS11.p2">
 660     <p class="p">It will detect what kind of shell you are running and
 661 set up your environment for using GROMACS. You may wish to arrange
 662 for your login scripts to do this automatically; please search the web
 663 for instructions on how to do this for your shell.</p>
 664   </div>
 665
 666     </div>
 667
 668     <div class="subsection" id="S3.SS12">
 669     <h3 class="title subsection-title"> 3.12. Testing GROMACS for correctness</h3>
 670   <div class="para" id="S3.SS12.p1">
 671     <p class="p">TODO install and use regression set</p>
 672   </div>
 673
 674     </div>
 675
 676     <div class="subsection" id="S3.SS13">
 677     <h3 class="title subsection-title"> 3.13. Testing GROMACS for performance</h3>
 678   <div class="para" id="S3.SS13.p1">
 679     <p class="p">TODO benchmarks</p>
 680   </div>
 681
 682     </div>
 683
 684     <div class="subsection" id="S3.SS14">
 685     <h3 class="title subsection-title"> 3.14. Having difficulty?</h3>
 686   <div class="para" id="S3.SS14.p1">
 687     <p class="p">You're not alone, this can be a complex task. If you encounter a
 688 problem with installing GROMACS, then there are a number of
 689 locations where you can find assistance. It is recommended that you
 690 follow these steps to find the solution:</p>
 691   </div>
 692
 693   <div class="para" id="S3.SS14.p2">
 694     <ol class="enumerate" id="I5">
 695
 696         <li class="item" id="I5.i1">
 697
 698   <div class="para" id="I5.i1.p1">
 699     <p class="p">Read the installation instructions again, taking note that you
 700 have followed each and every step correctly.</p>
 701   </div>
 702
 703         </li>
 704
 705         <li class="item" id="I5.i2">
 706
 707   <div class="para" id="I5.i2.p1">
 708     <p class="p">Search the GROMACS website and users emailing list for
 709 information on the error.</p>
 710   </div>
 711
 712         </li>
 713
 714         <li class="item" id="I5.i3">
 715
 716   <div class="para" id="I5.i3.p1">
 717     <p class="p">Search the internet using a search engine such as Google.</p>
 718   </div>
 719
 720         </li>
 721
 722         <li class="item" id="I5.i4">
 723
 724   <div class="para" id="I5.i4.p1">
 725     <p class="p">Post to the GROMACS users emailing list <span style="" class="text typewriter">gmx-users</span>
 726 for assistance. Be sure to give a full description of what you have
 727 done and why you think it didn't work. Give details about the system
 728 on which you are installing. Copy and paste your command line and as
 729 much of the output as you think might be relevant - certainly from
 730 the first indication of a problem. Describe the machine and
 731 operating system you are running on. People who might volunteer to
 732 help you do not have time to ask you interactive detailed follow-up
 733 questions, so you will get an answer faster if you provide as much
 734 information as you think could possibly help.</p>
 735   </div>
 736
 737         </li>
 738
 739     </ol>
 740   </div>
 741
 742     </div>
 743
 744     </div>
 745
 746     <div class="section" id="S4">
 747     <h2 class="title section-title"> 4. Special instructions for some platforms</h2>
 748     <div class="subsection" id="S4.SS1">
 749     <h3 class="title subsection-title"> 4.1. Building on Windows</h3>
 750   <div class="para" id="S4.SS1.p1">
 751     <p class="p">Building on Cygwin/MinGW/etc. works just like Unix. Please see the
 752 instructions above.</p>
 753   </div>
 754
 755   <div class="para" id="S4.SS1.p2">
 756     <p class="p">Building on Windows using native compilers is rather similar to
 757 building on Unix, so please start by reading the above. Then, download
 758 and unpack the GROMACS source archive. The UNIX-standard
 759 <span style="" class="text typewriter">.tar.gz</span> format can be managed on Windows, but you may prefer
 760 to browse <a href="ftp://ftp.gromacs.org/pub/gromacs" title="" class="ref url"><span style="" class="text typewriter">ftp://ftp.gromacs.org/pub/gromacs</span></a> to obtain a
 761 <span style="" class="text typewriter">.zip</span> format file, which doesn't need any external tools to
 762 unzip on recent Windows systems. Make a folder in which to do the
 763 out-of-source build of GROMACS. For example, make it within the
 764 folder unpacked from the source archive, and call it “build-cmake”.
 765 </p>
 766   </div>
 767
 768   <div class="para" id="S4.SS1.p3">
 769     <p class="p">Next, you need to open a command shell. If you do this from within
 770 your IDE (e.g. Microsoft Visual Studio), it will configure the
 771 environment for you. If you use a normal Windows command shell, then
 772 you will need to either set up the environment to find your compilers
 773 and libraries yourself, or run the <span style="" class="text typewriter">vcvarsall.bat</span> batch script
 774 provided by MSVC (just like sourcing a bash script under
 775 Unix). Presumably Intel's IDE has a similar functionality.</p>
 776   </div>
 777
 778   <div class="para" id="S4.SS1.p4">
 779     <p class="p">Within that command shell, change to the folder you created above. Run
 780 <code class="verbatim">cmake ..</code>, where the folder you point CMake towards is the
 781 folder created by the GROMACS installer. Resolve issues as
 782 above. You will probably make your life easier and faster by using the
 783 new facility to download and install FFTW automatically. After the
 784 initial run of <code class="verbatim">cmake</code>, you may wish to use <code class="verbatim">cmake</code>,
 785 <code class="verbatim">ccmake</code> or the GUI version of CMake until your configuration
 786 is complete.</p>
 787   </div>
 788
 789   <div class="para" id="S4.SS1.p5">
 790     <p class="p">To compile GROMACS, you then use <code class="verbatim">cmake --build .</code> so the
 791 right tools get used.</p>
 792   </div>
 793
 794     </div>
 795
 796     <div class="subsection" id="S4.SS2">
 797     <h3 class="title subsection-title"> 4.2. Building on Cray</h3>
 798   <div class="para" id="S4.SS2.p1">
 799     <p class="p">Probably you need to build static libraries only? Volunteer needed.</p>
 800   </div>
 801
 802     </div>
 803
 804     <div class="subsection" id="S4.SS3">
 805     <h3 class="title subsection-title"> 4.3. Building on BlueGene</h3>
 806     <div class="subsubsection" id="S4.SS3.SSS1">
 807     <h4 class="title subsubsection-title"> 4.3.1. BlueGene/P</h4>
 808   <div class="para" id="S4.SS3.SSS1.p1">
 809     <p class="p">Mark to write later. There is currently no native acceleration on this
 810 platform, but the default plain C kernels will work.</p>
 811   </div>
 812
 813     </div>
 814
 815     <div class="subsubsection" id="S4.SS3.SSS2">
 816     <h4 class="title subsubsection-title"> 4.3.2. BlueGene/Q</h4>
 817   <div class="para" id="S4.SS3.SSS2.p1">
 818     <p class="p">Mark to write later. There is currently no native acceleration on this
 819 platform, but the default plain C kernels will work.</p>
 820   </div>
 821
 822     </div>
 823
 824     </div>
 825
 826     </div>
 827
 828     <div class="section" id="S5">
 829     <h2 class="title section-title"> 5. Tested platforms</h2>
 830   <div class="para" id="S5.p1">
 831     <p class="p">While it is our best belief that GROMACS will build and run pretty
 832 much everywhere, it's important that we tell you where we really know
 833 it works because we've tested it. We do test on Linux, Windows, and
 834 Mac with a range of compilers and libraries for a range of our
 835 configuration options. Every commit in our <span style="" class="text typewriter">git</span> source code
 836 repository is tested on … We test irregularly on…</p>
 837   </div>
 838
 839   <div class="para" id="S5.p2">
 840     <p class="p">Contributions to this section are welcome.</p>
 841   </div>
 842
 843   <div class="para" id="S5.p3">
 844     <p class="p">Later we might set up the ability for users to contribute test results
 845 to Jenkins.
 846 </p>
 847   </div>
 848
 849     </div>
 850
 851     <div class="section" id="S6">
 852     <h2 class="title section-title"> 6. Other issues</h2>
 853   <div class="para" id="S6.p1">
 854     <p class="p">The GROMACS utility programs often write data files in formats
 855 suitable for the Grace plotting tool, but it is straightforward to
 856 use these files in other plotting programs, too.</p>
 857   </div>
 858
 859     </div>
 860
 861     </div>
 862
 863         </div>
 864       </div>
 865     </body>
 866     </html>