Getting started
=================

There are 2 options to get `HOS-Ocean`:

* Downloading :ref:`getting-started:Pre-built binaries` for your platform (if available)
* :ref:`getting-started:Building HOS-Ocean locally` from sources directly on your computer

To be able to use the program from anywhere on your system without using the full path to the binary file, you might want to :ref:`add its location to your system's PATH <getting-started:Setting the system's PATH>`.

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

Pre-built binaries (executables) are available for Linux and Windows platforms on `the Releases page <https://gitlab.com/lheea/HOS-Ocean/-/releases>`__.
Simply download the archive, expand it, and cut/paste the binary files wherever is suitable for you.


Building HOS-Ocean locally
~~~~~~~~~~~~~~~~~~~~~~~~~~

Dependencies
^^^^^^^^^^^^

The following tools are required to build `HOS-Ocean`:

* `CMake <https://cmake.org/>`__ as the build system generator
* A Fortran compiler, such as `GNU Fortran <https://gcc.gnu.org/fortran/>`__ or `Intel Fortran <https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler.html>`__

.. note::

    On Windows, GNU Fortran is available through `MinGW-w64 <https://www.mingw-w64.org/>`__ (among other tools).


The following libraries are used by `HOS-Ocean` and must be present on your system for CMake to detect them.:

* `LAPACK <https://www.netlib.org/lapack/>`__ for linear algebra
* `FFTW3 <https://www.fftw.org/>`__ for Fast Fourier Transforms

.. note::

    `Intel's Math Kernel Library (MKL) <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`__ can be used as both a LAPACK implementation and a FFTW3 substitute.

Optionally, the following libraries can be installed to enable corresponding features:

* A `MPI distribution <https://www.mpi-forum.org/>`__ for multi-processor computation,
* The `HDF5 library <https://www.hdfgroup.org/solutions/hdf5/>`__ to enable HDF5 output files.

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

After downloading `HOS-Ocean`' sources (either a release version on `the Releases page <https://gitlab.com/lheea/HOS-Ocean/-/releases>`__ or a Git clone), open a console at the root of the directory (where the ``CMakeLists.txt`` file is).

1. Configure the project

    This will check the dependencies and prepare the compilation in the ``build`` directory:

    .. sourcecode:: console

        cmake -S. -Bbuild

    The following options can be added with ``-D<option>=ON`` to customize the compilation:

    * ``USE_MPI``: enables multi-processor computations with `MPI <https://www.mpi-forum.org/>`,
    * ``USE_HDF5``: enables `HDF5 <https://www.hdfgroup.org/solutions/hdf5/>` output files,
    * ``ALLOW_MKL``: allows to use `MKL <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`__ instead of LAPACK and FFTW3.

    Other CMake standard options can be used (e.g. ``CMAKE_BUILD_TYPE``).
    Please refer to CMake's documentation for further details.

    .. warning::

        Changing some options might require a fresh build to be changed properly.
        To make a fresh build, delete the ``build`` directory and re-run the configuration command.

2. Build the project

    This will compile all the sources into executable programs:

    .. sourcecode:: console

        cmake --build build -j

    Once this process is finished, and provided no error occurred (a few warnings are expected), the executables can be found in the ``build`` directory.

    .. note:: The CMake ``-j`` option enables multi-processor compilation (faster).

Installation
^^^^^^^^^^^^

The final step is to install the compiled files on your computer.
To do so, run the following command:

.. sourcecode:: console

    cmake --install build

CMake will automatically choose the proper location on your system (e.g. in ``/usr/local`` on most Linux distributions, in ``C:\Program Files`` on Windows).
On Linux, this location is usually already in the system's ``PATH``.
On Windows however, you will need to add the install location to your system's ``PATH`` if you want to be able to use the program from anywhere on your system.

.. note::

    On Linux, the standard location (``/usr/local``) will likely be write-protected. Use ``sudo`` or choose another location.

    If you don't have administrative rights, a common location for user-installed programs is ``/home/<user>/.local``, however this location is not necessarily already in the system's ``PATH``.

Alternatively, you can specify the installation location with the ``--prefix`` option.
For example, if you want to install `HOS-Ocean` in a subdirectory named ``install``:

.. sourcecode:: console

    cmake --install build --prefix install

Setting the system's PATH
~~~~~~~~~~~~~~~~~~~~~~~~~

In this section, ``<program-directory>`` refers to the directory containing the `HOS-Ocean` executable (and/or library if relevant).

Linux
^^^^^

One can **temporarily** add the location (``<program-directory>``) of an executable to the system's `PATH` with the following command:

.. sourcecode:: bash

    export PATH=$PATH:<program-directory>

To **permanently** set the system's ``PATH``, the usual method is to add the command to one's profile script.
For example, if you use ``bash`` as your shell:

.. sourcecode:: bash

    echo 'export PATH=$PATH:<program-directory>' >> ~/.bashrc


Windows
^^^^^^^

Graphically
'''''''''''

.. note:: This procedure requires administrator rights. Use the command prompt if you do not have them.

#. Open the ``Settings``
#. Click on the ``System`` category
#. Go to the ``About`` tab on the left
#. Click on ``Advanced system settings`` on the right
#. In the window that opened, click on the ``Edit system variables`` button under the ``Advanced system settings`` tab
#. Select the ``Path`` environment variable (either for the current user or for the whole system), and click on the ``Edit`` button
#. In the window that opened, click on the ``New`` button to add a line
#. Enter the name of the directory that contains the `HOS-Ocean` executable (and library if relevant)
#. Save the changes by closing all the parameters windows with the ``OK`` buttons

Using the command prompt
''''''''''''''''''''''''

Open the standard command prompt (``cmd``).

To set the path for **the current command prompt session only**, use:

.. code:: winbatch

    set path=%path%;C:<program-directory>

To set the path for **all future sessions**, use:

.. code:: winbatch

    setx path "%path%;<program-directory>"