Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

REEF3D (Installation)

REEF3D is an open-source hydrodynamics framework for free-surface CFD, wave modelling, non-hydrostatic flow, and shallow-flow applications. It is relevant for hydraulic and coastal engineering cases where local 3D flow, hydraulic structures, complex bathymetry, or sediment transport are important.

This page describes a practical source-build workflow for Debian-based Linux systems, including Debian, Ubuntu, Linux Mint, LMDE, Lubuntu, and similar distributions. The workflow below was checked against the current upstream GitHub layout and release information on 2026-06-26. Upstream changes are frequent, so treat hard-coded version numbers as examples rather than permanent installation instructions.

Installation elements

A typical local setup needs two executables:

REEF3D is parallelized with MPI and currently builds with mpicxx. DIVEMesh is a separate repository and builds with g++.

Automatic installation with a helper script

For most Debian-based desktop or workstation installations, the easiest route is to use the REEF3D helper script instead of running the manual commands below. The script detects the Linux distribution, installs the required system packages, downloads the latest GitHub releases of DIVEMesh and REEF3D, patches the known Debian/Ubuntu/Mint Makefile path issues, compiles both programs, and optionally creates a desktop launcher.

The short version

Download the installer script install_reef3d.sh, then run:

chmod +x install_reef3d.sh
./install_reef3d.sh

At the end of an interactive installation, the script asks whether to create a desktop/menu launcher. Answer Y to create it. On non-interactive systems, or if the answer should be fixed in advance, use:

REEF3D_CREATE_DESKTOP=1 ./install_reef3d.sh

By default, the script installs REEF3D and DIVEMesh under:

~/opt/reef3d

It also creates symbolic links in:

~/.local/bin

After the installation, check that the executables are visible:

which REEF3D
which DiveMESH
REEF3D || true
DiveMESH || true

If which REEF3D or which DiveMESH returns nothing, open a new terminal or add ~/.local/bin to the shell PATH:

export PATH="$HOME/.local/bin:$PATH"

Customization

A custom installation directory can be selected with --prefix:

./install_reef3d.sh --prefix "$HOME/software/reef3d"

To control the number of parallel compiler jobs, use -j or --jobs:

./install_reef3d.sh -j 8

To force a clean rebuild, use:

./install_reef3d.sh --force

To explicitly skip the desktop launcher, use:

REEF3D_CREATE_DESKTOP=0 ./install_reef3d.sh

The following sections describe what the script does internally and are useful for troubleshooting failed builds.

Step-by-step installation

Install system packages

Update the package index and install the build toolchain, MPI, HYPRE, and Eigen:

sudo apt update
sudo apt install \
  build-essential gfortran git wget ca-certificates pkg-config dpkg-dev \
  libopenmpi-dev openmpi-bin \
  libhypre-dev libeigen3-dev

Optional but useful packages:

sudo apt install paraview htop tree

Check that the important tools are visible:

g++ --version
mpicxx --version
which mpicxx
mpirun --version

Check where Debian/Ubuntu installed HYPRE and Eigen:

dpkg -L libhypre-dev | grep -E 'HYPRE\.h|libHYPRE\.so'
dpkg -L libeigen3-dev | grep 'Eigen/Dense' | head

On Debian/Ubuntu/Mint systems, HYPRE headers are usually under /usr/include/hypre, while the library is normally under a multi-arch path such as /usr/lib/x86_64-linux-gnu/. This is why the upstream REEF3D Makefile often needs a local path adjustment.

Get the source code

Use Git rather than a random source archive when possible. The current REEF3D Makefile inserts Git branch and commit metadata into the build, so a Git checkout avoids confusing version strings.

mkdir -p ~/src
cd ~/src

git clone https://github.com/REEF3D/REEF3D.git
git clone https://github.com/REEF3D/DIVEMesh.git

List available REEF3D versions:

cd ~/src/REEF3D
git tag --sort=-v:refname | head

For a reproducible installation, check out a specific release tag instead of building whatever happens to be on master:

# Example only. Replace with the release tag you want to use.
git checkout 26.05

Build DIVEMesh

DIVEMesh is separate from REEF3D and should be built first:

cd ~/src/DIVEMesh
make clean
make -j"$(nproc)"

The expected executable is:

ls -lh bin/DiveMESH

If you want the executable available system-wide:

sudo install -m 755 bin/DiveMESH /usr/local/bin/DiveMESH

DIVEMesh compiler-line fix

At the time of checking, the upstream DIVEMesh Makefile contained:

CXX := -g++

That is not a valid compiler command on a normal Debian/Ubuntu/Mint shell. If your build fails with a message such as -g++: command not found, patch the line:

cd ~/src/DIVEMesh
sed -i 's/^CXX := -g++/CXX := g++/' Makefile
make clean
make -j"$(nproc)"

Build REEF3D with Debian/Ubuntu/Mint system packages

The current upstream REEF3D Makefile assumes HYPRE is installed under /usr/local/hypre and uses bundled Eigen from ThirdParty/eigen-3.3.8. Debian/Ubuntu/Mint packages install HYPRE elsewhere, so adjust the Makefile before compiling. Do not paste older Makefile snippets that set CXXFLAGS to -std=c++11; the current upstream Makefile uses CXXFLAGS := -std=c++17 ....

From the REEF3D source directory:

cd ~/src/REEF3D
cp Makefile Makefile.orig

Patch the HYPRE paths while keeping the upstream C++17 setting:

python3 - <<'PY'
from pathlib import Path

p = Path("Makefile")
s = p.read_text()

s = s.replace("HYPRE_DIR := /usr/local/hypre", "HYPRE_DIR := /usr")
s = s.replace(
    "LDFLAGS := -L ${HYPRE_DIR}/lib/ -lHYPRE",
    "LIBDIR := /usr/lib/$(shell dpkg-architecture -qDEB_HOST_MULTIARCH)\nLDFLAGS := -L $(LIBDIR) -lHYPRE",
)
s = s.replace(
    "INCLUDE := -I ${HYPRE_DIR}/include -I ${EIGEN_DIR} -DEIGEN_MPL2_ONLY",
    "INCLUDE := -I /usr/include/hypre -I ${EIGEN_DIR} -DEIGEN_MPL2_ONLY",
)

p.write_text(s)
PY

Then compile:

make clean
make release -j"$(nproc)"

The expected executable is:

ls -lh bin/REEF3D

For a user-local installation, add both executable directories to your shell path:

cat >> ~/.bashrc <<'EOF'

# REEF3D local build
export PATH="$HOME/src/REEF3D/bin:$HOME/src/DIVEMesh/bin:$PATH"
EOF

source ~/.bashrc

Then check:

which REEF3D
which DiveMESH

Alternative: build HYPRE manually under /usr/local/hypre

The upstream Dockerfile builds OpenMPI and HYPRE from source and installs HYPRE under /usr/local/hypre. That matches REEF3D’s default Makefile more closely, but it is more invasive on a workstation.

Use the manual /usr/local/hypre route only when you need a specific HYPRE version or when the distribution package causes solver/linker problems. For normal Debian, Ubuntu, and Mint workstations, prefer libhypre-dev first.

Test

Before setting up any project, run a small upstream tutorial or example case from the REEF3D Tutorials directory:

cd ~/src/REEF3D/Tutorials
find . -maxdepth 2 -type f | head

Follow the instructions shipped with the selected tutorial. Do not start debugging your own STL geometry, bathymetry, turbulence settings, and boundary conditions before confirming that the binary works on a small upstream case.

MPI run notes

For parallel runs, use mpirun or mpiexec according to the tutorial or case setup:

mpirun -np 4 REEF3D

Do not run MPI jobs with sudo. OpenMPI blocks root execution by default for a reason. The upstream Dockerfile sets OMPI_ALLOW_RUN_AS_ROOT variables because containers often run as root; that workaround belongs in containers, not on normal workstations.

Troubleshooting

mpicxx: command not found

Install OpenMPI development packages:

sudo apt install libopenmpi-dev openmpi-bin
which mpicxx

fatal error: HYPRE.h: No such file or directory

The HYPRE include path is wrong or libhypre-dev is missing.

sudo apt install libhypre-dev
dpkg -L libhypre-dev | grep HYPRE.h

Make sure the REEF3D Makefile contains:

INCLUDE := -I /usr/include/hypre -I ${EIGEN_DIR} -DEIGEN_MPL2_ONLY

/usr/bin/ld: cannot find -lHYPRE

The linker is not searching the Debian/Ubuntu multi-arch library directory.

dpkg -L libhypre-dev | grep libHYPRE.so
dpkg-architecture -qDEB_HOST_MULTIARCH

Make sure the REEF3D Makefile contains something equivalent to:

LIBDIR := /usr/lib/$(shell dpkg-architecture -qDEB_HOST_MULTIARCH)
LDFLAGS := -L $(LIBDIR) -lHYPRE

fatal error: Eigen/Dense: No such file or directory

REEF3D normally points to bundled Eigen:

EIGEN_DIR := ThirdParty/eigen-3.3.8

If that folder is missing, use the system Eigen path instead:

EIGEN_DIR := /usr/include/eigen3

Then rebuild:

make clean
make release -j"$(nproc)"

Build fails after changing branches or tags

Clean the build directory:

make clean
make release -j"$(nproc)"

If that still fails, restore the original Makefile and reapply only the HYPRE path patch:

cp Makefile.orig Makefile

Binary crashes on another computer

The upstream release target uses -march=native. That can create binaries optimized for the CPU on which they were compiled. If you compile on one machine and run on another, build with the less aggressive target:

make clean
make all -j"$(nproc)"

Alternatively, edit the release target and remove -march=native before compiling for a cluster with mixed CPU generations.

Version check / recording

For reproducibility, record the exact state/version:

cd ~/src/REEF3D
git rev-parse --short HEAD
git status --short
mpicxx --version
mpirun --version
ldconfig -p | grep HYPRE || true

Store the REEF3D tag/commit, operating system version, compiler version, MPI version, and Makefile patch with the simulation case documentation.

REEF3D sources

Software Resources
TELEMAC (Auto-Installation)
Software Resources
Native Compilation of Delft3D-FLOW on Ubuntu and Linux Mint