| OS | Arch | Compiler | MPI | Status |
|---|---|---|---|---|
| Ubuntu 24.04 | x86_64 | gfortran 14 | OpenMPI / MPICH | |
| Ubuntu 24.04 | x86_64 | ifort 2024 / ifx 2025 | Intel MPI | |
| macOS 15 | ARM64 | gfortran 14 | OpenMPI |
nekStab is a toolbox for global stability and bifurcation analysis using the spectral element solver Nek5000. Released under BSD-3-Clause license.
| Method | Description |
|---|---|
| SFD | Selective Frequency Damping for unstable steady states |
| BoostConv | Residual acceleration for slow convergence |
| TDF | Time-Delayed Feedback for periodic orbits |
| Newton-Krylov | Quadratic convergence for fixed points, UPOs (natural frequency), and forced periodic orbits |
| Analysis | Steady Flows | Time-Periodic (Floquet) |
|---|---|---|
| Direct eigenmodes | ✓ | ✓ |
| Adjoint eigenmodes | ✓ | ✓ |
| Transient growth | ✓ | ✓ |
- Wavemaker — structural sensitivity to feedback
- Energy budget — production, dissipation, transport decomposition (steady + Floquet)
- Base flow sensitivity — response to mean flow modifications
- Steady force sensitivity — optimal placement for passive control
- Mode animation — reconstruct eigenmode dynamics over one period
| Method | Description |
|---|---|
| POD | Proper Orthogonal Decomposition (energy-ranked modes) |
| DMD | Dynamic Mode Decomposition (frequency-ranked modes) |
| SPOD | Spectral POD (frequency-resolved coherent structures) |
- OTD modes — real-time Lyapunov vectors for chaotic flows
- Linearized DNS — perturbation evolution around base flows
- Scalar transport — temperature and passive scalar stability
- Sponge zones — non-reflecting boundaries for open flows
- Vortex identification — λ₂, Q-criterion, Ω-criterion output
- FFT module — FFTW3/MKL integration for spectral analysis with Nek5000
- Matrix-free: No Jacobian storage — scales to millions of DoFs
- Krylov-based: Time-stepper as linear operator — eigenvalues from snapshots
- Spectral accuracy: Leverages Nek5000's high-order elements
- MPI parallel: Efficient on laptops to supercomputers
- Validated: Automated test suite covering 9 solver modes across 4 geometries (cylinder, backstep, flip-flop, jet)
- FFT included: Smart linking to FFTW3 (GCC) or MKL (Intel) — no manual setup
| Mode | String | Aliases | Description |
|---|---|---|---|
| 0 | 'dns' |
Direct Numerical Simulation | |
| 0.1 | 'linear_dns' |
'lindns' |
Linearized DNS (perturbation) |
| 1.1 | 'sfd' |
Selective Frequency Damping | |
| 1.2 | 'boostconv' |
'boost' |
BoostConv acceleration |
| 1.4 | 'tdf' |
Time-Delayed Feedback | |
| 2 | 'newton_fp' |
'newton' |
Newton for fixed points |
| 2.1 | 'newton_po' |
'upo' |
Newton for periodic orbits (unknown period) |
| 2.2 | 'newton_po_t' |
'forced_upo' |
Newton for periodic orbits (forced period) |
| 3.1 | 'direct' |
Direct stability eigenmodes | |
| 3.11 | 'floquet_direct' |
Floquet direct analysis | |
| 3.2 | 'adjoint' |
Adjoint stability eigenmodes | |
| 3.21 | 'floquet_adjoint' |
Floquet adjoint analysis | |
| 3.3 | 'transient_growth' |
'tg' |
Optimal perturbations |
| 3.31 | 'floquet_tg' |
Floquet transient growth | |
| 4.1 | 'energy_budget' |
Kinetic energy budget | |
| 4.11 | 'energy_budget_floquet' |
Floquet energy budget | |
| 4.2 | 'wavemaker' |
Structural sensitivity | |
| 4.3 | 'bf_sensitivity' |
Base flow sensitivity | |
| 4.41 | 'force_sensitivity_real' |
Steady force sensitivity (real) | |
| 4.42 | 'force_sensitivity_imag' |
Steady force sensitivity (imag) | |
| 4.43 | 'delta_forcing' |
Delta forcing response | |
| 4.5 | 'animate_mode' |
'animate' |
Mode animation |
| 4.51 | 'animate_bf_deform' |
Base flow deformation animation | |
| 4.52 | 'animate_floquet' |
Floquet mode animation | |
| 5 | 'otd' |
Optimally Time-Dependent modes | |
| 6.1 | 'pod' |
Proper Orthogonal Decomposition | |
| 6.2 | 'dmd' |
Dynamic Mode Decomposition | |
| 6.3 | 'spod' |
Spectral POD |
See DOC.md for full parameter reference.
Ready-to-run cases live under example/, from canonical cylinder workflows to
thermal, airfoil, cavity, channel, and Floquet examples.
See EXAMPLES.md for the stage rationale, case catalog, and
public validation status.
Prerequisites
Linux (GCC)
sudo apt -y install build-essential gfortran libmpich-dev libopenblas-dev libfftw3-dev cmake m4 htopmacOS
brew install mpich gfortran fftw wget git cmake htopInstallation
git clone --depth=1 https://github.com/nekStab/nekStab.git
cd nekStab
./Nek5000setup.sh| Command | What it does |
|---|---|
git clone --depth=1 ... |
Downloads only the latest version (fastest, minimal download) |
cd nekStab |
Enter the nekStab directory |
./Nek5000setup.sh |
Downloads and configures Nek5000 inside nekStab/Nek5000/ |
Already have Nek5000? Skip
./Nek5000setup.shand pointNEK_SOURCE_ROOTto your existing installation (see below).
Add to your shell config (~/.bashrc or ~/.zshrc):
# nekStab path
export NEKSTAB_SOURCE_ROOT=$HOME/nekStab
export PATH=$NEKSTAB_SOURCE_ROOT/bin:$PATH
# Nek5000 path (adjust if using existing installation)
export NEK_SOURCE_ROOT=$NEKSTAB_SOURCE_ROOT/Nek5000 # ← or your existing path
export PATH=$NEK_SOURCE_ROOT/bin:$PATH
# Stack/core limits for large simulations
ulimit -s unlimited
ulimit -c unlimited| Variable / Setting | Purpose |
|---|---|
NEKSTAB_SOURCE_ROOT |
Location of nekStab source (build scripts reference this) |
NEK_SOURCE_ROOT |
Location of Nek5000 (required by Nek5000 build system) |
PATH additions |
Makes mks, nekbmpi, genmap, etc. available anywhere |
ulimit -s unlimited |
Removes stack size limit — prevents crashes in large runs |
ulimit -c unlimited |
Enables core dumps for debugging crashes |
Then reload: source ~/.bashrc (or restart terminal).
Enable tab completion for case names and common mks targets/options:
source "$NEKSTAB_SOURCE_ROOT/bin/mks-completion.bash"For zsh, load Bash completion first:
autoload -Uz bashcompinit && bashcompinit
source "$NEKSTAB_SOURCE_ROOT/bin/mks-completion.bash"Go to a given example folder and compile the code:
cd ~/nekStab/example/cylinder_re100/210_baseflow_newton/fp
mks 1cylnekStab supports multiple Fortran compilers. The build script auto-detects available compilers in this order: ifx → ifort → gfortran. To force a specific compiler:
NEKSTAB_FC=ifx mks 1cyl # Intel LLVM (recommended for Intel/AMD CPUs)
NEKSTAB_FC=ifort mks 1cyl # Intel Classic (available on many HPC systems)
NEKSTAB_FC=gcc mks 1cyl # GCC/gfortran| Compiler | Performance | Notes |
|---|---|---|
| ifx (Intel LLVM) | Fastest | Requires Intel oneAPI 2024+, uses MKL |
| ifort (Intel Classic) | Fast | Available on HPC systems, discontinued in oneAPI 2025 |
| gfortran (GCC) | Good | Universal, uses system BLAS/LAPACK |
Note: Intel discontinued
ifortin oneAPI 2025, but it remains available on many HPC systems. New installations should useifx.
The Intel compilers use MKL (Math Kernel Library) which provides highly optimized BLAS/LAPACK routines with runtime CPU dispatching.
For debugging crashes or numerical issues:
mks 1cyl --debug| What it enables | Why it helps |
|---|---|
Debug symbols (-g) |
Use gdb to inspect variables and step through code |
Stack traces (-fbacktrace) |
See exact file:line when a crash occurs |
Compiler warnings (-Wall) |
Catch uninitialized variables, type mismatches |
Tip: When a crash happens in debug mode, the output shows which subroutine and line number failed — much easier than hunting through a release build.
After successful compilation:
nekbmpi 1cyl 4 # Run case "1cyl" on 4 MPI processes
tail -f logfile # Monitor output in real-time
killall nek5000 # Stop the simulation| Command | What it does |
|---|---|
nekbmpi 1cyl 4 |
Launches nek5000 via mpirun with 4 processes (adjust to your CPU cores) |
tail -f logfile |
Streams solver output — watch convergence, time steps, diagnostics |
killall nek5000 |
Gracefully stops all running Nek5000 processes |
Tip: Use
nekbmpi 1cyl 4 &to run in background, thentail -f logfilein the same terminal.
For more information, see the Documentation.
Three equivalent ways to select operating mode:
| Method | Where | Example |
|---|---|---|
| String | .usr |
nekstab_mode = 'floquet_adjoint' |
| Flags | .usr |
isAdjoint = .true. + ifFloquet = .true. |
| uparam | .par |
userParam01 = 3.21 |
nekStab is maintained by Ricardo Frantz.
See FORTRAN_STYLE.md for the current Fortran coding style conventions and guiding principles.
See also: LightKrylov is a modern Fortran library providing abstract Krylov methods. neklab is the next-generation bifurcation and stability analysis toolbox for Nek5000, built on LightKrylov. Both are actively developed by Jean-Christophe Loiseau and Simon Kern.
Website: https://nekstab.github.io/
Several capabilities in nekStab started from work shared by others:
- The free-stream turbulence inflow generation builds on original work by M. A. Bucci.
- The optimally time-dependent (OTD) modes capability grew out of groundwork contributed by Simon Kern (KTH); the implementation follows Babaee & Sapsis (2016).
- The sponge/fringe damping was first prototyped against the KTH Toolbox and follows Nordström, Nordin & Henningson (1999) and Lundbladh et al. (1999).
The full list of authors and contributors is in AUTHORS.
When using nekStab, please cite Frantz et al. (2023). See CITATIONS.md for BibTeX entries and additional references.