NEK5000

NEK5000 is a spectral-element CFD code developed at Argonne National Laboratory. It solves the incompressible Navier-Stokes equations on unstructured quadrilateral (2-D) and hexahedral (3-D) meshes with high-order polynomial bases. HydroGym's NEK5000 backend currently provides a turbulent channel flow environment at $Re_{\tau} = 180$.

System requirements

Requirement	Notes
C compiler	GCC is recommended (gcc)
Fortran compiler	GFortran is required (gfortran)
GNU Make	Standard system package
MPI	OpenMPI or MPICH — required for all HydroGym runs
CMake	Optional, needed only for NekTools
X11 libraries	Optional, needed only for the visnek visualisation tool

Install system packages (Ubuntu / Debian)

sudo apt-get update
sudo apt install build-essential       # gcc, make
sudo apt install gfortran              # Fortran compiler
sudo apt install libopenmpi-dev        # MPI
sudo apt install cmake libx11-dev libxt-dev  # optional: NekTools + visnek

Building NEK5000

Clone the repository and add the bin/ directory to your PATH:

cd ~
git clone https://github.com/Nek5000/Nek5000.git
export PATH=$HOME/Nek5000/bin:$PATH

To make the PATH change permanent, add the export line to your ~/.bashrc (or ~/.zshrc) and start a new shell session.

Build the mesh partitioner and any other tools you need:

cd ~/Nek5000/tools
./maketools genmap     # mesh partitioner (required)

Verify the build

Download the bundled examples and run a short test case on 2 MPI ranks:

cd ~
git clone https://github.com/Nek5000/NekExamples.git
cp -r ~/NekExamples/eddy_uv .
cd eddy_uv

genmap                  # partition the mesh (input: eddy_uv)
makenek eddy_uv         # compile the case
nekbmpi eddy_uv 2       # run on 2 MPI ranks
tail logfile            # check solver output

A successful run prints residual and timing information for each time step.

Install the HydroGym Python package

Once NEK5000 is on your PATH, install the HydroGym NEK extras:

pip install hydrogym[nek]

This adds mpi4py, omegaconf, pymech, pettingzoo, stable-baselines3, supersuit, and tensorboard alongside the core package.

Running HydroGym with NEK5000

NEK5000 environments use MPMD (Multiple Program Multiple Data) execution: the Python RL controller and the NEK5000 solver are launched as separate MPI programs in the same mpirun command, connected via an inter-communicator:

mpirun -np 1 python test_nek_direct.py --steps 100 : -np 10 nek5000

The : -np 10 nek5000 part starts 10 NEK5000 solver ranks in the same MPI job. Adjust the count to match the mesh partition you compile for your case.

Loading pre-packaged environments from HuggingFace Hub

HydroGym can download pre-configured NEK5000 case files (mesh, boundary conditions, and environment configuration) from HuggingFace Hub:

from hydrogym.nek import NekEnv

env = NekEnv.from_hf('TCFmini_3D_Re180', nproc=10)
obs, info = env.reset()

For offline HPC use, download the environment package on a login node and pass local_fallback_dir:

env = NekEnv.from_hf(
    'TCFmini_3D_Re180',
    nproc=10,
    local_fallback_dir='/scratch/$USER/nek_envs',
)

NEK5000 version note

HydroGym is tested against the master branch of Nek5000/Nek5000. The master branch is recommended over release tarballs because using git clone makes it straightforward to pull in bug fixes:

cd ~/Nek5000
git pull origin master