Gromacs

Installation Instructions 4.5

    Redirected from Downloads/Installation Instructions

    Planning

    You will need to install GROMACS and any prerequisites somewhere you have write access. If you have superuser privileges, then you will have the option of just installing to the default locations. If you have a site installation policy that prohibits this, or lack superuser privileges, or wish to maintain multiple GROMACS installations, then you will need to choose somewhere suitable to install. For example, user joe might wish to install FFTW to /home/joe/programs/fftw.

    GROMACS is able to compile as a set of shared libraries, which greatly reduces the disk footprint of the installation, but this can be tricky on some platforms. If you encounter problems at the linking stages below, it is recommended that you configure everything for static libraries (i.e. with --disable-shared or --enable-all-static).

    Prerequisites

    GROMACS relies on very few external dependencies, namely:

    • An ANSI C compiler, and (very rarely) a Fortran compiler. GROMACS can be compiled entirely in C, which means you should be able to get it running on essentially any UNIX-style computer in the world. However prior to version 4.5, we also provide the innermost loops for some platforms in Fortran to improve performance, so we strongly recommend you to use a Fortran compiler on those platforms if you can - it makes a huge difference! For modern Intel and AMD processors we provide faster loops written in assembler, so for those you should skip Fortran. gcc version 4.5 is recommended, but for some very recent processors, gcc 4.6 can give better performance. Where assembly loops are in use, GROMACS performance is largely independent of the compiler used, so don't worry too much about it. The gcc 4.1.x series of compilers shipped with some Linux workstation distributions are broken for GROMACS - do not attempt to compile GROMACS with them.
    • To enable the native GPU acceleration in GROMACS, CUDA v3.2 or higher is required. The CUDA toolkit can be downloaded from the NVIDIA website.
    • If you want to run in parallel across a network, you need MPI. If you are running on a supercomputer you probably already have an optimized MPI version installed - consult your documentation or ask your system administrator. See below for information about how to make use of MPI.  As of GROMACS 4.5, threading is supported, so for e.g multi-core workstations, MPI is no longer required. Some older versions of MPICH and MVAPICH are unsuitable. OpenMPI is recommended.
    • You need an FFT library to perform Fourier transforms. Its precision (double vs single) needs to match the precision with which you intend to compile GROMACS. Often a distro will provide only a double-precision version, and to get the full benefit of GROMACS performance you will need to install a single-precision version. Recent GROMACS versions support FFTW-2.1.x, FFTW-3.x, ACML, Intel Math Kernel (MKL) library version 6.0 and later, and we also have a version of FFTPACK built into GROMACS. FFTPACK is really slow, and if there's any possibility you will want to use the PME algorithm, you are strongly advised to use a better FFT library. We currently recommend that you use the free FFTW3 library (see  http://www.fftw.org), since it is the most tested, and very fast.
    • You may want X and Motif/Lesstif libraries and headers for building the optional built-in visualization software ngmx. Note that this may mean installing packages with "-devel" suffixes if using your distro package manager.

    Details for building the FFTW prerequisite

    Various pre-compiled versions of the FFTW libraries exist (as well as rpms, debs, etc.), but to compile FFTW from source, follow these instructions. You may wish to do this if configure complains about FFT libraries, which are only available in double precision in some distributions. The precision of the FFTW libraries must match that of GROMACS. To compile a single-precision version of the libraries:

    ./configure --enable-float
    make
    make install 
    

    A few tips:

    • Add --enable-sse if your computers have i686 or x86-64 processors.
    • By default, FFTW header files will be installed in /usr/local/include the library files in /usr/local/lib. If you do not like that (since you must have root permissions to write there), you can place them e.g. in your own home directory by using the option --prefix. As an example, if you are Joe whose home directory is /home/joe, you might choose to set --prefix=/home/joe/programs/fftw, the headers will go in /home/joe/programs/fftw/include and the library files in /home/joe/programs/fftw/lib. Don't take this example literally - install somewhere that makes sense for you on your system!
    • If you get errors during GROMACS compilation (the "make" step) that suggest that you "recompile with -fPIC," then you should return to this FFTW stage, use make distclean and configure again using --enable-shared or --with-pic, before make and make install. Another possibility: something may be broken in the GROMACS build process.  As JLemkul noted here, configuration seems to indicate both shared and static libraries should be built, so some linking conflict within GROMACS could be the real problem.  If you built shared FFTW libraries, you should build shared GROMACS libraries (default behavior as of version 4.5.4), otherwise --disable-shared explicitly when configuring GROMACS.
    • The parallel transforms in FFTW haven't been used since GROMACS 3.3, so don't worry about MPI versions of the FFTW libraries.

    In some cases, it can also be useful to compile and install a double-precision version of the FFTW libraries. This can be accomplished with:

    make distclean
    ./configure
    make
    make install

    Configuration

    Using CMake

    Starting with GROMACS 4.5, Cmake (cross-platform make) can be used to build GROMACS. It will be the only build system begining with 4.6, with the old autoconf/automake system unavailable. CMake packages for various platforms can be found on the CMake project's download page. Most Linux distributions come with packages available through their corresponding package manager. Make sure you have version is 2.8 or later installed. Installation instructions for GROMACS using CMake can be found here.

    Using autoconf

    After installing and necessary prerequisites (e.g. FFTW or MPI), you are ready to install GROMACS. The process is very simple. After unpacking the source code, configure the installation with:

    ./configure
    

    This will check you system and automatically configure GROMACS with the default options and best optimizations for your type of computer. The script will let you know about any problems. If you don't want GROMACS installed in /usr/local/gromacs (since you have to be root to write there), select the path you want with the --prefix option. For versions 4.5.x, threading is enabled by default - this is incompatible with MPI, so choose one or the other. Threading is useful only when all your cores are real (i.e. not hyper-threading) and do not need any network to communicate.

    You can get a listing of all options recognized by configure by using the --help option.

    • If you want to compile an MPI parallel version of GROMACS, use the --enable-mpi option.
    • The default is to compile GROMACS in single precision, double precision is selected by the --disable-float option.
    • Especially for use on compute clusters, which may lack X and Motif/Lesstif libraries, consider --without-x. Only the built-in visualization software ngmx uses X, and so if you plan not to use that (for instance, on clusters where you may only need mdrun), you don't need to worry about installing and linking X and Motif libraries.
    • GROMACS tries to find FFTW and all optional libraries (like Lesstif and X) automatically, but this requires that they are present in the default places where the system searches for include files and libraries. If this is not the case (for instance, your system might not look in /usr/local/include and /usr/local/lib where FFTW is placed, or you may have configured FFTW with --prefix to install to a location of your choice) you can tell configure to include these locations by using the environment variables CPPFLAGS and LDFLAGS for includes and libraries, respectively. These variables can be specified separately, in advance of configuration, or on the ./configure command line. Assuming that you have configured and installed FFTW with --prefix=/home/joe/programs/fftw, if your shell is tcsh, you set:
    setenv CPPFLAGS -I/home/joe/programs/fftw/include
    setenv LDFLAGS -L/home/joe/programs/fftw/lib
    

    If your shell is bash:

    export CPPFLAGS="-I/home/joe/programs/fftw/include"
    export LDFLAGS="-L/home/joe/programs/fftw/lib"
    

    Alternative forms of the FFTW can be used, if you prefer, by specifying, for example:

    ./configure --with-fft=fftw2
    
    • The currently available FFT choices are fftw3, fftw2, mkl (Intel MKL), and FFTPACK (the built-in default, which is very slow).  If you're having difficulty installing with MKL, see this post on the gmx-users mailing list for tips. (However, mabraham thinks the form of that solution is unwise. ./configure --with-fft=mkl LIBS="-L${MKL}/lib/em64t -lmkl_lapack -lmkl_core -lmkl_em64t -lguide -lpthread" works fine in his case, but note that the libraries and their order will have to be chosen correctly for your system! On Intel systems with Intel compilers, mabraham observed MKL to be only a few percent faster than FFTW3, so you can save yourself some pain by using FFTW3.)

    Other notes:

    • If you don't like the compilers configure detects, just set them with the variables CC and/or F77 (MPICC for the MPI C compiler). You can add extra libraries (-llibrary) in the LIBS variable.
    • The configure script automatically detects not only your architecture, but also the specific CPU version of your computer to optimize as much as possible. Different CPU types will be installed in subdirectories below the architecture directory. If you don't want this, you can select an explicit location for binaries and libraries with --exec-prefix. If you have many similar machines, but with slightly different CPUs, it might be a good idea to compile one full version of GROMACS without CPU-specific optimizations or MPI parallelization (this version will be located in the main architecture directory), and then only compile mdrun for each CPU type. (Linux is a notable exception; we compile both non-assembly, SSE and sometimes 3DNow loops and select which one to use at runtime.)
    • GROMACS can use shared libraries on almost any platform, but since there are a few special cases where it doesn't work (MPI builds on aix, BlueGene, and OS X) it is not enabled by default. Static libraries also result in binaries that are more portable (you won't have to install the libraries if you want to make a test run on a computer without GROMACS). On the other hand, shared libraries will decrease the installation size from 100Mb to 10Mb, so you might want to try using it with --enable-shared. The large number of GROMACS utility programs show the greatest benefit from that, but these do not benefit at all from --enable-mpi (see below). So if you have problems with shared libraries and MPI together, then do two installations, one with --enable-shared for the tools and one with --enable-mpi for mdrun_mpi.
    • If you want to start over or change your configuration a later time (once you have started to compile things) you should restore the distribution to its initial clean state by typing:
    make distclean
    

    Compilation

    To compile GROMACS, simply issue:

    make
    

    If you want a log file of the compilation, type:

    make &> log
    

    If you have configured with --enable-mpi, then since only mdrun is MPI-aware, you can save time and build only this executable (but you'll need to do another configure and compile without MPI to get the tools):

    make mdrun
    

    If you are using GNU make (any Linux system) and have more than one CPU you can do a parallel build by adding the option "-j N", where N is the number of build threads. It compiles amazingly fast on a 16-way SMP machine!

    Otherwise - sit back and wait for the package to compile. Once it's done you might want to check the output of the make command, or at least make sure there weren't any fatal errors. If you get errors that suggest recompiling something with -fPIC, see Details for building the FFTW prerequisite above.

    Final Installation

    If GROMACS compiled without error, this last step is trivial. However, if you have an older GROMACS version in the same location you should remove it before proceeding! To adhere to modern Linux standards we have changed some subdirectories, and if you just install over the older files you risk ending up with a confusing mess of duplicate files and data.

    Install all the binaries, libraries and shared data files with:

    make install
    

    If you only want to build the mdrun executable (in the case of an MPI build), issue the following:

    make install-mdrun
    

    If you want to create links in /usr/local/bin to the installed GROMACS executables, and you have superuser privileges to write to that location, issue the command:

    make links
    
    

    You may find that any of the above create a bunch of errors from make about being denied permissions. This means you are trying to install somewhere that is not permitted for your user. Either use configure --prefix as above to install somewhere that you do have permission, or switch to the root user for only the actual installation step (not the whole procedure).

    Using MPI

    You may notice that the above instructions for an MPI installation (so you can run in parallel) recommend only doing make mdrun and make install-mdrun. That's because in GROMACS, only mdrun is MPI-aware. Perhaps in the future, some of the utility programs may become MPI-aware, but these will only be for compute-intensive utilities (e.g. that diagonalize large matrices, or calculate autocorrelations, etc.).

    Building and installing the other utilities with configure --enable-mpi is a waste of time, as is attempting to use any resulting MPI-linked-but-unaware utilities with mpirun. You may even run into more issues with shared libraries, so keep things simple!  Thus, if you wish to install an MPI-enabled mdrun executable, simply add the --enable-mpi --program-suffix=_mpi options to configure, then proceed with make mdrun and make install-mdrun.

    Test Set

    test set is available for testing of a GROMACS installation. It's broken, so don't bother trying to use it.

    Getting access to GROMACS after installation

    In a normal Unix/Linux/Cygwin/MacOS environment you will need to know the location where GROMACS is installed, e.g. /usr/local/gromacs. This may have been selected with --prefix as discussed above.

    In your shell configuration file (e.g. .bashrc for bash or .cshrc/.tcshrc for tcsh) you should use a command analogous to:

    source /usr/local/gromacs/bin/GMXRC

    near the end of that file.

    GMXRC then magically determines the type of shell you are using and configures your PATH, MANPATH, GMXLIB etc. environment variables  so that GROMACS works as intended. Note that you will then need to re-source your shell configuration file, or open a new shell in order to have the intended effect. If you prefer, you can interactively invoke the source command as above from your command line, and if you know you might want access to multiple versions of GROMACS in an interchangeable manner, this can be a useful approach.

    At some larger computing facilities, you should consult their documentation and/or staff for instructions on how GROMACS was installed and how you should get access to it and use it.

    Just as with everything else in the UNIX world, you should not do your daily work with GROMACS as root or superuser. It's unnecessary and highly risky. See here for more information.

    Removing a GROMACS installation

    To remove a GROMACS installation, see Removing Installation.

    Having difficulty?

    Edit section

    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:

    1. read the installation instructions again, taking note that you have followed each and every step correctly.
    2. search the GROMACS website and users emailing list for information on the error.
    3. search this wiki for information.
    4. search the internet using a search engine such as Google.
    5. post to the GROMACS users emailing list 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.

    Specialty InstructionsEdit section

    Page last modified 12:08, 6 May 2012 by mabraham