Skip to content
erf-modelPublic

About

Grid-sequenced Unified Steady Terrain solver (GUST) - A Steady RANS Solver for Atmospheric Boundary Layer simulations using AMReX

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

GUST

CI Docs

GUST (Grid-sequenced Unified Steady Terrain solver) computes steady wind fields over complex terrain. It is a steady Reynolds-averaged Navier–Stokes (RANS) solver for the atmospheric boundary layer, built on AMReX, and one code base builds for CPUs and GPUs (CUDA, HIP, SYCL).

What it does

  • Two answers from one input file. A mass-consistent wind in seconds (stop after the initializer), or the converged steady RANS solution in minutes.
  • Steady solver. SIMPLEC pressure–velocity coupling with implicit vertical line relaxation (line LU-SGS), local pseudo-time stepping with switched-evolution relaxation, and grid sequencing over coarser horizontal levels. An optional Jacobian-free Newton–Krylov stage (steady.stage = simplec_newton) finishes to tight tolerances.
  • Physics. The Axell–Liungman k–L turbulence closure, a Monin–Obukhov surface layer, buoyancy, Coriolis, and inflow from a log law or a measured profile.
  • Terrain. A terrain-following mesh from an elevation file (x y z points or ERF's grid format), with stretched vertical layers for thin near-ground cells. The pressure equation uses a terrain-aware multigrid solver that handles high cell aspect ratios.
  • A clear definition of steady. Residuals must fall by a set number of orders and the monitored quantities must settle; the run says why it stopped. Restarts continue bit for bit on the same ranks and box layout.

GUST reuses components of ERF (the k–L closure, the terrain-following mesh and Poisson operator, the surface layer), and its initializer builds on FastWindTerrain. It was called ablsteady before October 2026.

Quick start

git clone --recursive https://github.com/erf-model/gust-abl.git
cd gust-abl
cmake -S . -B build-rel -DCMAKE_BUILD_TYPE=Release
cmake --build build-rel -j 8
ctest --test-dir build-rel -L unit --output-on-failure
mpirun -n 2 build-rel/gust Tests/Infrastructure/Smoke_Restart/inputs_smoke

The tutorials walk through a single column, a flat boundary layer, a hill and Askervein Hill.

Case set-up tools

Python scripts in tools/ set up and check a case without editing decks by hand (pip install numpy pyyaml; the window also needs PySide6 pyqtgraph):

Script What it does
make_gust_case.py case.yaml writes a case folder (decks, terrain, run.sh) from one short YAML description
check_gust_inputs.py inputs checks a deck: unknown keys, ranges, settings that do not go together
fetch_terrain.py case.yaml downloads SRTM-based elevation tiles (AWS Terrain Tiles) for the case's domain
gust_gui.py [case.yaml] a window over the three: a form that starts with the basic settings (every key on request), a map of the domain and nests, the checker's findings, and a Run button that plots the residuals
python3 tools/gust_gui.py Tests/Infrastructure/Case_Setup/flat_nest.yaml

The case set-up page describes the YAML keys, the window and the terrain data and its acknowledgements.

Platforms

Platform Status in CI
Linux CPU (GCC Release and Debug, Clang; MPI) built, unit and smoke tests run
Windows CPU (MSVC, serial) built, unit and smoke tests run
Single precision (Linux) compiled
NVIDIA CUDA sm_90 (Linux, Windows) compiled
AMD HIP gfx90a (Linux) compiled
Intel SYCL (Linux) compiled

Hosted CI runners have no GPUs, so the GPU builds are compiled but not yet run (see the CI page).

Performance

Seconds per iteration on a Kestrel CPU node (104 Intel Xeon Sapphire Rapids cores) and on a Kestrel GPU node (4 × NVIDIA H100), the 3-D hill on power-of-2 meshes (GUST 12a81339f). The analysis, the minimum cells per rank and per GPU and the full tables are in the scaling page of the documentation.

CPU seconds per iteration

GPU seconds per iteration

Documentation

The full documentation is at https://erf-model.github.io/gust-abl/: building and running, every input with its range, the governing equations, discretization and solution algorithm, test cases and results. The sources are in docs/, and the same pages as one PDF at https://erf-model.github.io/gust-abl/gust.pdf. To build them locally:

python3 -m pip install -r docs/requirements.txt
make -C docs html     # output in docs/_build/html

Contributing

Issues and pull requests are welcome. The development rules (tests, input checks, review) are in docs/development.rst.

Licence

BSD 2-Clause (LICENSE). Code copied from ERF keeps ERF's licence; see docs/extraction.rst.

About

Grid-sequenced Unified Steady Terrain solver (GUST) - A Steady RANS Solver for Atmospheric Boundary Layer simulations using AMReX

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages