Initial conditions ================== The steady solver starts from an initial field. A good initial field is already close to the solution, so the solver needs fewer iterations. GUST builds the initial field in two steps: #. **Initial profile.** A wind profile is placed on the mesh by height above the local ground. #. **Mass-consistent adjustment.** The field is corrected so that it conserves mass, which bends the flow over and around the terrain. The method is that of mass-consistent wind models such as WindNinja (Forthofer et al. 2014) and follows FastWindTerrain. No FastWindTerrain code is copied (it uses a Cartesian immersed-boundary mesh), but every parameter has the same meaning. The code is in ``Source/Initializer`` and ``Source/ColumnGuess``; the inputs are in the ``init`` namespace (:doc:`inputs`). Options ------- ``init.first_guess`` selects the initial profile: .. list-table:: :header-rows: 1 :widths: 18 52 30 * - Value - Initial profile - Recommended for * - ``none`` (default) - Fluid at rest. - Tests only. * - ``profile`` - The inflow profile of :doc:`boundary_conditions` (log law, power law or file). - Cases without Coriolis forcing; flat cases with an inversion. * - ``column`` - The steady solution of a single vertical column, computed first (below). - Terrain cases with Coriolis forcing. ``init.projection`` (default 1) switches the mass-consistent adjustment on or off. With 0, the solver's own pressure correction removes the divergence in its first iteration. Initial profile from the inflow profile --------------------------------------- With ``init.first_guess = profile``: - :math:`u_0, v_0` are the inflow profile at each face's height above the ground, :math:`h = \max(z_\mathrm{face} - z_\mathrm{ground}, h_\mathrm{min})`, where :math:`h_\mathrm{min}` is ``init.z_agl_min``. - :math:`w_0 = 0`, except on the ground faces, where :math:`w_0 = u_0 z_x + v_0 z_y` (no flow through the ground). - :math:`\theta` is the sounding ``bc.theta_profile`` at the absolute height, and :math:`p = 0`. - :math:`k` is the profile's equilibrium value. Above :math:`z_i` = ``init.k_decay_height`` (0: no decay) it decays: .. math:: k = k_\mathrm{prof}(h)\, e^{-(h - z_i)/z_i} \quad (h > z_i), \qquad k = k_\mathrm{prof}(h) \quad (h \le z_i). Initial profile from a single column ------------------------------------ With Coriolis forcing, the steady wind turns with height (the Ekman spiral). The inflow profile has no such turning, so the solver must first spend many iterations on the slow inertial adjustment. ``init.first_guess = column`` avoids this: it first solves the horizontally uniform problem of the case, a single vertical column, and uses its steady profile as the initial profile. The column has the vertical grid of the case over flat ground. It solves for the horizontal wind, written as the complex number :math:`u + iv`, and for :math:`k`: .. math:: \frac{\partial (u + iv)}{\partial t} = \frac{\partial}{\partial z}\Bigl(\nu\,\frac{\partial (u + iv)}{\partial z}\Bigr) - i f\,\bigl((u + iv) - (u_g + i v_g)\bigr) + F_x + i F_y, \qquad \frac{\partial k}{\partial t} = \frac{\partial}{\partial z}\Bigl(\gamma_k\,\frac{\partial k}{\partial z}\Bigr) + P_s + P_b - \varepsilon . - :math:`\theta` is held at the sounding. - :math:`\nu`, :math:`\gamma_k`, :math:`P_s`, :math:`P_b`, :math:`\varepsilon` come from the turbulence model of :doc:`turbulence_model`. - The ground uses the neutral log law; the top and the Rayleigh layer are those of the case. **Forest canopy.** When the run has a canopy (:doc:`canopy`) the column carries it: the layer profile :math:`f_k` of the level's drag field (its mean over the domain's columns) enters the momentum equation as the drag :math:`-f_k |W| W`, linearised along the wind about each step's start (the derivative diagonal of the 3-D rows; a lagged :math:`|W|` would hand the balance speed back and forth at the column's large steps), and with ``canopy.tke`` the :math:`k` equation gains the wake production :math:`\beta_p f |W|^3`, the short-circuit sink :math:`\beta_d f |W| k` on the Patankar diagonal and the closure's length cap :math:`L \le \alpha/f`, the same terms as the 3-D stage's on a flat column. The first guess and an inflow column made from it then carry the forest: on ``Tests/Canonical_RANS/Canopy_Drag`` with a uniform 20 m canopy (LAI 3) the 3-D run starts from the column with first residuals of :math:`10^{-9}` against 1 from the profile, and reaches the verdict in 1082 iterations against 2046 (``rt_canopy_column``). The column is horizontally uniform and sits on the flat levels, so the canopy must be the same in every column and the terrain flat: on a terrain-following mesh even a canopy of uniform height gives each column its own layer profile, and a canopy whose :math:`f` differs between columns (a forest on part of the domain) stops the run, naming ``init.first_guess`` (use ``profile`` there, or an inflow table). Deep inside a dense uniform canopy the column's balances are closed forms, :math:`|W| = \sqrt{F/f}` for a pressure-gradient force :math:`F` and :math:`\beta_p |W|^3 = \beta_d |W| k + C_{\mu 0}^3 k^{3/2}/\alpha`, which the unit tests ``ColumnCanopy.*`` pin. The column is marched to steady state with implicit (backward Euler) steps that grow from 10 s to :math:`10^5` s. It has converged when the largest change of :math:`u, v` and :math:`k` over a step, relative to their scale, is below ``init.column_tol``. This typically takes 100–200 steps and a few hundredths of a second. If it has not converged after ``init.column_max_iterations`` steps, the run stops. The converged :math:`u, v, k` are then placed on the mesh by height above the local ground, exactly as the inflow profile is; :math:`\theta` stays the sounding. The table is written to ``io.column_guess_file`` (default ``column_guess.dat`` in the run directory), in full precision, so it reads back as a ``bc.inflow_file`` exactly. An inflow face keeps the case's inflow profile; the solver reconciles the two. **Requirements.** The column option needs: - a horizontal forcing: ``forcing.geostrophic = 1`` or a non-zero ``forcing.pressure_gradient``; - the SIMPLEC stage (``steady.stage = simplec``); - a ``surface_layer`` ground with the default wall :math:`k` (``bc.surface_zref`` is not supported), neutral unless ``init.column_stability = heat_flux`` (then ``bc.surface_stability = heat_flux``) or ``mol`` with a non-zero ``init.column_mol`` (``bc.surface_stability = heat_flux`` allowed: the run takes the column's flux); - with a non-neutral steady column, a Rayleigh layer on :math:`\theta` (below; the time-marching column needs none); - a ``slip_wall``, ``geostrophic`` or ``no_slip_wall`` top; - ``bc.rayleigh_fields`` either containing both ``u`` and ``v`` or neither; - with a pressure gradient but no Coriolis force: a neutral sounding or a Rayleigh layer on ``u`` and ``v`` (the steady column only); - with a forest canopy (:doc:`canopy`): flat terrain and a canopy that is the same in every column (below). ``init.k_decay_height`` cannot be used with it. Otherwise the run stops with a message naming ``init.first_guess``. .. _column-stability: **Stratified column.** With a non-neutral surface (``init.column_stability``, the forms of amrTerrain's 1-D column solver) the column also solves for :math:`\theta`, .. math:: \frac{\partial \theta}{\partial t} = \frac{\partial}{\partial z}\Bigl(\gamma_\theta\,\frac{\partial \theta}{\partial z}\Bigr) - c_r(z)\,(\theta - \theta_p), with the deck's gradient ``bc.zhi_theta_grad`` at the top and, at the ground, Monin–Obukhov similarity for a surface temperature :math:`\theta_s` (ERF's Businger–Dyer :math:`\psi_m`, :math:`\psi_h`, or QNSE's on the stable side with ``bc.surface_stable_functions = qnse``, :ref:`stable functions `): .. math:: u_* = \frac{\kappa U_1}{\ln\frac{z_1 + z_0}{z_0} - \psi_m(\zeta)}, \qquad q = -\frac{\kappa u_*\,(\theta_1 - \theta_s)}{\ln\frac{z_1 + z_0}{z_0} - \psi_h(\zeta)}, \qquad \zeta = \frac{z_1}{L}, \quad \frac{1}{L} = -\frac{\kappa g q}{u_*^3 \theta_0}, - :math:`U_1`, :math:`\theta_1`: the first cell's speed and potential temperature at height :math:`z_1`; - :math:`\zeta` from the bulk Richardson number, as ERF's surface-temperature solve: :math:`\zeta = \mathrm{Ri}_b\,(\ln - \psi_m)^2/(\ln - \psi_h)`, :math:`\mathrm{Ri}_b = z_1 g (\theta_1 - \theta_s)/(U_1^2 \theta_0)` held in [``init.column_rib_min``, ``init.column_rib_max``] (default ±4, ERF's), solved by ERF's fixed point under-relaxed by a half. Businger–Dyer's linear stable :math:`\psi` has a root only for :math:`\mathrm{Ri}_b < 0.2` (:math:`\zeta = \mathrm{Ri}_b \ln/(1 - 5\,\mathrm{Ri}_b)`), so with them the bound is at most 0.19 (:math:`\zeta = 3.8\ln`); QNSE's :math:`\phi` levels off and needs no further cap. The flux takes the full :math:`\theta_1 - \theta_s`, as in ERF and WRF; - :math:`q`: the kinematic surface heat flux (K m/s, upward > 0), implicit in :math:`\theta_1`; - the wall :math:`k` the surface layer's (Axell and Liungman 2001, Eq. 16): :math:`k_1 = (u_*^3 + \kappa B z_1)^{2/3}/C_{\mu 0}^2`, :math:`B = g q/\theta_0` for an upward flux only. ``surface_temperature`` fixes :math:`\theta_s` (``init.column_surface_theta``). ``mol`` and ``heat_flux`` fix :math:`1/L` (``init.column_mol``) or :math:`q` (``bc.surface_heat_flux``), and the column finds the :math:`\theta_s` that gives it by the secant method. The search is on :math:`1/L` for ``mol``, so it reaches every :math:`L` the column allows, also those past its largest downward flux. :math:`\zeta` is taken at the first cell centre, :math:`z_1/L`, as in the 3-D wall model. **Heat budget.** At steady state the surface flux has to leave (or enter) the column somewhere. The top passes almost nothing: its flux is the deck's gradient times a diffusivity at the floor. The Rayleigh layer on :math:`\theta` is therefore the column's heat source or sink, and a non-neutral column requires it (``bc.rayleigh_zdamp`` > 0 and ``theta`` in ``bc.rayleigh_fields``). The most stable column the deck allows (the smallest :math:`L`, the largest downward flux) depends on that layer's height and strength and on the wind. It is a property of the deck, not of the turbulence model. A request beyond it stops the run, naming the smallest :math:`L` (or the largest flux) reached. On the unit test's 64 m column (Rayleigh layer above 48 m) the smallest :math:`L` is 414 m; on a 120 m deck with the Bolund vertical grid the largest downward flux is −0.029 K m/s with the Rayleigh layer above 80 m and −0.022 K m/s above 100 m. The log prints the flux, :math:`L` and :math:`\theta_s` reached, and the column's total steps and columns. With ``mol`` and ``bc.surface_stability = heat_flux`` the 3-D run takes the column's flux as ``bc.surface_heat_flux``. The wall :math:`k` is the surface layer's, :math:`(u_*^3 + \kappa B z_1)^{2/3}/C_{\mu 0}^2`; amrTerrain's column uses the additive form :math:`(u_*^2 + (\kappa B z_1)^{2/3})/C_{\mu}^2`, up to :math:`2^{1/3}` larger for an upward flux. **Target wind.** ``init.column_target_u``, ``init.column_target_v`` at ``init.column_target_height`` (amrTerrain's met-mast forcing): the geostrophic wind needed to keep a given wind at a given height under each stratification. After each converged column the geostrophic wind and the column's Rayleigh reference wind are multiplied by :math:`R = U_\mathrm{target}/U(z_t)` (complex: scaled and turned), the pressure gradient by :math:`R\,|R|` (the stress goes with the square of the speed), and the column is solved again, until :math:`|R - 1| < 10^{-4}`. :math:`U(z_t)` is MOST's profile below the first cell centre and linear in :math:`\ln(z + z_0)` above. The 3-D run then takes that forcing. It reaches the target only if nothing holds its wind to the deck's inflow profile, so a target is refused with a Rayleigh layer on :math:`u, v`, a sponge or an inflow face (for an inflow case, run the column on a periodic deck and give its ``io.column_guess_file`` table as ``bc.inflow_file``), and with a stratified column over a neutral 3-D surface. .. _column-marching: **Time-marching column.** ``init.column_time`` > 0 marches the same column in physical time instead: backward Euler steps of ``init.column_dt`` (the last step ends at ``init.column_time``), :math:`\nu_t` taken from the closure at each step without the steady column's relaxation, and no convergence test. It is the form of ERF's near-1-D column with a stratified inflow: a column heated or cooled at a fixed rate has no steady state, so it needs no Rayleigh layer on :math:`\theta`, and the table is its state at ``init.column_time``. The surface is fixed: the neutral wall law (``mol`` with ``init.column_mol = 0``, :math:`\theta` held), ``surface_temperature``, or ``heat_flux``, where the flux :math:`q` = ``bc.surface_heat_flux`` enters the first cell as given (explicit, no search for :math:`\theta_s`) and MOST gives :math:`u_*` and :math:`L` from it, as ERF's flux surface: .. math:: u_* = \frac{\kappa U_1}{\ln\frac{z_1 + z_0}{z_0} - \psi_m(\zeta)}, \qquad \zeta = -\frac{\kappa g q z_1}{\theta_0 u_*^3}, solved by the fixed point under-relaxed by a half (from the previous step's :math:`\zeta`, then from 0 if that fails, to :math:`10^{-10}`), :math:`\theta_* = -q/u_*`. A downward flux too large for the wind has no root and stops the run, naming ``bc.surface_heat_flux`` (at any step, and at the final state). With a slip top, ``bc.zhi_theta_grad = 0`` and no Rayleigh layer on :math:`\theta` the column's heat content :math:`\sum \theta\,\Delta z` then grows by :math:`q t` to round-off (the unit test ``ColumnMarching.SurfaceFluxBudget``). The target wind and a non-zero ``init.column_mol`` need the steady column; the bulk Richardson bounds are refused with ``heat_flux`` (no bulk Richardson number is solved). The log and the table header give the surface of the final state; with ``surface_temperature`` the flux printed is the one at ``init.column_time`` only. The 3-D run is steady and has no such time: a marched :math:`\theta` with a fixed flux and no heat sink is not a steady state of a periodic deck. The table is meant as the ``bc.inflow_file`` of a deck with an inflow face (with ``simplec.theta = frozen``), or as a first guess alone (the example deck stops after one iteration, ``steady.max_iterations = 1``). On four stratified columns (240 × 10 m levels, 9 h, ``Tests/Canonical_RANS/Column_Marching``) the column is within 9 % of ERF's bulk Richardson number between 46 and 73 m and within 1 % of its speed at 300 m, the same for steps of 1, 10 and 60 s; a 9 h column of 1 s steps takes about 2 s. The march is first order in time and stayed stable up to 3600 s steps; steps up to about 300 s keep the bulk Richardson number within 0.002 of the 1 s column, while 3600 s steps damp the inertial oscillation (U(300 m) 1–3 % low). **The first cell's k.** By default (``init.column_wall_k = fixed``) the marching column holds the first cell's :math:`k` at the surface layer's wall value, as the steady column and the 3-D run do: .. math:: k_1 = \frac{\left(u_*^3 + \kappa B z_1\right)^{2/3}}{C_{\mu 0}^2}, \qquad B = \max\left(\frac{g q}{\theta_0}, 0\right) (Axell and Liungman 2001, Eq. 16). ``init.column_wall_k = solved`` solves the first cell's :math:`k` with the equation of the other cells instead: no :math:`k` flux through the ground, the shear production from the mean of the wall law's gradient at the first centre (:math:`u_*/(\kappa (z_1 + z_0))` when neutral, MOST's otherwise) and the layer difference above, the buoyancy production or destruction, the closure's dissipation. The layer difference is smaller than the wall law's gradient, so in a neutral surface layer the solved :math:`k_1` settles below the log-layer value :math:`u_*^2/C_{\mu 0}^2`: at 0.77 of it for :math:`z_1/z_0 = 5` and 0.74 for :math:`z_1/z_0 \ge 30` (a discrete constant-stress layer; 0.76 in ``ColumnMarching.SolvedWallK``), with a :math:`k` minimum at the first cell. The closer agreement with ERF's first-cell :math:`k` below is therefore partly this discretisation, not evidence that the solved value is the more physical one. In the four columns the solved first-cell :math:`k` is 1.2–1.3 times ERF's (the wall value is about 1.9 times), and the bulk Richardson number moves 1–2 % of its value towards ERF's (6.5–8 % below it, from 8–9 %). The speed at 300 m and :math:`\theta` change by at most 0.01 m/s and 0.01 K. The 3-D run keeps the wall value either way. **Restart.** The checkpoint holds the state, not the adjusted forcing or the column's flux, and ``init.*`` keys are refused on a restart. The log lists the inputs a restart deck needs in their place (``forcing.ug``, ``forcing.vg``, ``forcing.pressure_gradient``, ``bc.surface_heat_flux``), with all their digits. On the Bolund case 4 deck with :math:`L` = 250 m and 7.58 m/s at 5 m, the column gives :math:`u_*` = 0.509 m/s (0.5085 m/s measured). That agreement mainly reflects MOST at 5 m with the chosen :math:`z_0` and target. The flux, :math:`q` = −0.039 K m/s, is sustained by the Rayleigh layer and has no measured counterpart. The column's :math:`\theta` goes into the ``io.column_guess_file`` table (a ``bc.inflow_file`` for a run with the same stratification). The 3-D first guess keeps :math:`\theta` from the sounding. **When to use it.** On the 2-D and 3-D hills the column start halves the iterations (:doc:`results`). On the flat ``Neutral_ABL_Flat`` case it does not converge: the column's :math:`k` at the sharp inversion base differs from the 3-D solution, and a slow oscillation of :math:`k` develops there. Use ``profile`` for that case. Mass-consistent adjustment -------------------------- The initial profile :math:`\mathbf u_0` does not conserve mass over terrain. The adjustment finds the field :math:`\mathbf u` closest to :math:`\mathbf u_0` that does (Sherman 1978): .. math:: \nabla\cdot(\Sigma\nabla\lambda) = \nabla\cdot\mathbf u_0, \qquad \mathbf u = \mathbf u_0 - \Sigma\nabla\lambda, \qquad \Sigma = \mathrm{diag}(\alpha_h^2, \alpha_h^2, \alpha_v^2) . - :math:`\lambda`: a Lagrange multiplier (a potential), with :math:`\lambda = 0` on inflow and outflow faces and no flux through walls, the ground and the top. - :math:`\alpha_h, \alpha_v`: horizontal and vertical transmissivity (``init.alpha_h``, ``init.alpha_v``). The equation is solved by the Poisson solver of :doc:`solution_algorithm`, terrain cross terms included. **Choosing α.** Only the ratio :math:`\alpha_v/\alpha_h` matters. A smaller ratio allows less vertical motion, so the flow goes around steep terrain rather than over it, as in stable air. In Sherman's notation :math:`\alpha_v/\alpha_h` is :math:`\alpha_1/\alpha_2`, WindNinja's stability parameter. Ratios of 0.1 and above are practical; smaller ratios need more Poisson iterations. With :math:`\alpha_v \ne \alpha_h` this one solve always uses the ``gmres_fft`` back end, whatever ``solver.poisson_backend`` says, and the log says so. The SIMPLEC stage keeps ``solver.poisson_backend``. O'Brien correction ------------------ ``init.obrien = 1`` (off by default) first sets the vertical flux :math:`\Omega_0` from column continuity, integrating from the ground up, and removes the remaining flux at the top with a weight that grows with height (O'Brien 1970): .. math:: a_z\Omega_{k+1/2} = a_z\Omega_{k-1/2} - J_k D^h_k\,\Delta\zeta, \qquad f_k = \frac{z_k - z_\mathrm{ground}}{z_\mathrm{top} - z_\mathrm{ground}} , where :math:`D^h` is the horizontal part of the divergence and the top residual is removed with the weight :math:`f_k^2`. It is meant for initial profiles taken from soundings or other models. The resulting field ------------------- The initial field is divergence-free to the Poisson tolerance, and :math:`\theta`, :math:`k`, :math:`p` are consistent with the sounding. It is a starting point, not a RANS solution: it does not satisfy the momentum equations. A restart (``io.restart``) cannot be combined with ``init.first_guess``: the checkpoint already holds the state.