Installation
============

Pre-built binaries
------------------

Pre-built binaries (library and executables) for several systems can be downloaded from the `Releases page <https://gitlab.com/lheea/Grid2Grid/-/releases>`__.

Building from source
--------------------

Dependencies
~~~~~~~~~~~~

To compile Grid2Grid, you will need the following tools:

- `CMake <https://cmake.org/>`_
- A Fortran compiler (e.g. `GNU Fortran <https://gcc.gnu.org/fortran/>`_)

Additionally, Grid2Grid relies on the following library, which is expected to be present on the system (are is generally easily installed via package managers):

- `FFTW3 <http://www.fftw.org/>`_

.. note:: When compiling with Intel Fortran, the MKL library can be used as a FFTW3 implementation. To enable this, the ``ALLOW_MKL`` CMake option must be set to ``ON`` (see :ref:`installation:Build Grid2Grid`).

Optionally, Grid2Grid can be compiled with the following libraries for additional features (also generally available via package managers):

- `HDF5 <https://www.hdfgroup.org/solutions/hdf5/>`_
- MPI (e.g. `OpenMPI <https://www.open-mpi.org/>`_)

The following libraries are used by Grid2Grid but are automatically downloaded and compiled during the build process:

- `bspline-fortran <https://github.com/jacobwilliams/bspline-fortran>`__
- `EaFort <https://gitlab.com/MASELA/EaFort>`__, a collection and wrapper for other libraries

While they are not direct dependencies, Grid2Grid is designed to work on the output of HOS-NWT and HOS-Ocean:

- HOS-NWT: `repository <https://gitlab.com/lheea/HOS-NWT>`__, `documentation <https://lheea.gitlab.io/HOS-NWT/>`__ and `latest release <https://gitlab.com/lheea/HOS-NWT/-/releases/permalink/latest>`__
- HOS-Ocean: `repository <https://gitlab.com/lheea/HOS-Ocean>`__, `documentation <https://lheea.gitlab.io/HOS-Ocean/>`__ and `latest release <https://gitlab.com/lheea/HOS-Ocean/-/releases/permalink/latest>`__


Download Grid2Grid
~~~~~~~~~~~~~~~~~~

The source code of the latest Grid2Grid release can be downloaded from the `Releases page <https://gitlab.com/lheea/Grid2Grid/-/releases/permalink/latest>`__ or cloned using Git from the `GitLab repository <https://gitlab.com/lheea/Grid2Grid>`__.

Build Grid2Grid
~~~~~~~~~~~~~~~

Options
^^^^^^^

To compile Grid2Grid with additional features, the following options can be passed to CMake:

- ``BUILD_SHARED_LIBS`` (default: ``ON``): Build shared libraries (only build the static version if you know what you are doing)
- ``MPI_SUPPORT`` (default: ``ON``): Build with MPI Parallelization
- ``HDF5_SUPPORT`` (default: ``OFF``): Build with HDF5 file format support
- ``ALLOW_MKL`` (default: ``OFF``): Allows MKL to be used as a FFTW3 implementation (mainly useful when compiling with Intel Fortran)

To pass one of these options to CMake, use ``-D<option_name>=<option_value>`` during the configuration step.

Compilation
^^^^^^^^^^^

To compile Grid2Grid, follow these steps:

1. Configure the build with CMake:

.. code-block:: bash

    cmake -S. -Bbuild

.. note:: If you want to enable additional features, pass the corresponding options to CMake. For example, to enable HDF5 support, use ``cmake -S. -Bbuild -DHDF5_SUPPORT=ON``.

2. Compile the code:

.. code-block:: bash

    cmake --build build

3. optionally, install the compiled binaries:

.. code-block:: bash

    cmake --install build

.. note:: By default, the binaries will be installed in an appropriate location selected by CMake depending on the system. To install them in a different location, use the ``--prefix`` option when configuring the build with CMake. For example, to install the binaries in a local ``install`` directory, use ``cmake --install build --prefix install``.

    To install Grid2Grid for OpenFOAM, use:

    .. code-block:: bash

       cmake --install build --prefix $FOAM_USER_LIBBIN/..