Getting started

There are 2 options to get HOS-Ocean:

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 add its location to your system’s PATH.

Pre-built binaries

Pre-built binaries (executables) are available for Linux and Windows platforms on the Releases page. 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:

Note

On Windows, GNU Fortran is available through MinGW-w64 (among other tools).

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

  • LAPACK for linear algebra

  • FFTW3 for Fast Fourier Transforms

Note

Intel’s Math Kernel Library (MKL) can be used as both a LAPACK implementation and a FFTW3 substitute.

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

Compilation

After downloading HOS-Ocean’ sources (either a release version on the Releases page 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:

    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 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:

    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:

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:

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:

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:

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.

  1. Open the Settings

  2. Click on the System category

  3. Go to the About tab on the left

  4. Click on Advanced system settings on the right

  5. In the window that opened, click on the Edit system variables button under the Advanced system settings tab

  6. Select the Path environment variable (either for the current user or for the whole system), and click on the Edit button

  7. In the window that opened, click on the New button to add a line

  8. Enter the name of the directory that contains the HOS-Ocean executable (and library if relevant)

  9. 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:

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

To set the path for all future sessions, use:

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