.. highlight:: bash
Introduction to building |Gromacs|
-==================================
+----------------------------------
These instructions pertain to building |Gromacs|
|version|. You might also want to check the `up-to-date installation instructions`_.
Quick and dirty installation
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Get the latest version of your C and C++ compilers.
2. Check that you have CMake version |CMAKE_MINIMUM_REQUIRED_VERSION| or later.
3. Get and unpack the latest version of the |Gromacs| tarball.
-4. Make a separate build directory and change to it.
+4. Make a separate build directory and change to it.
5. Run ``cmake`` with the path to the source as an argument
6. Run ``make``, ``make check``, and ``make install``
7. Source ``GMXRC`` to get access to |Gromacs|
more complex.
Quick and dirty cluster installation
-------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On a cluster where users are expected to be running across multiple
nodes using MPI, make one installation similar to the above, and
the non-MPI build is installed.
Typical installation
---------------------
+^^^^^^^^^^^^^^^^^^^^
+
As above, and with further details below, but you should consider
using the following `CMake options`_ with the
appropriate value instead of ``xxx`` :
* ``-DCMAKE_PREFIX_PATH=xxx`` to add a non-standard location for CMake to `search for libraries, headers or programs`_
* ``-DCMAKE_INSTALL_PREFIX=xxx`` to install |Gromacs| to a `non-standard location`_ (default ``/usr/local/gromacs``)
* ``-DBUILD_SHARED_LIBS=off`` to turn off the building of shared libraries to help with `static linking`_
-* ``-DGMX_FFT_LIBRARY=xxx`` to select whether to use ``fftw``, ``mkl`` or ``fftpack`` libraries for `FFT support`_
+* ``-DGMX_FFT_LIBRARY=xxx`` to select whether to use ``fftw3``, ``mkl`` or ``fftpack`` libraries for `FFT support`_
* ``-DCMAKE_BUILD_TYPE=Debug`` to build |Gromacs| in debug mode
Building older versions
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
+
Installation instructions for old |Gromacs| versions can be found at
the |Gromacs| `documentation page
<http://manual.gromacs.org/documentation>`_.
Prerequisites
-=============
+-------------
+
Platform
---------
+^^^^^^^^
+
|Gromacs| can be compiled for many operating systems and
architectures. These include any distribution of Linux, Mac OS X or
Windows, and architectures including x86, AMD64/x86-64, several
PowerPC including POWER8, ARM v7, ARM v8, and SPARC VIII.
Compiler
---------
+^^^^^^^^
|Gromacs| can be compiled on any platform with ANSI C99 and C++11
compilers, and their respective standard C/C++ libraries. Good
* RHEL/CentOS: `EPEL page`_ or the RedHat Developer Toolset
Compiling with parallelization options
---------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For maximum performance you will need to examine how you will use
|Gromacs| and what hardware you plan to run on. Often OpenMP_
generally built into your compiler and detected automatically.
GPU support
-^^^^^^^^^^^
+~~~~~~~~~~~
+
|Gromacs| has excellent support for NVIDIA GPUs supported via CUDA.
On Linux, NVIDIA CUDA_ toolkit with minimum version |REQUIRED_CUDA_VERSION|
-is required, and the latest
-version is strongly encouraged. Using Intel or Microsoft MSVC compilers
-requires version 7.0 and 8.0, respectively. NVIDIA GPUs with at
+is required, and the latest version is strongly encouraged. Using
+Microsoft MSVC compiler requires version 8.0. NVIDIA GPUs with at
least NVIDIA compute capability |REQUIRED_CUDA_COMPUTE_CAPABILITY| are
required. You are strongly recommended to
get the latest CUDA version and driver that supports your hardware, but
OpenCL_ support. The minimum OpenCL version required is
|REQUIRED_OPENCL_MIN_VERSION|. The current OpenCL implementation is recommended for
use with GCN-based AMD GPUs, on Linux we recommend the ROCm runtime.
+For Intel GPUs it is required to compile with ``-DGMX_OCL_NB_CLUSTER_SIZE=4`` and
+the `Neo driver <https://github.com/intel/compute-runtime/releases>`_ is recommended.
It is also supported with NVIDIA GPUs, but using
the latest NVIDIA driver (which includes the NVIDIA OpenCL runtime) is
recommended. Also note that there are performance limitations (inherent
.. _mpi-support:
MPI support
-^^^^^^^^^^^
+~~~~~~~~~~~
|Gromacs| can run in parallel on multiple cores of a single
workstation using its built-in thread-MPI. No user action is required
been deprecated for years, it is not supported.
CMake
------
+^^^^^
|Gromacs| builds with the CMake build system, requiring at least
version |CMAKE_MINIMUM_REQUIRED_VERSION|. You can check whether
.. _FFT support:
Fast Fourier Transform library
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Many simulations in |Gromacs| make extensive use of fast Fourier
transforms, and a software library to perform these is always
required. We recommend FFTW_ (version 3 or higher only) or Intel
MKL_. The choice of library can be set with ``cmake
--DGMX_FFT_LIBRARY=<name>``, where ``<name>`` is one of ``fftw``,
+-DGMX_FFT_LIBRARY=<name>``, where ``<name>`` is one of ``fftw3``,
``mkl``, or ``fftpack``. FFTPACK is bundled with |Gromacs| as a
fallback, and is acceptable if simulation performance is not a
priority. When choosing MKL, |Gromacs| will also use MKL for BLAS and
software component is needed when building with CUDA GPU acceleration.
Using 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,
slightly faster.
Using MKL
-^^^^^^^^^
+~~~~~~~~~
+
Use MKL bundled with Intel compilers by setting up the compiler
environment, e.g., through ``source /path/to/compilervars.sh intel64``
or similar before running CMake including setting
The full list and order(!) of libraries you require are found in Intel's MKL documentation for your system.
Other optional build components
--------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
* Run-time detection of hardware capabilities can be improved by
linking with hwloc, which is automatically enabled if detected.
* Hardware-optimized BLAS and LAPACK libraries are useful
by setting ``-DGMX_EXTERNAL_TNG=yes``, but TNG
|GMX_TNG_MINIMUM_REQUIRED_VERSION| is bundled in the |Gromacs|
source already.
-* An external lmfit library for Levenberg-Marquardt curve fitting
- can be used by setting ``-DGMX_EXTERNAL_LMFIT=yes``, but lmfit
- |GMX_LMFIT_MINIMUM_REQUIRED_VERSION| is bundled in the |Gromacs|
- source already.
+* The lmfit library for Levenberg-Marquardt curve fitting is used in
+ |Gromacs|. Only lmfit |GMX_LMFIT_REQUIRED_VERSION| is supported. A
+ reduced version of that library is bundled in the |Gromacs|
+ distribution, and the default build uses it. That default may be
+ explicitly enabled with ``-DGMX_USE_LMFIT=internal``. To use an
+ external lmfit library, set ``-DGMX_USE_LMFIT=external``, and adjust
+ ``CMAKE_PREFIX_PATH`` as needed. lmfit support can be disabled with
+ ``-DGMX_USE_LMFIT=none``.
* zlib is used by TNG for compressing some kinds of trajectory data
* Building the |Gromacs| documentation is optional, and requires
- ImageMagick, pdflatex, bibtex, doxygen, python 2.7, sphinx
+ ImageMagick, pdflatex, bibtex, doxygen, python 2.7, sphinx
|EXPECTED_SPHINX_VERSION|, and pygments.
* 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.
-
+
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
.. _configure-cmake:
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 your build machine is the same as
your target machine, then you can be sure that the defaults and
.. _non-standard location:
Where to install |Gromacs|
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
|Gromacs| is installed in the directory to which
``CMAKE_INSTALL_PREFIX`` points. It may not be the source directory or
.. _cmake options:
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 ``cmake`` and passing the various options at once
be able to be changed interactively in that run of ``ccmake``.
SIMD support
-^^^^^^^^^^^^
+~~~~~~~~~~~~
+
|Gromacs| has extensive support for detecting and using the SIMD
capabilities of many modern HPC CPU architectures. If you are building
|Gromacs| on the same hardware you will run it on, then you don't need
Additionally, with GPU accelerated runs ``AVX2_256`` can also be
faster on high-end Skylake CPUs with both 512-bit FMA units enabled.
9. ``AVX_512_KNL`` Knights Landing Xeon Phi processors
-10. ``IBM_QPX`` BlueGene/Q A2 cores have this.
-11. ``Sparc64_HPC_ACE`` Fujitsu machines like the K computer have this.
-12. ``IBM_VMX`` Power6 and similar Altivec processors have this.
-13. ``IBM_VSX`` Power7, Power8 and later have this.
-14. ``ARM_NEON`` 32-bit ARMv7 with NEON support.
-15. ``ARM_NEON_ASIMD`` 64-bit ARMv8 and later.
+10. ``Sparc64_HPC_ACE`` Fujitsu machines like the K computer have this.
+11. ``IBM_VMX`` Power6 and similar Altivec processors have this.
+12. ``IBM_VSX`` Power7, Power8 and later have this.
+13. ``ARM_NEON`` 32-bit ARMv7 with NEON support.
+14. ``ARM_NEON_ASIMD`` 64-bit ARMv8 and later.
The CMake configure system will check that the compiler you have
chosen can target the architecture you have chosen. mdrun will check
SIMD architectures in a few days.
CMake advanced options
-^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~
+
The options that are displayed in the default view of ``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
.. _search for libraries, headers or programs:
Helping CMake find the right libraries, headers, or programs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
If libraries are installed in non-default locations their location can
be specified using the following variables:
.. _CUDA GPU acceleration:
CUDA GPU acceleration
-^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~
+
If you have the CUDA_ Toolkit installed, you can use ``cmake`` with:
::
every single possible architecture, which in rare cases (say, Tegra systems)
can result in the default build not being able to use some GPUs.
If this happens, or if you want to remove some architectures to reduce
-binary size and build time, you can alter the target CUDA architectures.
+binary size and build time, you can alter the target CUDA architectures.
This can be done either with the ``GMX_CUDA_TARGET_SM`` or
``GMX_CUDA_TARGET_COMPUTE`` CMake variables, which take a semicolon delimited
string with the two digit suffixes of CUDA (virtual) architectures names, for
OpenCL GPU acceleration
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
The primary target of the |Gromacs| OpenCL support is accelerating simulations
on AMD hardware, both discrete GPUs and APUs (integrated CPU+GPU chips).
On Mac OS, an AMD GPU can be used only with OS version 10.10.4 and
higher; earlier OS versions are known to run incorrectly.
+By default, any clFFT library on the system will be used with
+|Gromacs|, but if none is found then the code will fall back on a
+version bundled with |Gromacs|. To require |Gromacs| to link with an
+external library, use
+
+::
+
+ cmake .. -DGMX_GPU=ON -DGMX_USE_OPENCL=ON -DclFFT_ROOT_DIR=/path/to/your/clFFT -DGMX_EXTERNAL_CLFFT=TRUE
+
Static linking
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
+
Dynamic linking of the |Gromacs| executables will lead to a
smaller disk footprint when installed, and so is the default on
platforms where we believe it has been tested repeatedly and found to work.
In general, this includes Linux, Windows, Mac OS X and BSD systems.
Static binaries take more space, but on some hardware and/or under
some conditions they are necessary, most commonly when you are running a parallel
-simulation using MPI libraries (e.g. BlueGene, Cray).
+simulation using MPI libraries (e.g. Cray).
* To link |Gromacs| binaries statically against the internal |Gromacs|
libraries, set ``-DBUILD_SHARED_LIBS=OFF``.
Linux, this is usually ``CFLAGS=-static CXXFLAGS=-static``.
Portability aspects
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
+
A |Gromacs| build will normally not be portable, not even across
hardware with the same base instruction set, like x86. Non-portable
hardware-specific optimizations are selected at configure-time, such
``-DGMX_BUILD_MDRUN_ONLY=ON`` option.
Linear algebra libraries
-^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~
+
As mentioned above, sometimes vendor BLAS and LAPACK libraries
can provide performance enhancements for |Gromacs| when doing
normal-mode analysis or covariance analysis. For simplicity, the text
accordingly. The internal versions are fine for normal use. If you
need to specify a non-standard path to search, use
``-DCMAKE_PREFIX_PATH=/path/to/search``. If you need to specify a
-library with a non-standard name (e.g. ESSL on AIX or BlueGene), then
+library with a non-standard name (e.g. ESSL on Power machines), then
set ``-DGMX_BLAS_USER=/path/to/reach/lib/libwhatever.a``.
If you are using Intel MKL_ for FFT, then the BLAS and
over-ridden with ``GMX_BLAS_USER``, etc.
Changing the names of |Gromacs| binaries and libraries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
It is sometimes convenient to have different versions of the same
|Gromacs| programs installed. The most common use cases have been single
and double precision, and with and without MPI. This mechanism can
``_mod``.
Changing installation tree structure
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
By default, a few different directories under ``CMAKE_INSTALL_PREFIX`` are used
when when |Gromacs| is installed. Some of these can be changed, which is mainly
useful for packaging |Gromacs| for various distributions. The directories are
Installed man pages go here.
Compiling and linking
----------------------
+^^^^^^^^^^^^^^^^^^^^^
+
Once you have configured with ``cmake``, you can build |Gromacs| with ``make``.
It is expected that this will always complete successfully, and
give few or no warnings. The CMake-time tests |Gromacs| makes on the settings
.. _building just the mdrun binary:
Building only mdrun
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
This is now supported with the ``cmake`` option
``-DGMX_BUILD_MDRUN_ONLY=ON``, which will build a different version of
the targets for which an mdrun-only build is desirable.
Installing |Gromacs|
---------------------
+^^^^^^^^^^^^^^^^^^^^
+
Finally, ``make install`` will install |Gromacs| in the
directory given in ``CMAKE_INSTALL_PREFIX``. If this is a system
directory, then you will need permission to write there, and you
.. _getting access to |Gromacs|:
Getting access to |Gromacs| after installation
-----------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
|Gromacs| installs the script ``GMXRC`` in the ``bin``
subdirectory of the installation directory
(e.g. ``/usr/local/gromacs/bin/GMXRC``), which you should source
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.
+instructions on how to do this for your shell.
Many of the |Gromacs| programs rely on data installed in the
``share/gromacs`` subdirectory of the installation directory. By
location properly set, or edit the ``GMXRC`` script.
Testing |Gromacs| for correctness
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Since 2011, the |Gromacs| development uses an automated system where
every new code change is subject to regression testing on a number of
platforms and software combinations. While this improves
Testing |Gromacs| for performance
----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
We are still working on a set of benchmark systems for testing
the performance of |Gromacs|. Until that is ready, we recommend that
you try a few different parallelization options, and experiment with
tools such as ``gmx tune_pme``.
Having difficulty?
-------------------
+^^^^^^^^^^^^^^^^^^
+
You are 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
.. _gmx-special-build:
Special instructions for some platforms
-=======================================
+---------------------------------------
Building on Windows
--------------------
+^^^^^^^^^^^^^^^^^^^
+
Building on Windows using native compilers is rather similar to
building on Unix, so please start by reading the above. Then, download
and unpack the |Gromacs| source archive. Make a folder in which to do
the right tools get used.
Building on Cray
-----------------
+^^^^^^^^^^^^^^^^
+
|Gromacs| builds mostly out of the box on modern Cray machines, but
you may need to specify the use of static binaries with
``-DGMX_BUILD_SHARED_EXE=off``, and you may need to set the F77
Building on Solaris
--------------------
+^^^^^^^^^^^^^^^^^^^
The built-in |Gromacs| processor detection does not work on Solaris,
so it is strongly recommended that you build |Gromacs| with
does not currently compile |Gromacs| correctly, perhaps because the
thread-MPI atomics are incorrectly implemented in |Gromacs|).
-Building on BlueGene
---------------------
-
-BlueGene/Q
-^^^^^^^^^^
-There is currently native acceleration on this platform for the Verlet
-cut-off scheme. There are no plans to provide accelerated kernels for
-the group cut-off scheme, but the default plain C kernels will work
-(slowly).
-
-Only the bgclang compiler is supported, because it is the only
-availble C++11 compiler. Only static linking is supported.
-
-Computation on BlueGene floating-point units is always done in
-double-precision. However, mixed-precision builds of |Gromacs| are still
-normal and encouraged since they use cache more efficiently.
-
-You need to arrange for FFTW to be installed correctly, following the
-above instructions. You may prefer to configure FFTW with
-``--disable-fortran`` to avoid complications.
-
-MPI wrapper compilers should be used for compiling and linking. The
-MPI wrapper compilers can make it awkward to
-attempt to use IBM's optimized BLAS/LAPACK called ESSL (see the
-section on `linear algebra libraries`_. Since mdrun is the only part
-of |Gromacs| that should normally run on the compute nodes, and there is
-nearly no need for linear algebra support for mdrun, it is recommended
-to use the |Gromacs| built-in linear algebra routines - this is never
-a problem for normal simulations.
-
-The recommended configuration is to use
-
-::
-
- cmake .. -DCMAKE_C_COMPILER=mpicc \
- -DCMAKE_CXX_COMPILER=mpicxx \
- -DCMAKE_TOOLCHAIN_FILE=Platform/BlueGeneQ-static-bgclang-CXX.cmake \
- -DCMAKE_PREFIX_PATH=/your/fftw/installation/prefix \
- -DGMX_MPI=ON \
- -DGMX_BUILD_MDRUN_ONLY=ON
- make
- make install
-
-which will build a statically-linked MPI-enabled mdrun for the compute
-nodes. Otherwise, |Gromacs| default configuration
-behaviour applies.
-
-It is possible to configure and make the remaining |Gromacs| tools with
-the compute-node toolchain, but as none of those tools are MPI-aware,
-this would not normally
-be useful. Instead, users should plan to run these on the login node,
-and perform a separate |Gromacs| installation for that, using the login
-node's toolchain - not the above platform file, or any other
-compute-node toolchain. This may require requesting an up-to-date
-gcc or clang toolchain for the front end.
-
-Note that only the MPI build is available for the compute-node
-toolchains. The |Gromacs| thread-MPI or no-MPI builds are not useful at
-all on BlueGene/Q.
-
Fujitsu PRIMEHPC
^^^^^^^^^^^^^^^^
+
This is the architecture of the K computer, which uses Fujitsu
Sparc64VIIIfx chips. On this platform, |Gromacs| has
accelerated group kernels using the HPC-ACE instructions, no
Intel Xeon Phi
^^^^^^^^^^^^^^
+
Xeon Phi processors, hosted or self-hosted, are supported.
Only symmetric (aka native) mode is supported on Knights Corner. The
performance depends among other factors on the system size, and for
Tested platforms
-================
+----------------
+
While it is our best belief that |Gromacs| will build and run pretty
much everywhere, it is important that we tell you where we really know
it works because we have tested it. We do test on Linux, Windows, and
have a look at the `continuous integration server used by GROMACS`_,
which runs Jenkins_.
-We test irregularly on ARM v7, ARM v8, BlueGene/Q, Cray, Fujitsu
+We test irregularly on ARM v7, ARM v8, Cray, Fujitsu
PRIMEHPC, Power8, Google Native Client and other environments, and
with other compilers and compiler versions, too.
biod.pnpi.spb.ru / alexxy / gromacs.git / blobdiff