Boundary conditions
The computational domain is a box with six faces: west and east (xlo, xhi), south and north (ylo,
yhi), the ground (zlo) and the top (zhi). Each face gets one boundary type. The typical ABL setup is
periodic sides, a rough ground described by a wall model, and a slip top. The boundary types are ERF’s. The code is
in Source/BoundaryConditions (the fills and Dirichlet rows), Source/BoundaryInputs (the bc reader and its
checks), Source/BoundaryDamping (the damping layers), Source/InflowProfile and Source/SurfaceLayer; the
inputs are in the bc
namespace (Input reference).
Boundary types
Type |
Faces |
Condition |
|---|---|---|
|
x, y |
The flow leaving one side enters the opposite side. Used where |
|
x, y |
\(u, v, \theta, k\) from the inflow profile at their height above the ground. |
|
x, y |
Zero normal gradient for every field; \(p = 0\). |
|
all |
No flow through the face; no stress along it. At the top, \(\theta\) may have a given gradient
( |
|
all |
The velocity equals the wall velocity (0, or a moving lid set by |
|
ground |
Monin–Obukhov wall model (below). The default ground. |
|
top |
\(u, v\) held at the geostrophic wind. |
The defaults are periodic sides, a surface_layer ground and a slip_wall top, as in ERF’s canonical ABL
cases.
No flow through the ground and the top. On a terrain-following mesh the velocity normal to the ground is the contravariant velocity \(\Omega\) (Terrain-following coordinates), not \(w\). The ground and top values of \(w\) are therefore
which gives \(\Omega = 0\). Over flat ground \(w_\mathrm{face} = 0\).
Outflow faces: the transport fluxes of the ghost cells. The outflow fill copies \(u, v, w, \theta, k\)
along the grid line into the ghost cells outside the face. The ghost node columns take the face node’s height, so a
ghost cell is flat across the face (along the face it keeps the face line’s slope). Convection uses the transport
fluxes \(F_x = a_x u\), \(F_y = a_y v\) and \(\Omega = w - z_x \bar u - z_y \bar v\) (MassFlux.H), and
the control volume of the face-point velocity reaches half a cell into the ghost cell, so it reads the ghost cell’s
fluxes. By default (bc.outflow_transport = mirror) the ghost cell is given the edge cell’s fluxes as a mirror
image through the face:
\(e\): the last cell inside the face; \(e + m\): the \(m\)-th ghost cell outside it (counted outwards, so towards lower indices on a low face), at the same level and position along the face; \(e - m + 1\): its mirror image inside.
\(F_t\): the tangential flux (\(F_y\) on an x face, \(F_x\) on a y face), at cell positions along the normal; \(F_n\): the normal flux, on the faces \(f\) (the boundary face) and \(f \pm m\).
\(a_x, a_y\): the area factors of the x- and y-faces (Mesh.H); \(z_x, z_y\): the slopes of a z-face, from its four nodes; \(\bar u, \bar v\): the means of the four \(u\) (\(v\)) points around it.
Each ghost cell then has its edge cell’s divergence (in index space), whatever the ground does along or across the face, and the face-point control volume, half in each, has the edge cell’s net flux: for a mass-consistent field the face-point rows are like interior rows. The velocity ghosts are not changed, so the strain rate, the diffusion and the closure at the face see the same values as before.
With bc.outflow_transport = from_velocity (the only choice up to v1.0.0) the fluxes are computed from the copied
velocities and the ghost cell’s own geometry. These terms then differ from the edge cell’s:
\(\Omega_g - \Omega_e \approx z_{x,e}\,\bar u_e\) on an x face (plus the difference of the along-face slopes times \(\bar v\)): a vertical flux where the face cuts a slope.
\(F_{n,f+1} \approx F_{n,f-1}\) (the copied normal velocity), so the ghost cell’s normal divergence is minus the edge cell’s.
In 3-D the tangential flux, through the flat ghost cell’s area factors (a smaller term).
The face-point control volume then has a net flux the implicit diagonal (\(a_P = \sum a_\mathrm{nb}\)) does not
hold. Where it is an outflow (a face cutting a rising slope) the true diagonal is larger, the face-point rows
overshoot and the iteration alternates between two states (Tests/Canonical_RANS/Outflow_Steep_Terrain: relative
residual 0.176 with from_velocity, steady in 148 iterations with mirror). Mirroring \(\Omega\) alone
removes that flux but leaves the normal-flux term: on Aspect_Ratio_Hill_2D (dx/dz1 = 100, a slope of 5e-4 at the
face) the spanwise velocity residual then decayed slowly at the face column (546 iterations, against 181 with
from_velocity and 161 with the full mirror). The cause of that slow mode was not isolated; the full mirror,
which makes the face-point control volume consistent, does not show it.
The two choices differ over flat ground too (the normal flux), by little: on Askervein_210 the 10 m speeds change
by at most 7e-6 (relative). With backflow through the face (or an edge cell that slows the flow by more than two
thirds) the extrapolated normal flux turns the outer half of the face-point control volume into an inflow; the rows
stay well posed (upwind weights), but a zero-gradient outflow is not meant for backflow with either choice. A restart from a checkpoint written with v1.0.0 continues with mirror; give
bc.outflow_transport = from_velocity to continue the old run unchanged.
Wall model
The first cell above the ground is usually much thicker than the thin layer where the wind drops to zero. A wall model bridges this layer: it gives the stress at the ground from the wind in the first cell, using Monin–Obukhov similarity theory (MOST). In each column,
\(u_*\): friction velocity.
\(U = \max(|\mathbf U_t|, 0.1~\mathrm{m/s})\): wind speed parallel to the ground at the reference height (
bc.surface_zref; by default the first cell centre). \(\mathbf U_t = \mathbf U - (\mathbf U\cdot\mathbf n)\,\mathbf n\) is the cell-centre wind with its component along the ground normal \(\mathbf n\) removed, interpolated in \(\ln(d + z_0)\) between two centres. In the cell on the ground the centre wind is taken parallel to the ground, \((u_c,\, v_c,\, z_x u_c + z_y v_c)\): the no-flux rule (\(\Omega = 0\)) applied to the cell’s own centre \(u_c, v_c\), which is exact for a flow along a uniform slope; the cell’s \(w\) faces are not read. The ghost fill writes the ground \(w\) face and the \(u, v\) ghosts after the wall model, so the wall model reads no value the fill writes, and a second fill changes nothing. Over flat ground the vertical part is projected out either way. (Before audit A2 the vertical part was the mean of the ground and top \(w\) faces; the ground face is written by the fill from the wall law’s ghosts, so the fill was not a fixed point.) A reference height between the last two cell centres reads the top \(w\) face, which the fill writes too; over a top that is not flat the fill is then a fixed point only to that face’s change.\(d = h/|A|\): distance from the ground along its normal, with \(|A| = \sqrt{1 + z_x^2 + z_y^2}\).
\(z_0\): roughness length (
bc.surface_z0, or per column frombc.surface_z0_file, roughness map).\(q\): kinematic surface heat flux (
bc.surface_heat_flux).\(L_O\): Obukhov length.
\(\psi_m\): ERF’s Businger–Dyer stability function, or QNSE’s on the stable side (below).
\(m\): a floor on the denominator (below).
With bc.surface_stability = heat_flux, \(u_*\) and \(L_O\) are solved together by Newton’s method to
round-off. (ERF uses a relaxed fixed point to 1e-5; a converged \(u_*\) keeps the residual smooth, which a
finite-difference Jacobian needs.)
Denominator floor. Without a floor, strong convection at low wind gives \(u_* < 0\).
bc.surface_denominator_floor selects the floor:
log_law(default): \(m = \min(\ln((d + z_0)/z_0),\, 1)\). In neutral flow the floor never acts, so \(u_*\) is the log-law value at every height.one: \(m = 1\). In neutral flow this lowers \(u_*\) when the reference point is below \((e - 1)\,z_0 \approx 1.72\,z_0\), for example a 1 m first layer over \(z_0 = 0.5\) m.
The two give identical results where \(\ln((d + z_0)/z_0) \ge 1\).
Stable functions. bc.surface_stable_functions selects the stable side
(\(\zeta = z/L > 0\)) of the flux-gradient functions \(\phi_m, \phi_h\) and their integrals
\(\psi = \int_0^\zeta (1 - \phi(x))/x\,dx\). Both use one form,
businger_dyer(default): \(a = 5\), \(b = 0\), so \(\phi = 1 + 5\zeta\) and \(\psi = -5\zeta\) (Dyer 1974, ERF’s functions).qnse: the quasi-normal scale elimination functions (Sukoriansky, Galperin and Perov 2005), as ERF’senable_qnse_stable_functions: \(a_m, b_m\) (bc.surface_qnse_am,_bm) for momentum and \(a_h, b_h\) (_ah,_bh) for heat, ERF’s defaults 2.5 and 0.2. \(\phi\) tends to \(a/b = 12.5\) in very stable air, so the surface stress does not collapse as fast as with Businger–Dyer’s linear \(\phi\).
The unstable side is Businger–Dyer’s with either choice. The selection applies to the wall model’s
\(u_*\) (bc.surface_stability = heat_flux), the ground gradients of the ghost cells, and the stratified
column (stratified column).
The wall model replaces the diffusive fluxes through the ground:
Field |
Ground flux |
|---|---|
\(u, v\) |
\(u_*^2\,|A|\,\mathbf U_t/U\), along the ground wind |
\(\theta\) |
\(-q\,|A|\) |
\(k\) |
0; the first cell relaxes to \(k_w = (u_*^3 + \kappa B d_0)^{2/3}/C_{\mu 0}^2\) (AL01 Eq. 16),
with \(d_0\) the first-cell-centre distance and \(B = gq/\theta_0\) for \(q > 0\). With
|
The ghost cells below the ground continue the MOST profile.
Roughness map. bc.surface_z0_file replaces the single \(z_0\) with one value per ground column, for a
surface such as water beside land. The file holds x y z0 points (the format of terrain.file). Each ground
column takes the inverse-distance-weighted mean of \(\ln z_0\) over the terrain.idw_neighbors nearest
points (weight \(r^{-p}\), \(p\) = terrain.idw_power) at its cell centre:
\(z_{0,n}\): the file’s value at point \(n\), at distance \(r_n\) from the cell centre;
\(z_{0,\mathrm{ref}}\): the file’s largest value (a file of one value then gives that value exactly).
The log law depends on \(z_0\) through \(\ln z_0\), so the mean is taken on that scale; an arithmetic mean
would let a few rough points dominate a smooth neighbour. A point within \(10^{-6}\) m of the centre gives its own
value. Ghost columns take the column they image (periodic image, or the nearest domain column). Every reader of
\(z_0\) on the ground uses the column’s value: the wall model above, the ghost fill’s wall-law gradient, and the
turbulence model’s geometric length \(\kappa(d + z_0)\). The inflow profile keeps bc.inflow_z0; where it
differs from the map next to the inflow face, an internal boundary layer grows from that face (over water
\(z_0 = 0.0003\) m below an inflow of \(z_0 = 0.01\) m, about 9 m deep after 200 m by Elliott’s 1958 estimate),
so the inflow should take the upstream surface’s \(z_0\) and a matching \(u_*\).
On the coarse levels of grid sequencing (mesh.hierarchy_levels > 1) a coarse column covering
\(r \times r\) level-0 columns takes their geometric mean,
\(z_{0,c} = z_{0,\mathrm{ref}} \exp\big(\tfrac{1}{r^2}\sum \ln(z_{0}/z_{0,\mathrm{ref}})\big)\). This is a
simple aggregation on the log-law scale, not a blending-height drag average (Mason 1988): in a column half water
and half land it gives about 20–30 % less drag at a 0.5–1 m first centre than the area mean of the two drags. The
coarse levels only seed level 0, which uses the map itself. The run prints the minimum, maximum and geometric mean of each level’s
map, and the turbulence plotfile (io.turb_plot_file) holds it as z0 on the first cells. A restart reads the
file the deck names again: the checkpoint does not record the map. init.first_guess = column needs a single
\(z_0\) and refuses a map.
Tests/Real_Terrain/WindNinja2019/bolund_z0_map.py writes the Bolund map from the Bolund terrain points: 0.0003 m over water (terrain at or
below the 0.75 m water level) and 0.015 m over land, with land roughness east of \(x = 327\) m, the values and
rules of the Bolund blind comparison (Bechmann et al. 2011).
Inflow profile
The inflow profile gives the wind, \(\theta\) and \(k\) as functions of the height \(z\) above the
ground. It is used on inflow faces, in the damping layers and for the initial field (Initial conditions). The
wind speed \(S(z)\) points along bc.inflow_direction:
A file profile tabulates z u v theta [k]. For the analytic profiles \(\theta\) is the sounding
bc.theta_profile.
Turbulence of the profile. Without a \(k\) column, \(k\) and \(\nu_t\) are in equilibrium with the wind’s shear: shear production equals dissipation in the neutral k–L closure (Turbulence model),
\(u_{*l}\): the local friction velocity; \(l\): the length; \(l_\mathrm{max}\):
turb.max_geom_lscale.bc.inflow_tke_length = closure(the default) uses this \(l\), the closure’s own geometric length, so the inflow \(k\) is the closure’s equilibrium.unboundeddrops the cap (\(l = \kappa(z + z_0)\)); the log law then has \(u_{*l} = u_*\) and \(k = u_*^2/C_{\mu 0}^2\) at every height.Why the cap. Without it, \(\kappa z\,dS/dz\) grows with height on a power law, and so does \(k\): on ERF’s Askervein inflow it reaches about 9 m²/s² at 316 m, where ERF’s flow has 0.31; with the cap, 0.31 at 316 m.
A \(k\) column is used as given, and
bc.inflow_tke_lengthis refused (it would change nothing).The equilibrium is the neutral one, also above an inversion, and the height is the height above the ground (the closure’s wall distance with
turb.wall_distance = terrain_height). The roughness isbc.inflow_z0, which should equalbc.surface_z0, or withbc.surface_z0_filethe map’s \(z_0\) next to the inflow face.A log-law wind with the capped length is not a momentum equilibrium (its stress falls with height as \((l/\kappa(z + z_0))^2\)); with the unbounded length the \(k\) equation was out of balance instead. The domain adjusts either way; the capped form at least balances the \(k\) equation.
Damping layers
Damping layers absorb waves before they reflect from the top or the sides. Both are off by default. They relax a field \(q\) towards the inflow profile \(q_\mathrm{ref}\) (0 for \(w\)) by adding a term to the residual:
\(z_d\): start height of the Rayleigh layer (
bc.rayleigh_zdamp); \(z_\mathrm{top}\): the top level of the mesh, which is notmesh.prob_hiz on a stretched grid (Terrain-following coordinates).\(c_r\): Rayleigh coefficient (
bc.rayleigh_dampcoef);bc.rayleigh_fieldsselects the fields.\(s\): distance to an inflow or outflow face; \(w_s\) is the sponge width (
bc.sponge_width) and \(c_s\) its strength (bc.sponge_strength).\(\theta\) is relaxed to the sounding at the absolute height by default (
bc.rayleigh_height).
In stratified flow over a hill, damp \(\theta\) together with \(w\). Gravity waves exchange energy between the two, and on ERF’s 2-D hill damping \(w\) alone let the pseudo-time iteration grow.
Pressure
The pressure correction is periodic where the mesh is periodic, Dirichlet (\(p = 0\)) on outflow faces and
Neumann on all other faces. The types follow ERF’s get_fft_bc.
Ghost cells
The solution has two layers of ghost cells outside each face. With interior values \(c_0, c_1\) and ghost values \(g_1, g_2\) along the face normal:
Rule |
Ghost values |
|---|---|
even |
\(g_1 = c_0,\ g_2 = c_1\) |
odd |
\(g_1 = -c_0,\ g_2 = -c_1\) (0 on the face) |
value \(V\) |
\(g_1 = 2V - c_0,\ g_2 = 2V - c_1\) |
profile |
\(g = P(h)\) at the ghost’s height above the ground |
gradient \(G\) |
the centred difference at \(c_0\) equals \(G\) |
The directions are filled in the order x, y, z, so corner ghosts get values too. Each direction fills every field
at both faces on all boxes of a rank in one launch (audit A9); on a domain no wider than the two ghost layers it is two
launches, the low face first. The values are those of one launch per field, face, box and layer.
Every copy of a ghost cell then holds one value. In its outermost lateral ghost layer a box lacks some of what the
rules read (the node heights have one lateral ghost layer, the wall law’s gradient two), so after the fill each cell
outside the domain takes the value of the box whose column it is in, and the ghost images of cells inside the domain
are refreshed from the neighbouring boxes (audit A3). No valid cell changes. The results then do not depend on the box
layout. Before, they did where an inflow face crosses terrain at a box seam and turb.realizability is on: the
cap’s strain in the first lateral ghost layer read inflow face points computed from the clamped heights.