Installation guide for exotic configurations
********************************************


Special instructions for building GROMACS on less-common systems
================================================================

These instructions pertain to building GROMACS 2024. This document is
complementary to the up-to-date installation instructions
instructions.

The configurations listed here are expected to work, but **are not
recommended for typical users**.


SYCL GPU acceleration for AMD and NVIDIA GPUs using Intel oneAPI DPC++
----------------------------------------------------------------------

AMD and NVIDIA GPUs can also be used with Intel oneAPI BaseKit and
Codeplay oneAPI plugins.

For most users, we recommend using CUDA for NVIDIA GPUs and
AdaptiveCpp for AMD GPUs instead.

With some versions of oneAPI, you might receive "The compiler you are
using does not support OpenMP parallelism" error from CMake. In this
case, please add the following options to your CMake command:

* For oneAPI 2024.x: "-DCMAKE_C_FLAGS="-isystem
  /opt/intel/oneapi/compiler/latest/opt/compiler/include"
  -DCMAKE_CXX_FLAGS="-isystem
  /opt/intel/oneapi/compiler/latest/opt/compiler/include""

* For oneAPI 2023.x: "-DCMAKE_C_FLAGS="-isystem
  /opt/intel/oneapi/compiler/latest/linux/compiler/include"
  -DCMAKE_CXX_FLAGS="-isystem
  /opt/intel/oneapi/compiler/latest/linux/compiler/include""


AMD GPUs
~~~~~~~~

After installing Intel oneAPI toolkit 2023.0 or newer, a compatible
ROCm version, and the Codeplay plugin, set up the environment by
running "source /opt/intel/oneapi/setvars.sh --include-intel-llvm" or
loading an appropriate **module load** on an HPC system.

Then, configure GROMACS using the following command (replace "gfxXYZ"
with the target architecture):

   cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
            -DGMX_GPU=SYCL -DGMX_SYCL=DPCPP \
            -DGMX_GPU_NB_CLUSTER_SIZE=8 -DGMX_GPU_FFT_LIBRARY=vkfft \
            -DSYCL_CXX_FLAGS_EXTRA='-fsycl-targets=amdgcn-amd-amdhsa;-Xsycl-target-backend;--offload-arch=gfxXYZ'


NVIDIA GPUs
~~~~~~~~~~~

After installing Intel oneAPI toolkit 2023.0 or newer, a compatible
CUDA version, and the Codeplay plugin, set up the environment by
running "source /opt/intel/oneapi/setvars.sh --include-intel-llvm" or
loading an appropriate **module load** on an HPC system.

   Then, configure GROMACS using the following command:

   cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
            -DGMX_GPU=SYCL -GMX_SYCL=DPCPP \
            -DGMX_GPU_NB_CLUSTER_SIZE=8 -DGMX_GPU_FFT_LIBRARY=vkfft \
            -DSYCL_CXX_FLAGS_EXTRA=-fsycl-targets=nvptx64-nvidia-cuda


SYCL GPU acceleration for NVIDIA GPUs using AdaptiveCpp (hipSYCL)
-----------------------------------------------------------------

For most users, we recommend using CUDA for NVIDIA GPUs.

Build and install AdaptiveCpp with CUDA backend (we recommend using
the mainline Clang, not the ROCm-bundled one).

Then, use the following command to build GROMACS (make sure to use the
same compiler and set target GPU architecture instead of "sm_XY"):

   cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
            -DGMX_GPU=SYCL -DGMX_SYCL=ACPP -DHIPSYCL_TARGETS='cuda:sm_XY'


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 recommended or even necessary, most commonly when
you are running large parallel simulation using MPI libraries (e.g.
Cray).

* To link GROMACS binaries statically against the internal GROMACS
  libraries, set "-DBUILD_SHARED_LIBS=OFF".

* To link statically against external (non-system) libraries as well,
  set "-DGMX_PREFER_STATIC_LIBS=ON". 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 on platforms where that
  is the default. To use static system libraries, additional
  compiler/linker flags are necessary, e.g. "-static-libgcc -static-
  libstdc++".

* To attempt to link a fully static binary set
  "-DGMX_BUILD_SHARED_EXE=OFF". This will prevent CMake from
  explicitly setting any dynamic linking flags. This option also sets
  "-DBUILD_SHARED_LIBS=OFF" and "-DGMX_PREFER_STATIC_LIBS=ON" by
  default, but the above caveats apply. For compilers which don't
  default to static linking, the required flags have to be specified.
  On Linux, this is usually "CFLAGS=-static CXXFLAGS=-static".


Building on Solaris
-------------------

The built-in GROMACS processor detection does not work on Solaris, so
it is strongly recommended that you build GROMACS with
"-DGMX_HWLOC=on" and ensure that the "CMAKE_PREFIX_PATH" includes the
path where the hwloc headers and libraries can be found. At least
version 1.11.8 of hwloc is recommended.
