nekRS¶
Overview¶
nekRS is a fast and scalable computational fluid dynamics (CFD) software package targeting massively parallel computers. It is based on the high-order spectral element method and is capable of solving incompressible and low Mach-number fluid flow problems. nekRS uses the OCCA portability layer for offloading compute kernels to GPU devices.
For details about the code and its usage, see the nekRS home page. This page provides information specific to running on Polaris at the ALCF.
Using nekRS at ALCF¶
ALCF provides assistance with build instructions, compiling executables, submitting jobs, and providing prebuilt binaries (upon request). For questions, contact us at support@alcf.anl.gov.
How to Obtain the Code¶
nekRS is an open-source code developed in the Nek5000/nekRS GitHub repository. ALCF maintains a version of nekRS with build scripts for ALCF systems in the argonne-cps/nekRS_alcf repository, and the instructions on this page are based on the v26 branch of that repository:
We encourage users to run their simulations with the v26 branch on both Polaris and Aurora. If you have difficulty using it or need a different version of nekRS, contact support@alcf.anl.gov.
Building on Polaris¶
nekRS uses CMake to build and install the software package. The BuildMe.Polaris script at the top level of the repository loads the required modules, then configures, builds, and installs nekRS:
The script builds in a directory named RBK_built.on.<date> inside the repository (with a symbolic link current pointing to it) and installs nekRS to .local/nekrs in the directory one level above the repository. For example, if the repository was cloned into $HOME/nekRS_alcf, nekRS is installed in $HOME/.local/nekrs. Edit NEKRS_HOME in the script to install elsewhere.
Build on a compute node
The build (hypre, OCCA, Nek5000, and nekRS) is sizable. The per-user limits on the login nodes can cause the build to fail or run slowly, so we recommend building within an interactive job on a compute node, for example in the debug queue.
The script uses the following modules, which must also be loaded when running nekRS (see the job script below):
The cuda/13.0 module must be loaded before craype-accel-nvidia80; the latter does not load without it, and the cudatoolkit-standalone modules do not satisfy this requirement. craype-accel-nvidia80 is needed for the compiler wrappers (cc, CC, ftn) to link the Cray MPICH GPU Transport Layer (GTL) library used for GPU-aware MPI.
If the configuration step was successful, the Summary section of the CMake output shows the Cray compiler wrappers and Default backend : CUDA. After installation, set up the environment:
Alternatively, you may add the above lines to your $HOME/.bashrc and type source $HOME/.bashrc in the current terminal window.
Rebuild after system software upgrades
nekRS records the compilers and flags used at build time in $NEKRS_HOME/nekrs.conf and reuses them to compile kernels and case files at run time. Installations built before the August 2026 Polaris upgrade (which removed gcc-native/13.2 and older Cray PE releases) will not work and must be rebuilt from a clean build directory. Also delete the .cache directory in each case directory; see Just-in-time (JIT) compilation.
Running Jobs on Polaris¶
An example submission script for running a 2-node nekRS job is shown below as an example. Additional information on nekRS input files and application setup options is described here. The correct options to execute the script are as follows:
NEKRS_HOME=</path/to/nekrs/install> PROJ_ID=<project_id> QUEUE=<queue> ./run.sh <casename> <number_of_nodes> <walltime_hh:mm:ss>
Users can copy the script below into a file run.sh, make it executable with chmod +x run.sh, and execute it using the command above.
| run.sh | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | |
Just-in-time (JIT) compilation¶
nekRS uses the OCCA library to translate, compile, and run GPU-targeted functions and kernels. Some useful notes on the cached object files can be found here.
The compiled kernels and case (.udf, .usr) objects are cached in the .cache directory of the case directory by default. After rebuilding or reinstalling nekRS, delete .cache so that stale objects built with the previous installation are not reused.
Discussion Group¶
Users can visit the GitHub Discussions page to seek help, find solutions, share ideas, and follow discussions on several application-specific topics.