--- /dev/null
+\documentclass{article}[12pt,a4paper,twoside]
+\usepackage{hyperref}
+% haven't made these work with LaTeXML yet...
+%\usepackage[strings]{underscore}
+%\usepackage[english]{babel}
+
+\title{GROMACS installation guide}
+
+% macros to keep style uniform
+\newcommand{\gromacs}{GROMACS}
+\newcommand{\nvidia}{NVIDIA}
+\newcommand{\cuda}{CUDA}
+\newcommand{\fftw}{FFTW}
+\newcommand{\mkl}{MKL}
+\newcommand{\mpi}{MPI}
+\newcommand{\threadmpi}{ThreadMPI}
+\newcommand{\openmpi}{OpenMPI}
+\newcommand{\openmp}{OpenMP}
+\newcommand{\openmm}{OpenMM}
+\newcommand{\lammpi}{LAM/MPI}
+\newcommand{\mpich}{MPICH}
+\newcommand{\cmake}{CMake}
+\newcommand{\sse}{SSE}
+\newcommand{\ssetwo}{SSE2}
+\newcommand{\avx}{AVX}
+\newcommand{\fft}{FFT}
+\newcommand{\blas}{BLAS}
+\newcommand{\lapack}{LAPACK}
+\newcommand{\vmd}{VMD}
+\newcommand{\pymol}{PyMOL}
+\newcommand{\grace}{Grace}
+%\newcommand{\}{}
+%\newcommand{\}{}
+
+% later, make CMake keep this version current for us
+\newcommand{\fftwversion}{3.3.2}
+\newcommand{\cmakeversion}{2.8.0}
+\newcommand{\cudaversion}{3.2}
+
+\begin{document}
+\section{Building GROMACS}
+These instructions pertain to building \gromacs{} 4.6 beta releases
+and newer. For installations instructions for old \gromacs{} versions,
+see here
+\url{http://www.gromacs.org/Documentation/Installation_Instructions_4.5}.
+
+\section{Prerequisites}
+
+\subsection{Platform}
+
+\gromacs{} can be compiled for any distribution of Linux, Mac OS X,
+Windows (native, Cygwin or MinGW), BlueGene, Cray and probably others.
+Technically, it can be compiled on any platform with an ANSI C
+compiler and supporting libraries, such as the GNU C library. It can
+even compile on an iPhone! Later, there will be a detailed list of
+hardware, platform and compilers upon which we do build and regression
+testing.
+
+\subsection{Compiler}
+
+\gromacs{} requires an ANSI C compiler that complies with the C89
+standard. For best performance, the \gromacs{} team strongly
+recommends you get the most recent version of your preferred compiler
+for your platform (e.g. GCC 4.7 or Intel 12.0 or newer on x86
+hardware). There is a large amount of \gromacs{} code introduced in
+version 4.6 that depends on effective compiler optimization to get
+high performance - the old assembly-language routines have all
+gone. For other platforms, use the vendor's compiler, and check for
+specialized information below.
+
+\subsubsection{Running in parallel}
+
+\gromacs{} can run in parallel on multiple cores of a single
+workstation using its built-in \threadmpi. No user action is required
+in order to enable this.
+
+If you wish to use the excellent new native GPU support in \gromacs,
+\nvidia{}'s \cuda{}
+\url{http://www.nvidia.com/object/cuda_home_new.html} version
+\cudaversion{} software development kit is required, and the latest
+version is encouraged. \nvidia{} GPUs with at least \nvidia{} compute
+capability 2.0 are required, e.g. Fermi or Kepler cards.
+
+The GPU support from \gromacs{} version 4.5 using \openmm{}
+\url{https://simtk.org/home/openmm} is still available, also requires
+\cuda{}, and remains the only hardware-based acceleration available
+for implicit solvent simulations in \gromacs{}. This parallelization
+path may not be maintained in the future.
+
+If you wish to run in parallel on multiple machines across a network,
+you will need to have
+\begin{itemize}
+\item an \mpi{} library installed that supports the \mpi{} 1.3
+ standard, and
+\item wrapper compilers that will compile code using that library.
+\end{itemize}
+The \gromacs{} team recommends \openmpi{}
+\url{http://www.open-mpi.org/} version 1.4.1 (or higher), \mpich{}
+\url{http://www.mpich.org/} version 1.4.1 (or higher), or your
+hardware vendor's \mpi{} installation. The most recent version of
+either of this is likely to be the best. \lammpi{}
+\url{http://www.lam-mpi.org/} may work, but since it has been
+deprecated for years, it is not supported.
+
+In some cases, \openmp{} parallelism is an advantage for \gromacs{},
+but support for this is generally built into your compiler and you
+need to make no advance preparation for this. The performance gain you
+might achieve can vary with the compiler.
+
+It is important to examine how you will use \gromacs{} and upon what
+hardware and with what compilers in deciding which parallelization
+paths to make available. Testing the performance of different options
+is unfortunately mandatory. The days of being able to just build and
+run '\verb+mdrun+' and get decent performance by default on your
+hardware are long gone. \gromacs{} will always run correctly, and does
+a decent job of trying to maximize your performance, but if you want
+to approach close to the optimum, you will need to do some work for
+it!
+
+\subsection{CMake}
+
+From version 4.6, \gromacs{} has moved to use the build system
+\cmake{}. The previous build system that used \texttt{configure} from
+the GNU autotools package has been removed permanently. \cmake{}
+permits the \gromacs{} team to support a very wide range of hardware,
+compilers and build configurations while continuing to provide the
+portability, robustness and performance for which \gromacs{} is known.
+
+\gromacs{} requires \cmake{} version \cmakeversion{} or higher. Lower
+versions will not work. You can check whether \cmake{} is installed,
+and what version it is, with \texttt{cmake --version}. If you need to
+install \cmake{}, then first check whether your platform's package
+management system provides a suitable version, or visit
+\url{http://www.cmake.org/cmake/help/install.html} for pre-compiled
+binaries, source code and installation instructions. The \gromacs{}
+team recommends you install the most recent version of \cmake{} you
+can.
+
+\subsection{Fast Fourier Transform library}
+
+Many simulations in \gromacs{} make extensive use of Fourier transforms,
+and a software library to perform these is always required. We
+recommend \fftw{} \url{http://www.fftw.org/} (version 3 or higher
+only) or Intel's \mkl{}
+\url{http://software.intel.com/en-us/intel-mkl}.
+
+\subsubsection{\fftw{}}
+
+\fftw{} is likely to be available for your platform via its package
+management system, but there can be compatibility and significant
+performance issues associated with these packages. In particular,
+\gromacs{} simulations are normally run in single floating-point
+precision whereas the default \fftw{} package is normally in double
+precision, and good compiler options to use for \fftw{} when linked to
+\gromacs{} may not have been used. Accordingly, the \gromacs{} team
+recommends either
+\begin{itemize}
+\item that you permit the \gromacs{} installation to download and
+ build \fftw{} \fftwversion{} from source automatically
+ for you, or
+\item that you build \fftw{} from the source code.
+\end{itemize}
+
+If you build \fftw{} from source yourself, get the most recent version
+and follow its installation guide
+(e.g. \url{http://www.fftw.org/fftw3_doc/Installation-and-Customization.html}). Choose
+the precision (i.e. single or float vs double) to match what you will
+later require for \gromacs{}. There is no need to compile with
+threading or \mpi{} support, but it does no harm. On x86 hardware,
+compile \emph{only} with \texttt{--enable-sse2} (regardless of
+precision) even if your processors can take advantage of \avx{}
+extensions to \sse{}. The way \gromacs{} uses Fourier transforms
+cannot take advantage of this feature in \fftw{} because of memory
+system performance limitations, it can degrade performance by around
+20\%, and there is no way for \gromacs{} to require the use of the
+\ssetwo{} at run time if \avx{} support has been compiled into \fftw{}.
+
+\subsubsection{\mkl{}}
+
+Using \mkl{} requires a set of linker flags that \gromacs{} is not
+able to detect for you, so setting up optimal linking is tricky at the
+moment. Need better documentation later.
+
+\subsection{Optional build components}
+
+\begin{itemize}
+\item A hardware-optimized \blas{} or \lapack{} library is useful for
+ some of the \gromacs{} utilities, but is not needed for running
+ simulations.
+\item The built-in \gromacs{} trajectory viewer \texttt{ngmx} requires
+ X11 and Motif/Lesstif libraries and header files. Generally, the
+ \gromacs{} team recommends you use third-party software for
+ visualization, such as \vmd{}
+ \url{http://www.ks.uiuc.edu/Research/vmd/} or \pymol{}
+ \url{http://www.pymol.org/}.
+\end{itemize}
+
+\section{Doing a build of \gromacs}
+
+This section will cover a general build of \gromacs{} with \cmake{},
+but it is not an exhaustive discussion of how to use \cmake{}. There
+are many resources available on the web, which we suggest you search
+for when you encounter problems not covered here. The material below
+applies specifically to builds on Unix-like systems, including Linux,
+Mac OS X, MinGW and Cygwin. For other platforms, see the specialist
+instructions below.
+
+\subsection{Configuring with \cmake{}}
+
+\cmake{} will run many tests on your system and do its best to work
+out how to build \gromacs{} for you. If you are building \gromacs{} on
+hardware that is identical to that where you will run \texttt{mdrun},
+then you can be sure that the defaults will be pretty good. Howver, if
+you want to control aspects of the build, there's plenty of things you
+can set, too.
+
+The best way to use \cmake{} to configure \gromacs{} is to do an
+``out-of-source'' build, by making another directory from which you
+will run \cmake{}. This can be a subdirectory or not, it doesn't
+matter. It also means you can never corrupt your source code by trying
+to build it! So, the only required argument on the \cmake{} command
+line is the name of the directory containing the
+\texttt{CMakeLists.txt} file of the code you want to build. For
+example, download the source tarball and use
+% TODO: keep up to date as we approach real releases!
+\begin{verbatim}
+$ tar xfz gromacs-4.6-beta1-src.tgz
+$ cd gromacs-4.6-beta1
+$ mkdir build-cmake
+$ cd build-cmake
+$ cmake ..
+\end{verbatim}
+
+You will see \texttt{cmake} report the results of a large number of
+tests on your system made by \cmake{} and by \gromacs{}. These are
+written to the \cmake{} cache, kept in \texttt{CMakeCache.txt}. You
+can edit this file by hand, but this is not recommended because it is
+easy to reach an inconsistent state. You should not attempt to move or
+copy this file to do another build, because the paths are hard-coded
+within it. If you mess things up, just delete this file and start
+again with '\verb+cmake+'.
+
+If there's a serious problem detected at this stage, then you will see
+a fatal error and some suggestions for how to overcome it. If you're
+not sure how to deal with that, please start by searching on the web
+(most computer problems already have known solutions!) and then
+consult the \texttt{gmx-users} mailing list. There are also
+informational warnings that you might like to take on board or
+not. Piping the output of \texttt{cmake} through \texttt{less} or
+\texttt{tee} can be useful, too.
+
+\cmake{} works in an iterative fashion, re-running each time a setting
+is changed to try to make sure other things are consistent. Once
+things seem consistent, the iterations stop. Once \texttt{cmake}
+returns, you can see all the settings that were chosen and information
+about them by using
+\begin{verbatim}
+$ ccmake ..
+\end{verbatim}
+Check out \url{http://www.cmake.org/cmake/help/runningcmake.html} for
+general advice on what you are seeing and how to navigate and change
+things. The settings you might normally want to change are already
+presented. If you make any changes, then \texttt{ccmake} will notice
+that and require that you re-configure (using '\verb+c+'), so that it
+gets a chance to make changes that depend on yours and perform more
+checking. This might require several configuration stages when you are
+using \texttt{ccmake} - when you are using \texttt{cmake} the
+iteration is done behind the scenes.
+
+A key thing to consider here is the setting of
+\texttt{GMX\_INSTALL\_PREFIX}. You will need to be able to write to this
+directory in order to install \gromacs{} later, and if you change your
+mind later, changing it in the cache triggers a full re-build,
+unfortunately. So if you do not have super-user privileges on your
+machine, then you will need to choose a sensible location within your
+home directory for your \gromacs{} installation.
+
+When \texttt{cmake} or \texttt{ccmake} have completed iterating, the
+cache is stable and a build tree can be generated, with '\verb+g+' in
+\texttt{ccmake} or automatically with \texttt{cmake}.
+
+\subsection{Using CMake command-line options}
+Once you become comfortable with setting and changing options, you
+may know in advance how you will configure GROMACS. If so, you can
+speed things up by invoking \texttt{cmake} with a command like:
+\begin{verbatim}
+$ cmake .. -DGMX_GPU=ON -DGMX_MPI=ON -DGMX_INSTALL_PREFIX=/home/marydoe/programs
+\end{verbatim}
+to build with GPUs, MPI and install in a custom location. You can even
+save that in a shell script to make it even easier next time. You can
+also do this kind of thing with \texttt{ccmake}, but you should avoid
+this, because the options set with '\verb+-D+' will not be able to be
+changed interactively in that run of \texttt{ccmake}.
+
+\subsection{CMake advanced options}
+The options that can be seen with \texttt{ccmake} are ones that we
+think a reasonable number of users might want to consider
+changing. There are a lot more options available, which you can see by
+toggling the advanced mode in \texttt{ccmake} on and off with
+'\verb+t+'. Even there, most of the variables that you might want to
+change have a '\verb+CMAKE_+' or '\verb+GMX_+' prefix.
+
+\subsection{Helping CMake find the right libraries/headers/programs}
+
+If libraries are installed in non-default locations their location can
+be specified using the following environment variables:
+\begin{itemize}
+\item \texttt{CMAKE\_INCLUDE\_PATH} for header files
+\item \texttt{CMAKE\_LIBRARY\_PATH} for libraries
+\item \texttt{CMAKE\_PREFIX\_PATH} for header, libraries and binaries
+ (e.g. '\verb+/usr/local+').
+\end{itemize}
+The respective '\verb+include+', '\verb+lib+', or '\verb+bin+' is
+appended to the path. For each of these variables, a list of paths can
+be specified (on Unix seperated with ":"). Note that these are
+enviroment variables (and not \cmake{} command-line arguments) and in
+a '\verb+bash+' shell are used like:
+\begin{verbatim}
+$ CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
+\end{verbatim}
+
+The \texttt{CC} and \texttt{CXX} environment variables are also useful
+for indicating to \cmake{} which compilers to use, which can be very
+important for maximising \gromacs{} performance. Similarly,
+\texttt{CFLAGS}/\texttt{CXXFLAGS} can be used to pass compiler
+options, but note that these will be appended to those set by
+\gromacs{} for your build platform and build type. You can customize
+some of this with advanced options such as \texttt{CMAKE\_C\_FLAGS}
+and its relatives.
+
+See also: \url{http://cmake.org/Wiki/CMake_Useful_Variables#Environment_Variables}
+
+\subsection{CMake advice during the GROMACS 4.6 beta phase}
+We'd like users to have the ability to change any setting and still
+have the \cmake{} cache stable; ie. not have things you set
+mysteriously change, or (worse) the whole thing breaks. We're not
+there yet. If you know in advance you will want to use a particular
+setting, set that on the initial \texttt{cmake} command line. If you
+have to change compilers, do that there, or immediately afterwards in
+\texttt{ccmake}. Gross changes like GPU or shared libraries on/off are
+more likely to work if you do them on the initial command line,
+because that's how we've been doing it while developing and
+testing. If you do make a mess of things, there's a great thing about
+an out-of-source build - you can just do '\verb+rm -rf *+' and start
+again. Easy!
+
+We are interested in learning how you managed to break things. If you
+can reproducibly reach a state where \cmake{} can't proceed, or
+subsequent compilation/linking/running fails, then we need to know so
+we can fix it!
+
+\subsection{Native GPU acceleration}
+If you have the \cuda{} SDK installed, you can use \cmake{}
+with:
+\begin{verbatim}
+cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
+\end{verbatim}
+(or whichever path has your installation). Note that this will require
+a working C++ compiler, and in some cases you might need to handle
+this manually, e.g. with the advanced option
+\texttt{CUDA\_NVCC\_HOST\_COMPILER}.
+
+More documentation needed here - particular discussion of fiddly
+details on Windows, Linux and Mac required. Not all compilers on all
+systems can be made to work.
+
+\subsection{Static linking}
+Dynamic linking of the \gromacs{} executables will lead to a smaller
+disk footprint when installed, and so is the default. However, on some
+hardware or under some circumstances you might need to do static
+linking. To link \gromacs{} binaries statically against the internal
+\gromacs{} libraries, set \texttt{BUILD\_SHARED\_LIBS=OFF}. To link
+statically against external libraries as well, the
+\texttt{GMX\_PREFER\_STATIC\_LIBS=ON} option can be used. Note, that
+in general \cmake{} picks up whatever is available, so this option
+only instructs \cmake{} to prefer static libraries when both static
+and shared are available. If no static version of an external library
+is available, even when the aforementioned option is ON, the shared
+library will be used. Also note, that the resulting binaries will
+still be dynamically linked against system libraries if that is all
+that is available.
+
+\subsection{Suffixes for binaries and libraries}
+It is sometimes convenient to have different versions of the same
+\gromacs{} libraries installed. The most common use cases have been
+single and double precision, and with and without \mpi{}. By default,
+\gromacs{} will suffix binaries and libraries for such builds with
+'\verb+_d+' for double precision and/or '\verb+_mpi+' for \mpi{} (and
+nothing otherwise). This can be controlled manually with
+\texttt{GMX\_DEFAULT\_SUFFIX}, \texttt{GMX\_BINARY\_SUFFIX} and
+\texttt{GMX\_LIBRARY\_SUFFIX}.
+
+\subsection{Building \gromacs{}}
+
+Once you have a stable cache, you can build \gromacs{}. If you're not
+sure the cache is stable, you can re-run \verb+cmake ..+ or
+\verb+ccmake ..+' to see. Then you can run \texttt{make} to start the
+compilation. Before actual compilation starts, \texttt{make} checks
+that the cache is stable, so if it isn't you will see \cmake{} run
+again.
+
+So long as any changes you've made to the configuration are sensible,
+it is expected that the \texttt{make} procedure will always complete
+successfully. The tests \gromacs{} makes on the settings you choose
+are pretty extensive, but there are probably a few cases we haven't
+thought of yet. Search the web first for solutions to problems,
+but if you need help, ask on \texttt{gmx-users}, being sure to provide
+as much information as possible about what you did, the system you are
+building on, and what went wrong.
+
+If you have a multi-core or multi-CPU machine with \texttt{N}
+processors, then using
+\begin{verbatim}
+$ make -j N
+\end{verbatim}
+will generally speed things up by quite a bit.
+
+\subsection{Installing \gromacs{}}
+
+Finally, \texttt{make install} will install \gromacs{} in the
+directory given in \texttt{GMX\_INSTALL\_PREFIX}. If this is an system
+directory, then you will need permission to write there, and you
+should use super-user privileges only for \texttt{make install} and
+not the whole procedure.
+
+\subsection{Getting access to \gromacs{} after installation}
+
+\gromacs{} installs the script \texttt{GMXRC} in the \texttt{bin}
+subdirectory of the installation directory
+(e.g. \texttt{/usr/local/gromacs/bin/GMXRC}), which you should source
+from your shell:
+\begin{verbatim}
+$ source your-installation-prefix-here/bin/GMXRC
+\end{verbatim}
+
+It will detect what kind of shell you are running and
+set up your environment for using \gromacs{}. You may wish to arrange
+for your login scripts to do this automatically; please search the web
+for instructions on how to do this for your shell.
+
+\subsection{Testing \gromacs{} for correctness}
+TODO install and use regression set
+
+\subsection{Testing \gromacs{} for performance}
+TODO benchmarks
+
+\subsection{Having difficulty?}
+
+You're not alone, this can be a complex task. If you encounter a
+problem with installing \gromacs{}, then there are a number of
+locations where you can find assistance. It is recommended that you
+follow these steps to find the solution:
+
+\begin{enumerate}
+\item Read the installation instructions again, taking note that you
+ have followed each and every step correctly.
+\item Search the \gromacs{} website and users emailing list for
+ information on the error.
+\item Search the internet using a search engine such as Google.
+\item Post to the \gromacs{} users emailing list \texttt{gmx-users}
+ for assistance. Be sure to give a full description of what you have
+ done and why you think it didn't work. Give details about the system
+ on which you are installing. Copy and paste your command line and as
+ much of the output as you think might be relevant - certainly from
+ the first indication of a problem. Describe the machine and
+ operating system you are running on. People who might volunteer to
+ help you do not have time to ask you interactive detailed follow-up
+ questions, so you will get an answer faster if you provide as much
+ information as you think could possibly help.
+\end{enumerate}
+
+\section{Special instructions for some platforms}
+
+\subsection{Building on Windows}
+
+Need a volunteer to write this section.
+
+Cygwin works just like Unix.
+
+\subsection{Building on Cray}
+
+Probably you need to build static libraries only? Volunteer needed.
+
+\subsection{Building on BlueGene}
+
+\subsubsection{BlueGene/P}
+
+Mark to write later. There is currently no native acceleration on this
+platform, but the default kernels will work.
+
+\subsubsection{BlueGene/Q}
+
+Mark to write later. There is currently no native acceleration on this
+platform, but the default kernels will work.
+
+\section{Tested platforms}
+
+While it is our best belief that \gromacs{} will build and run pretty
+much everywhere, it's important that we tell you where we really know
+it works because we've tested it. We do test on Linux, Windows, and
+Mac with a range of compilers and libraries for a range of our
+configuration options. Every commit in our \texttt{git} source code
+repository is tested on ... We test irregularly on...
+
+Contributions to this section are welcome.
+
+Later we might set up the ability for users to contribute test results
+to Jenkins.
+
+\section{Other issues}
+
+The \gromacs{} utility programs often write data files in formats
+suitable for the \grace{} plotting tool, but it is straightforward to
+use these files in other plotting programs, too.
+
+\end{document}
--- /dev/null
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3c.org/TR/MathML2/dtd/xhtml-math11-f.dtd">
+<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">
+ <head>
+ <title>GROMACS installation guide</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <link rel="stylesheet" type="text/css" href="core.css"/>
+ </head>
+ <body>
+ <div class="navbar">
+ <ul class="toc">
+ <li class="tocentry"><span class="ref toc here">GROMACS installation guide</span>
+ <ul class="toc">
+ <li class="tocentry"><a href="#S1" title="1. Building GROMACS in GROMACS installation guide" class="ref toc">1 Building GROMACS</a></li>
+ <li class="tocentry"><a href="#S2" title="2. Prerequisites in GROMACS installation guide" class="ref toc">2 Prerequisites</a>
+ <ul class="toc">
+ <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>
+ <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>
+ <ul class="toc">
+ <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>
+ </ul></li>
+ <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>
+ <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>
+ <ul class="toc">
+ <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>
+ <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>
+ </ul></li>
+ <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>
+ </ul></li>
+ <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>
+ <ul class="toc">
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ </ul></li>
+ <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>
+ <ul class="toc">
+ <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>
+ <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>
+ <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>
+ <ul class="toc">
+ <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>
+ <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>
+ </ul></li>
+ </ul></li>
+ <li class="tocentry"><a href="#S5" title="5. Tested platforms in GROMACS installation guide" class="ref toc">5 Tested platforms</a></li>
+ <li class="tocentry"><a href="#S6" title="6. Other issues in GROMACS installation guide" class="ref toc">6 Other issues</a></li>
+ </ul></li>
+ </ul>
+ </div>
+ <div class="main">
+ <div class="content">
+ <div class="document">
+ <h1 class="title document-title">GROMACS installation guide</h1>
+ <div class="section" id="S1">
+ <h2 class="title section-title"> 1. Building GROMACS</h2>
+ <div class="para" id="S1.p1">
+ <p class="p">These instructions pertain to building GROMACS 4.6 beta releases
+and newer. For installations instructions for old GROMACSversions,
+see here
+<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>
+ </div>
+
+ </div>
+
+ <div class="section" id="S2">
+ <h2 class="title section-title"> 2. Prerequisites</h2>
+ <div class="subsection" id="S2.SS1">
+ <h3 class="title subsection-title"> 2.1. Platform</h3>
+ <div class="para" id="S2.SS1.p1">
+ <p class="p">GROMACS can be compiled for any distribution of Linux, Mac OS X,
+Windows (native, Cygwin or MinGW), BlueGene, Cray and probably others.
+Technically, it can be compiled on any platform with an ANSI C
+compiler and supporting libraries, such as the GNU C library. It can
+even compile on an iPhone! Later, there will be a detailed list of
+hardware, platform and compilers upon which we do build and regression
+testing.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S2.SS2">
+ <h3 class="title subsection-title"> 2.2. Compiler</h3>
+ <div class="para" id="S2.SS2.p1">
+ <p class="p">GROMACS requires an ANSI C compiler that complies with the C89
+standard. For best performance, the GROMACS team strongly
+recommends you get the most recent version of your preferred compiler
+for your platform (e.g. GCC 4.7 or Intel 12.0 or newer on x86
+hardware). There is a large amount of GROMACS code introduced in
+version 4.6 that depends on effective compiler optimization to get
+high performance - the old assembly-language routines have all
+gone. For other platforms, use the vendor's compiler, and check for
+specialized information below.</p>
+ </div>
+
+ <div class="subsubsection" id="S2.SS2.SSS1">
+ <h4 class="title subsubsection-title"> 2.2.1. Running in parallel</h4>
+ <div class="para" id="S2.SS2.SSS1.p1">
+ <p class="p">GROMACS can run in parallel on multiple cores of a single
+workstation using its built-in ThreadMPI. No user action is required
+in order to enable this.</p>
+ </div>
+
+ <div class="para" id="S2.SS2.SSS1.p2">
+ <p class="p">If you wish to use the excellent new native GPU support in GROMACS,
+NVIDIA's CUDA
+<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
+3.2 software development kit is required, and the latest
+version is encouraged. NVIDIA GPUs with at least NVIDIA compute
+capability 2.0 are required, e.g. Fermi or Kepler cards.</p>
+ </div>
+
+ <div class="para" id="S2.SS2.SSS1.p3">
+ <p class="p">The GPU support from GROMACS version 4.5 using OpenMM
+<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
+CUDA, and remains the only hardware-based acceleration available
+for implicit solvent simulations in GROMACS. This parallelization
+path may not be maintained in the future.</p>
+ </div>
+
+ <div class="para" id="S2.SS2.SSS1.p4">
+ <p class="p">If you wish to run in parallel on multiple machines across a network,
+you will need to have</p>
+
+ <ul class="itemize" id="I1">
+
+ <li class="item" id="I1.i1">
+
+ <div class="para" id="I1.i1.p1">
+ <p class="p">an MPI library installed that supports the MPI 1.3
+standard, and</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I1.i2">
+
+ <div class="para" id="I1.i2.p1">
+ <p class="p">wrapper compilers that will compile code using that library.</p>
+ </div>
+
+ </li>
+
+ </ul>
+
+ <p class="p">The GROMACS team recommends OpenMPI
+<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
+<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
+hardware vendor's MPI installation. The most recent version of
+either of this is likely to be the best. LAM/MPI
+<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
+deprecated for years, it is not supported.</p>
+ </div>
+
+ <div class="para" id="S2.SS2.SSS1.p5">
+ <p class="p">In some cases, OpenMP parallelism is an advantage for GROMACS,
+but support for this is generally built into your compiler and you
+need to make no advance preparation for this. The performance gain you
+might achieve can vary with the compiler.</p>
+ </div>
+
+ <div class="para" id="S2.SS2.SSS1.p6">
+ <p class="p">It is important to examine how you will use GROMACS and upon what
+hardware and with what compilers in deciding which parallelization
+paths to make available. Testing the performance of different options
+is unfortunately mandatory. The days of being able to just build and
+run '<code class="verbatim">mdrun</code>' and get decent performance by default on your
+hardware are long gone. GROMACS will always run correctly, and does
+a decent job of trying to maximize your performance, but if you want
+to approach close to the optimum, you will need to do some work for
+it!</p>
+ </div>
+
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S2.SS3">
+ <h3 class="title subsection-title"> 2.3. CMake</h3>
+ <div class="para" id="S2.SS3.p1">
+ <p class="p">From version 4.6, GROMACS has moved to use the build system
+CMake. The previous build system that used <span style="" class="text typewriter">configure</span> from
+the GNU autotools package has been removed permanently. CMake
+permits the GROMACS team to support a very wide range of hardware,
+compilers and build configurations while continuing to provide the
+portability, robustness and performance for which GROMACS is known.</p>
+ </div>
+
+ <div class="para" id="S2.SS3.p2">
+ <p class="p">GROMACS requires CMake version 2.8.0 or higher. Lower
+versions will not work. You can check whether CMake is installed,
+and what version it is, with <span style="" class="text typewriter">cmake --version</span>. If you need to
+install CMake, then first check whether your platform's package
+management system provides a suitable version, or visit
+<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
+binaries, source code and installation instructions. The GROMACS
+team recommends you install the most recent version of CMake you
+can.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S2.SS4">
+ <h3 class="title subsection-title"> 2.4. Fast Fourier Transform library</h3>
+ <div class="para" id="S2.SS4.p1">
+ <p class="p">Many simulations in GROMACS make extensive use of Fourier transforms,
+and a software library to perform these is always required. We
+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
+only) or Intel's MKL
+<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>
+ </div>
+
+ <div class="subsubsection" id="S2.SS4.SSS1">
+ <h4 class="title subsubsection-title"> 2.4.1. FFTW</h4>
+ <div class="para" id="S2.SS4.SSS1.p1">
+ <p class="p">FFTW is likely to be available for your platform via its package
+management system, but there can be compatibility and significant
+performance issues associated with these packages. In particular,
+GROMACS simulations are normally run in single floating-point
+precision whereas the default FFTW package is normally in double
+precision, and good compiler options to use for FFTW when linked to
+GROMACS may not have been used. Accordingly, the GROMACS team
+recommends either</p>
+
+ <ul class="itemize" id="I2">
+
+ <li class="item" id="I2.i1">
+
+ <div class="para" id="I2.i1.p1">
+ <p class="p">that you permit the GROMACS installation to download and
+build FFTW 3.3.2 from source automatically
+for you, or</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I2.i2">
+
+ <div class="para" id="I2.i2.p1">
+ <p class="p">that you build FFTW from the source code.</p>
+ </div>
+
+ </li>
+
+ </ul>
+ </div>
+
+ <div class="para" id="S2.SS4.SSS1.p2">
+ <p class="p">If you build FFTW from source yourself, get the most recent version
+and follow its installation guide
+(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
+the precision (i.e. single or float vs double) to match what you will
+later require for GROMACS. There is no need to compile with
+threading or MPI support, but it does no harm. On x86 hardware,
+compile <em class="emph">only</em> with <span style="" class="text typewriter">--enable-sse2</span> (regardless of
+precision) even if your processors can take advantage of AVX
+extensions to SSE. The way GROMACS uses Fourier transforms
+cannot take advantage of this feature in FFTW because of memory
+system performance limitations, it can degrade performance by around
+20%, and there is no way for GROMACS to require the use of the
+SSE2 at run time if AVX support has been compiled into FFTW.</p>
+ </div>
+
+ </div>
+
+ <div class="subsubsection" id="S2.SS4.SSS2">
+ <h4 class="title subsubsection-title"> 2.4.2. MKL</h4>
+ <div class="para" id="S2.SS4.SSS2.p1">
+ <p class="p">Using MKL requires a set of linker flags that GROMACS is not
+able to detect for you, so setting up optimal linking is tricky at the
+moment. Need better documentation later.</p>
+ </div>
+
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S2.SS5">
+ <h3 class="title subsection-title"> 2.5. Optional build components</h3>
+ <div class="para" id="S2.SS5.p1">
+ <ul class="itemize" id="I3">
+
+ <li class="item" id="I3.i1">
+
+ <div class="para" id="I3.i1.p1">
+ <p class="p">A hardware-optimized BLAS or LAPACK library is useful for
+some of the GROMACS utilities, but is not needed for running
+simulations.</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I3.i2">
+
+ <div class="para" id="I3.i2.p1">
+ <p class="p">The built-in GROMACS trajectory viewer <span style="" class="text typewriter">ngmx</span> requires
+X11 and Motif/Lesstif libraries and header files. Generally, the
+GROMACS team recommends you use third-party software for
+visualization, such as VMD
+<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
+<a href="http://www.pymol.org/" title="" class="ref url"><span style="" class="text typewriter">http://www.pymol.org/</span></a>.</p>
+ </div>
+
+ </li>
+
+ </ul>
+ </div>
+
+ </div>
+
+ </div>
+
+ <div class="section" id="S3">
+ <h2 class="title section-title"> 3. Doing a build of GROMACS</h2>
+ <div class="para" id="S3.p1">
+ <p class="p">This section will cover a general build of GROMACS with CMake,
+but it is not an exhaustive discussion of how to use CMake. There
+are many resources available on the web, which we suggest you search
+for when you encounter problems not covered here. The material below
+applies specifically to builds on Unix-like systems, including Linux,
+Mac OS X, MinGW and Cygwin. For other platforms, see the specialist
+instructions below.</p>
+ </div>
+
+ <div class="subsection" id="S3.SS1">
+ <h3 class="title subsection-title"> 3.1. Configuring with CMake</h3>
+ <div class="para" id="S3.SS1.p1">
+ <p class="p">CMake will run many tests on your system and do its best to work
+out how to build GROMACS for you. If you are building GROMACS on
+hardware that is identical to that where you will run <span style="" class="text typewriter">mdrun</span>,
+then you can be sure that the defaults will be pretty good. Howver, if
+you want to control aspects of the build, there's plenty of things you
+can set, too.</p>
+ </div>
+
+ <div class="para" id="S3.SS1.p2">
+ <p class="p">The best way to use CMake to configure GROMACS is to do an
+“out-of-source” build, by making another directory from which you
+will run CMake. This can be a subdirectory or not, it doesn't
+matter. It also means you can never corrupt your source code by trying
+to build it! So, the only required argument on the CMake command
+line is the name of the directory containing the
+<span style="" class="text typewriter">CMakeLists.txt</span> file of the code you want to build. For
+example, download the source tarball and use
+</p>
+ <pre class="verbatim">
+$ tar xfz gromacs-4.6-beta1-src.tgz
+$ cd gromacs-4.6-beta1
+$ mkdir build-cmake
+$ cd build-cmake
+$ cmake ..
+</pre></div>
+
+ <div class="para" id="S3.SS1.p3">
+ <p class="p">You will see <span style="" class="text typewriter">cmake</span> report the results of a large number of
+tests on your system made by CMake and by GROMACS. These are
+written to the CMake cache, kept in <span style="" class="text typewriter">CMakeCache.txt</span>. You
+can edit this file by hand, but this is not recommended because it is
+easy to reach an inconsistent state. You should not attempt to move or
+copy this file to do another build, because the paths are hard-coded
+within it. If you mess things up, just delete this file and start
+again with '<code class="verbatim">cmake</code>'.</p>
+ </div>
+
+ <div class="para" id="S3.SS1.p4">
+ <p class="p">If there's a serious problem detected at this stage, then you will see
+a fatal error and some suggestions for how to overcome it. If you're
+not sure how to deal with that, please start by searching on the web
+(most computer problems already have known solutions!) and then
+consult the <span style="" class="text typewriter">gmx-users</span> mailing list. There are also
+informational warnings that you might like to take on board or
+not. Piping the output of <span style="" class="text typewriter">cmake</span> through <span style="" class="text typewriter">less</span> or
+<span style="" class="text typewriter">tee</span> can be useful, too.</p>
+ </div>
+
+ <div class="para" id="S3.SS1.p5">
+ <p class="p">CMake works in an iterative fashion, re-running each time a setting
+is changed to try to make sure other things are consistent. Once
+things seem consistent, the iterations stop. Once <span style="" class="text typewriter">cmake</span>
+returns, you can see all the settings that were chosen and information
+about them by using</p>
+ <pre class="verbatim">
+$ ccmake ..
+</pre>
+ <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
+general advice on what you are seeing and how to navigate and change
+things. The settings you might normally want to change are already
+presented. If you make any changes, then <span style="" class="text typewriter">ccmake</span> will notice
+that and require that you re-configure (using '<code class="verbatim">c</code>'), so that it
+gets a chance to make changes that depend on yours and perform more
+checking. This might require several configuration stages when you are
+using <span style="" class="text typewriter">ccmake</span> - when you are using <span style="" class="text typewriter">cmake</span> the
+iteration is done behind the scenes.</p>
+ </div>
+
+ <div class="para" id="S3.SS1.p6">
+ <p class="p">A key thing to consider here is the setting of
+<span style="" class="text typewriter">GMX_INSTALL_PREFIX</span>. You will need to be able to write to this
+directory in order to install GROMACS later, and if you change your
+mind later, changing it in the cache triggers a full re-build,
+unfortunately. So if you do not have super-user privileges on your
+machine, then you will need to choose a sensible location within your
+home directory for your GROMACS installation.</p>
+ </div>
+
+ <div class="para" id="S3.SS1.p7">
+ <p class="p">When <span style="" class="text typewriter">cmake</span> or <span style="" class="text typewriter">ccmake</span> have completed iterating, the
+cache is stable and a build tree can be generated, with '<code class="verbatim">g</code>' in
+<span style="" class="text typewriter">ccmake</span> or automatically with <span style="" class="text typewriter">cmake</span>.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS2">
+ <h3 class="title subsection-title"> 3.2. Using CMake command-line options</h3>
+ <div class="para" id="S3.SS2.p1">
+ <p class="p">Once you become comfortable with setting and changing options, you
+may know in advance how you will configure GROMACS. If so, you can
+speed things up by invoking <span style="" class="text typewriter">cmake</span> with a command like:</p>
+ <pre class="verbatim">
+$ cmake .. -DGMX_GPU=ON -DGMX_MPI=ON -DGMX_INSTALL_PREFIX=/home/marydoe/programs
+</pre>
+ <p class="p">to build with GPUs, MPI and install in a custom location. You can even
+save that in a shell script to make it even easier next time. You can
+also do this kind of thing with <span style="" class="text typewriter">ccmake</span>, but you should avoid
+this, because the options set with '<code class="verbatim">-D</code>' will not be able to be
+changed interactively in that run of <span style="" class="text typewriter">ccmake</span>.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS3">
+ <h3 class="title subsection-title"> 3.3. CMake advanced options</h3>
+ <div class="para" id="S3.SS3.p1">
+ <p class="p">The options that can be seen with <span style="" class="text typewriter">ccmake</span> are ones that we
+think a reasonable number of users might want to consider
+changing. There are a lot more options available, which you can see by
+toggling the advanced mode in <span style="" class="text typewriter">ccmake</span> on and off with
+'<code class="verbatim">t</code>'. Even there, most of the variables that you might want to
+change have a '<code class="verbatim">CMAKE_</code>' or '<code class="verbatim">GMX_</code>' prefix.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS4">
+ <h3 class="title subsection-title"> 3.4. Helping CMake find the right libraries/headers/programs</h3>
+ <div class="para" id="S3.SS4.p1">
+ <p class="p">If libraries are installed in non-default locations their location can
+be specified using the following environment variables:</p>
+
+ <ul class="itemize" id="I4">
+
+ <li class="item" id="I4.i1">
+
+ <div class="para" id="I4.i1.p1">
+ <p class="p"><span style="" class="text typewriter">CMAKE_INCLUDE_PATH</span> for header files</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I4.i2">
+
+ <div class="para" id="I4.i2.p1">
+ <p class="p"><span style="" class="text typewriter">CMAKE_LIBRARY_PATH</span> for libraries</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I4.i3">
+
+ <div class="para" id="I4.i3.p1">
+ <p class="p"><span style="" class="text typewriter">CMAKE_PREFIX_PATH</span> for header, libraries and binaries
+(e.g. '<code class="verbatim">/usr/local</code>').</p>
+ </div>
+
+ </li>
+
+ </ul>
+
+ <p class="p">The respective '<code class="verbatim">include</code>', '<code class="verbatim">lib</code>', or '<code class="verbatim">bin</code>' is
+appended to the path. For each of these variables, a list of paths can
+be specified (on Unix seperated with ”:”). Note that these are
+enviroment variables (and not CMake command-line arguments) and in
+a '<code class="verbatim">bash</code>' shell are used like:</p>
+ <pre class="verbatim">
+$ CMAKE_PREFIX_PATH=/opt/fftw:/opt/cuda cmake ..
+</pre></div>
+
+ <div class="para" id="S3.SS4.p2">
+ <p class="p">The <span style="" class="text typewriter">CC</span> and <span style="" class="text typewriter">CXX</span> environment variables are also useful
+for indicating to CMake which compilers to use, which can be very
+important for maximising GROMACS performance. Similarly,
+<span style="" class="text typewriter">CFLAGS</span>/<span style="" class="text typewriter">CXXFLAGS</span> can be used to pass compiler
+options, but note that these will be appended to those set by
+GROMACS for your build platform and build type. You can customize
+some of this with advanced options such as <span style="" class="text typewriter">CMAKE_C_FLAGS</span>
+and its relatives.</p>
+ </div>
+
+ <div class="para" id="S3.SS4.p3">
+ <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>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS5">
+ <h3 class="title subsection-title"> 3.5. CMake advice during the GROMACS 4.6 beta phase</h3>
+ <div class="para" id="S3.SS5.p1">
+ <p class="p">We'd like users to have the ability to change any setting and still
+have the CMake cache stable; ie. not have things you set
+mysteriously change, or (worse) the whole thing breaks. We're not
+there yet. If you know in advance you will want to use a particular
+setting, set that on the initial <span style="" class="text typewriter">cmake</span> command line. If you
+have to change compilers, do that there, or immediately afterwards in
+<span style="" class="text typewriter">ccmake</span>. Gross changes like GPU or shared libraries on/off are
+more likely to work if you do them on the initial command line,
+because that's how we've been doing it while developing and
+testing. If you do make a mess of things, there's a great thing about
+an out-of-source build - you can just do '<code class="verbatim">rm -rf *</code>' and start
+again. Easy!</p>
+ </div>
+
+ <div class="para" id="S3.SS5.p2">
+ <p class="p">We are interested in learning how you managed to break things. If you
+can reproducibly reach a state where CMake can't proceed, or
+subsequent compilation/linking/running fails, then we need to know so
+we can fix it!</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS6">
+ <h3 class="title subsection-title"> 3.6. Native GPU acceleration</h3>
+ <div class="para" id="S3.SS6.p1">
+ <p class="p">If you have the CUDA SDK installed, you can use CMake
+with:</p>
+ <pre class="verbatim">
+cmake .. -DGMX_GPU=ON -DCUDA_TOOLKIT_ROOT_DIR=/usr/local/cuda
+</pre>
+ <p class="p">(or whichever path has your installation). Note that this will require
+a working C++ compiler, and in some cases you might need to handle
+this manually, e.g. with the advanced option
+<span style="" class="text typewriter">CUDA_NVCC_HOST_COMPILER</span>.</p>
+ </div>
+
+ <div class="para" id="S3.SS6.p2">
+ <p class="p">More documentation needed here - particular discussion of fiddly
+details on Windows, Linux and Mac required. Not all compilers on all
+systems can be made to work.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS7">
+ <h3 class="title subsection-title"> 3.7. Static linking</h3>
+ <div class="para" id="S3.SS7.p1">
+ <p class="p">Dynamic linking of the GROMACS executables will lead to a smaller
+disk footprint when installed, and so is the default. However, on some
+hardware or under some circumstances you might need to do static
+linking. To link GROMACS binaries statically against the internal
+GROMACS libraries, set <span style="" class="text typewriter">BUILD_SHARED_LIBS=OFF</span>. To link
+statically against external libraries as well, the
+<span style="" class="text typewriter">GMX_PREFER_STATIC_LIBS=ON</span> option can be used. Note, that
+in general CMake picks up whatever is available, so this option
+only instructs CMake to prefer static libraries when both static
+and shared are available. If no static version of an external library
+is available, even when the aforementioned option is ON, the shared
+library will be used. Also note, that the resulting binaries will
+still be dynamically linked against system libraries if that is all
+that is available.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS8">
+ <h3 class="title subsection-title"> 3.8. Suffixes for binaries and libraries</h3>
+ <div class="para" id="S3.SS8.p1">
+ <p class="p">It is sometimes convenient to have different versions of the same
+GROMACS libraries installed. The most common use cases have been
+single and double precision, and with and without MPI. By default,
+GROMACS will suffix binaries and libraries for such builds with
+'<code class="verbatim">_d</code>' for double precision and/or '<code class="verbatim">_mpi</code>' for MPI (and
+nothing otherwise). This can be controlled manually with
+<span style="" class="text typewriter">GMX_DEFAULT_SUFFIX</span>, <span style="" class="text typewriter">GMX_BINARY_SUFFIX</span> and
+<span style="" class="text typewriter">GMX_LIBRARY_SUFFIX</span>.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS9">
+ <h3 class="title subsection-title"> 3.9. Building GROMACS</h3>
+ <div class="para" id="S3.SS9.p1">
+ <p class="p">Once you have a stable cache, you can build GROMACS. If you're not
+sure the cache is stable, you can re-run <code class="verbatim">cmake ..</code> or
+<code class="verbatim">ccmake ..</code>' to see. Then you can run <span style="" class="text typewriter">make</span> to start the
+compilation. Before actual compilation starts, <span style="" class="text typewriter">make</span> checks
+that the cache is stable, so if it isn't you will see CMake run
+again.</p>
+ </div>
+
+ <div class="para" id="S3.SS9.p2">
+ <p class="p">So long as any changes you've made to the configuration are sensible,
+it is expected that the <span style="" class="text typewriter">make</span> procedure will always complete
+successfully. The tests GROMACS makes on the settings you choose
+are pretty extensive, but there are probably a few cases we haven't
+thought of yet. Search the web first for solutions to problems,
+but if you need help, ask on <span style="" class="text typewriter">gmx-users</span>, being sure to provide
+as much information as possible about what you did, the system you are
+building on, and what went wrong.</p>
+ </div>
+
+ <div class="para" id="S3.SS9.p3">
+ <p class="p">If you have a multi-core or multi-CPU machine with <span style="" class="text typewriter">N</span>
+processors, then using</p>
+ <pre class="verbatim">
+$ make -j N
+</pre>
+ <p class="p">will generally speed things up by quite a bit.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS10">
+ <h3 class="title subsection-title"> 3.10. Installing GROMACS</h3>
+ <div class="para" id="S3.SS10.p1">
+ <p class="p">Finally, <span style="" class="text typewriter">make install</span> will install GROMACS in the
+directory given in <span style="" class="text typewriter">GMX_INSTALL_PREFIX</span>. If this is an system
+directory, then you will need permission to write there, and you
+should use super-user privileges only for <span style="" class="text typewriter">make install</span> and
+not the whole procedure.
+</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS11">
+ <h3 class="title subsection-title"> 3.11. Getting access to GROMACS after installation</h3>
+ <div class="para" id="S3.SS11.p1">
+ <p class="p">GROMACS installs the script <span style="" class="text typewriter">GMXRC</span> in the <span style="" class="text typewriter">bin</span>
+subdirectory of the installation directory
+(e.g. <span style="" class="text typewriter">/usr/local/gromacs/bin/GMXRC</span>), which you should source
+from your shell:</p>
+ <pre class="verbatim">
+$ source your-installation-prefix-here/bin/GMXRC
+</pre></div>
+
+ <div class="para" id="S3.SS11.p2">
+ <p class="p">It will detect what kind of shell you are running and
+set up your environment for using GROMACS. You may wish to arrange
+for your login scripts to do this automatically; please search the web
+for instructions on how to do this for your shell.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS12">
+ <h3 class="title subsection-title"> 3.12. Testing GROMACS for correctness</h3>
+ <div class="para" id="S3.SS12.p1">
+ <p class="p">TODO install and use regression set</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS13">
+ <h3 class="title subsection-title"> 3.13. Testing GROMACS for performance</h3>
+ <div class="para" id="S3.SS13.p1">
+ <p class="p">TODO benchmarks</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S3.SS14">
+ <h3 class="title subsection-title"> 3.14. Having difficulty?</h3>
+ <div class="para" id="S3.SS14.p1">
+ <p class="p">You're not alone, this can be a complex task. If you encounter a
+problem with installing GROMACS, then there are a number of
+locations where you can find assistance. It is recommended that you
+follow these steps to find the solution:</p>
+ </div>
+
+ <div class="para" id="S3.SS14.p2">
+ <ol class="enumerate" id="I5">
+
+ <li class="item" id="I5.i1">
+
+ <div class="para" id="I5.i1.p1">
+ <p class="p">Read the installation instructions again, taking note that you
+have followed each and every step correctly.</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I5.i2">
+
+ <div class="para" id="I5.i2.p1">
+ <p class="p">Search the GROMACS website and users emailing list for
+information on the error.</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I5.i3">
+
+ <div class="para" id="I5.i3.p1">
+ <p class="p">Search the internet using a search engine such as Google.</p>
+ </div>
+
+ </li>
+
+ <li class="item" id="I5.i4">
+
+ <div class="para" id="I5.i4.p1">
+ <p class="p">Post to the GROMACS users emailing list <span style="" class="text typewriter">gmx-users</span>
+for assistance. Be sure to give a full description of what you have
+done and why you think it didn't work. Give details about the system
+on which you are installing. Copy and paste your command line and as
+much of the output as you think might be relevant - certainly from
+the first indication of a problem. Describe the machine and
+operating system you are running on. People who might volunteer to
+help you do not have time to ask you interactive detailed follow-up
+questions, so you will get an answer faster if you provide as much
+information as you think could possibly help.</p>
+ </div>
+
+ </li>
+
+ </ol>
+ </div>
+
+ </div>
+
+ </div>
+
+ <div class="section" id="S4">
+ <h2 class="title section-title"> 4. Special instructions for some platforms</h2>
+ <div class="subsection" id="S4.SS1">
+ <h3 class="title subsection-title"> 4.1. Building on Windows</h3>
+ <div class="para" id="S4.SS1.p1">
+ <p class="p">Need a volunteer to write this section.</p>
+ </div>
+
+ <div class="para" id="S4.SS1.p2">
+ <p class="p">Cygwin works just like Unix.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S4.SS2">
+ <h3 class="title subsection-title"> 4.2. Building on Cray</h3>
+ <div class="para" id="S4.SS2.p1">
+ <p class="p">Probably you need to build static libraries only? Volunteer needed.</p>
+ </div>
+
+ </div>
+
+ <div class="subsection" id="S4.SS3">
+ <h3 class="title subsection-title"> 4.3. Building on BlueGene</h3>
+ <div class="subsubsection" id="S4.SS3.SSS1">
+ <h4 class="title subsubsection-title"> 4.3.1. BlueGene/P</h4>
+ <div class="para" id="S4.SS3.SSS1.p1">
+ <p class="p">Mark to write later. There is currently no native acceleration on this
+platform, but the default kernels will work.</p>
+ </div>
+
+ </div>
+
+ <div class="subsubsection" id="S4.SS3.SSS2">
+ <h4 class="title subsubsection-title"> 4.3.2. BlueGene/Q</h4>
+ <div class="para" id="S4.SS3.SSS2.p1">
+ <p class="p">Mark to write later. There is currently no native acceleration on this
+platform, but the default kernels will work.</p>
+ </div>
+
+ </div>
+
+ </div>
+
+ </div>
+
+ <div class="section" id="S5">
+ <h2 class="title section-title"> 5. Tested platforms</h2>
+ <div class="para" id="S5.p1">
+ <p class="p">While it is our best belief that GROMACS will build and run pretty
+much everywhere, it's important that we tell you where we really know
+it works because we've tested it. We do test on Linux, Windows, and
+Mac with a range of compilers and libraries for a range of our
+configuration options. Every commit in our <span style="" class="text typewriter">git</span> source code
+repository is tested on … We test irregularly on…</p>
+ </div>
+
+ <div class="para" id="S5.p2">
+ <p class="p">Contributions to this section are welcome.</p>
+ </div>
+
+ <div class="para" id="S5.p3">
+ <p class="p">Later we might set up the ability for users to contribute test results
+to Jenkins.</p>
+ </div>
+
+ </div>
+
+ <div class="section" id="S6">
+ <h2 class="title section-title"> 6. Other issues</h2>
+ <div class="para" id="S6.p1">
+ <p class="p">The GROMACS utility programs often write data files in formats
+suitable for the Grace plotting tool, but it is straightforward to
+use these files in other plotting programs, too.</p>
+ </div>
+
+ </div>
+
+ </div>
+
+ </div>
+ </div>
+ </body>
+ </html>
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff