Tutorial 1: A neutral surface layer
This first tutorial runs the simplest case: wind over flat, uniform ground with no temperature effects. The answer is known exactly, so you can check that GUST reproduces it. The run takes a few seconds on a laptop.
You will learn to: run GUST, read its log, find its output and compare a wind profile with theory.
Before you start: build GUST (Installation). The commands below assume you are in the repository
directory and the executable is build-rel/gust.
The physical problem
A constant pressure gradient drives the wind over flat ground with roughness length \(z_0 = 0.1\) m. The domain is 1000 m high. At steady state the ground stress balances the driving force, so the friction velocity is known:
Near the ground the wind follows the logarithmic law and the TKE is constant:
Nothing changes in the horizontal, so a small 4 × 4 × 64 mesh is enough.
The input file
Open Tests/Canonical_RANS/Neutral_Column/inputs_steady_column. Without its comments it reads:
# Mesh: 4 x 4 x 64 cells, 2560 m x 2560 m x 1000 m, periodic sides
mesh.n_cell = 4 4 64
mesh.prob_hi = 2560. 2560. 1000.
mesh.is_periodic = 1 1 0
mesh.max_grid_size = 4 4
terrain.type = flat
# Boundaries: rough ground with a wall model, slip top
bc.zlo = surface_layer
bc.zhi = slip_wall
bc.surface_z0 = 0.1
bc.theta_profile_z = 0.
bc.theta_profile = 300.
# Initial field: a log-law profile (deliberately with the wrong u* = 0.25 m/s)
bc.inflow_profile = log_law
bc.inflow_ustar = 0.25
bc.inflow_z0 = 0.1
bc.inflow_direction = 0.
init.first_guess = profile
# Turbulence model and driving force
turb.max_geom_lscale = 1.0e12
turb.face_mean = logarithmic
forcing.pressure_gradient = 1.225e-4 0. 0.
# Solver and convergence criteria
steady.stage = simplec
steady.sweep = zjacobi
steady.cfl0 = 1.
steady.cfl_max = 50.
steady.max_iterations = 20000
steady.residual_drop_orders = 6
steady.residual_tol = 1.e-8
# Output
io.plot_file = steady_column_plt
io.turb_plot_file = steady_column_turb
io.chk_file = steady_column_chk
Every input is namespace.key = value. The namespaces group the inputs by topic: mesh, bc (boundary
conditions), init (initial conditions), steady (solver), and so on. Input reference lists them all.
Three settings are worth noting:
The initial profile uses \(u_* = 0.25\) m/s, not 0.35 m/s. The solver has to find the right answer itself.
steady.sweep = zjacobikeeps the z-line Jacobi sweeps of the iteration counts below. Without it a CPU build uses line LU-SGS (the default since the sweep and CFL-cap study on Askervein, Results).steady.cfl_max = 50is large. It works here because every column is identical; 3-D cases need smaller values (How-to guides).
Run the case
Run it in a new directory, on two MPI ranks:
mkdir -p runs/column && cd runs/column
mpirun -n 2 ../../build-rel/gust ../../Tests/Canonical_RANS/Neutral_Column/inputs_steady_column
Read the log
The log starts with the mesh and the initial field:
gust: (4,4,64) cells, 1 boxes (each spans the full z column)
gust: initializer: 0 Poisson iterations (gmres_mlmg, reltol 1.000e-10), divergence 0.000000000e+00 ...
gust: mesh quality
min cell thickness / flat layer thickness = 1.000000000e+00
...
gust: SIMPLEC stage: 2 zjacobi sweeps, pressure gmres_mlmg reltol 0.001, alpha_p 1, w_vnn_cap off, cfl0 1, cfl_max 50
Over flat ground the initial profile already conserves mass, so the initializer needs no Poisson iterations. Then the solver prints one table row per iteration (the first ten, then every tenth) under a header it repeats every 20 rows:
Iter CFL Line solver u-res v-res w-res tke-res theta-res p-res r
------ --------- ----------- --------- --------- --------- --------- --------- --------- ---------
300 5.000e+01 zjacobi 9.669e-05 0.000e+00 0.000e+00 1.352e-03 0.000e+00 0.000e+00 1.935e-02
Column |
Meaning |
|---|---|
|
Iteration number. |
|
Current CFL number. It grows from |
|
The z-line solver of the sweeps ( |
|
Scaled residuals of \(u, v, w, k, \theta, p\). The column has no \(v, w, \theta, p\) imbalance, so those are 0. |
|
Largest residual relative to its reference value. |
io.iteration_log = full prints instead one gust: it line per row that also has the monitors (largest wind
speed, mean TKE, mean friction velocity \(u_*\)), the Poisson iterations, the divergence before and after the
correction and the cells where \(k\) was raised to its floor (Output files).
The run ends with the verdict:
2231 5.000e+01 zjacobi 6.863e-10 0.000e+00 0.000e+00 9.990e-09 0.000e+00 0.000e+00 1.373e-07
gust: steady after 2231 iterations (2231 over the run)
gust: stage account: 2231 iterations, 3.459247747 s, 0 AU
gust: wrote steady_column_plt02231
gust: wrote steady_column_turb02231
gust: wrote steady_column_chk02231
The mean friction velocity (the last monitor) is 0.3500 m/s, the exact value.
The output
The run directory now holds three outputs (Output files):
steady_column_plt02231: the solution (\(u, v, w, p, \theta, k\) and the height), an AMReX plotfile;steady_column_turb02231: turbulence fields with ERF’s variable names;steady_column_chk02231: a checkpoint for restarting.
Plotfiles open in ParaView, VisIt or yt.
Compare with the log law
The repository includes a small plotfile reader that needs only the Python standard library. Save this script as
profile.py in the run directory:
import math
import sys
sys.path.insert(0, "../../extern_erf") # ERF's plotfile reader
import erf_plotfile
z, avg, _ = erf_plotfile.planar_averages("steady_column_plt02231", ["u", "tke"])
ustar, kappa, z0 = 0.35, 0.41, 0.1
for k in range(6):
loglaw = ustar / kappa * math.log((z[k] + z0) / z0)
print(f"z = {z[k]:6.2f} m u = {avg['u'][k]:.3f} log law = {loglaw:.3f} k = {avg['tke'][k]:.4f}")
Run it with python3 profile.py:
z = 7.81 m u = 3.731 log law = 3.731 k = 0.3960
z = 23.44 m u = 4.620 log law = 4.662 k = 0.4382
z = 39.06 m u = 5.029 log law = 5.097 k = 0.4067
z = 54.69 m u = 5.302 log law = 5.383 k = 0.3879
z = 70.31 m u = 5.507 log law = 5.597 k = 0.3745
z = 85.94 m u = 5.670 log law = 5.768 k = 0.3636
The first cell matches the log law exactly, because the wall model imposes it there, and \(k\) equals \(u_*^2/C_{\mu 0}^2 = 0.396\). Higher up the wind falls slightly below the log law (by about 1–2 %), because the stress decreases with height in this driven column.
Next steps
Tutorial 2: An atmospheric boundary layer adds Coriolis forcing and a temperature inversion.
Try
mpirun -n 1instead of 2: the result is the same.