Deploying to gh-pages from @ 4b2921e 🚀

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
-# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 1f0783e4f93b0f977cfe30e1da400e1d
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: b9a7243bd55f1f7490f5200a3937f44a
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/theory/theory.rst.txt

@@ -427,6 +427,62 @@ z direction (example: *half-channel* simulations) at the centerline.
        w &= 0
    \end{aligned}
 
+
+.. _terrainmodel:
+
+Terrain Model
+--------------
+
+An immersed boundary forcing method (IBFM) is used to represent the terrain. In this method,
+the effect of the terrain is modeled using a forcing term in the momentum and energy equation. 
+
+The forcing term in the momentum equation is given by: 
+
+.. math::
+
+   F_i = - \beta C_d u_i | u_i | 
+
+Here :math:`\beta` is the volume fraction of the cell covered by terrain, :math:`C_d` is a drag
+term  and :math:`u_i` is the wind speed. Currently, the volume fraction is 
+computed as a 0 or 1 using a simple nearest cell algorithm at each grid level. Future, updates 
+will incorporate the partial terrain overlap using the EB capability in AMReX. The calculation 
+of the drag coefficient term and the forcing term for the energy equation can be found in 
+`Muñoz‐Esparza, Domingo, et al.  (JAMS 2020) <https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2020MS002141>`_.
+
+The original formulation is designed for low Reynolds number cases and does not include a 
+method for applying a wall function. We propose the use of a forcing function to include 
+the wall effects. 
+
+First, compute the friction velocity from location k+1: 
+
+.. math::
+
+   u_*= |u_i[k+1]| \frac {\kappa}{\log [(z_{k+1}-z_k)/z0]}
+
+The expected wind speed at cell k is computed as follows: 
+
+.. math::
+
+   |u_n|= \frac{u_*}{\kappa} \log [0.5 (z_{k+1}-z_k)/z0]
+
+The methodology can be extended to include stability functions in a straight forward manner. The forcing 
+term is computed as 
+
+.. math::
+
+   F_i= - \frac {|u[k]| \hat{c} - |u_n|\hat{l}} {\tau}
+
+
+
+Here :math:`\hat{c}=(1,1,1)` is the existing normal vector from the grid and :math:`\hat{l}=(ux,uy,0)/|u_n|` is the value 
+from the log law. The calculation of :math:`\hat{l}` and :math:`u_*` can be modified in the future align with the normal (following 
+the orange arrow below).
+
+.. image:: ./images/terrain_normal.png
+   :align: center
+   :width: 30%
+
+
 Navigating source code
 ------------------------
 
@@ -445,4 +501,4 @@ overview of the AMReX GPU strategy and the higher-level functions (e.g.,
 AMR-Wind. The `Linear Solvers section
 <https://amrex-codes.github.io/amrex/docs_html/LinearSolvers_Chapter.html>`_
 provides an overview of the multi-level multigrid (MLMG) solvers used to solve
-the various linear systems within AMR-Wind.
+the various linear systems within AMR-Wind.

_sources/user/features.rst.txt

@@ -116,7 +116,7 @@ Flow physics
 
 * Geometry
 
-   * Immersed boundary
+   * Immersed boundary forcing method with stair-case type terrain and wall function [:ref:`doc <terrain>`]
 
    * Coupling with Nalu-Wind for body-conforming meshes with overset methodology
 
@@ -179,8 +179,4 @@ Current development
 
 * Temporal and spatial varying MMC forcing
 
-* Complex terrain
 
-   * Improved wall conditions, e.g., non-uniform roughness, temperature and heat fluxes
-
-   * Complex terrain though immersed boundary methods

_sources/user/inputs.rst.txt

@@ -79,6 +79,7 @@ This section documents the parameters available within each section.
    inputs_transport.rst
    inputs_turbulence.rst
    inputs_Momentum_Sources.rst
+   inputs_Temperature_Sources.rst
    inputs_ABL.rst
    inputs_ABL_meso_forcing.rst
    inputs_SyntheticTurbulence.rst

_sources/user/inputs_Momentum_Sources.rst.txt

@@ -160,3 +160,82 @@ Section: Momentum Sources
    the uniform_timetable body force type and is only active for the uniform_timetable type.  Note that the code 
    expects there to be a single-line header at the beginning of the uniform timetable file; if no header exists, 
    the first line of data will be ignored.
+
+.. input_param:: DragForcing.drag_coefficient
+
+   **type:** Real, optional
+
+   This value specifies the coefficient for the forcing term in the immersed boundary forcing method. It is currently
+   recommended to use the default value to avoid initial numerical stability. 
+
+.. input_param:: DragForcing.sponge_strength
+
+   **type:** Real, optional
+
+   The value of the sponge layer coefficient. It is recommended to use the default value of 1.0.  
+
+.. input_param:: DragForcing.sponge_density
+
+   **type:** Real, optional
+
+   The value of the sponge layer density. It is recommended to use the default value of 1.0.  
+
+.. input_param:: DragForcing.sponge_distance_west
+
+   **type:** Real, optional
+
+   This value is specified as a negative value when the inflow x-velocity is <=0. The default value is -1000 m and can be changed if strong 
+   reflections are observed. 
+
+.. input_param:: DragForcing.sponge_distance_east
+
+   **type:** Real, optional
+
+   This value is specified as a positive value when the inflow x-velocity is >=0. The default value is 1000 m and can be changed if strong 
+   reflections are observed. 
+
+.. input_param:: DragForcing.sponge_distance_south
+
+   **type:** Real, optional
+
+   This value is specified as a negative value when the inflow y-velocity is <=0. The default value is -1000 m and can be changed if strong 
+   reflections are observed. 
+
+.. input_param:: DragForcing.sponge_distance_north
+
+   **type:** Real, optional
+
+   This value is specified as a positive value when the inflow y-velocity is >=0. The default value is 1000 m and can be changed if strong 
+   reflections are observed. 
+
+.. input_param:: DragForcing.sponge_west
+
+   **type:** int, optional
+
+   This term turns on the sponge layer in the west (-x) boundary. The default value is 0. 
+
+.. input_param:: DragForcing.sponge_east
+
+   **type:** int, optional
+
+   This term turns on the sponge layer in the east (+x) boundary. The default value is 1. 
+
+.. input_param:: DragForcing.sponge_south
+
+   **type:** int, optional
+
+   This term turns on the sponge layer in the south (-y) boundary. The default value is 0. 
+
+.. input_param:: DragForcing.sponge_north
+
+   **type:** int, optional
+
+   This term turns on the sponge layer in the north (+y) boundary. The default value is 1. 
+
+
+.. input_param:: DragForcing.is_laminar
+
+   **type:** int, optional
+
+   This term turns off the sponge layer. This term is required for terrain simulations with periodic 
+   boundary conditions. The default value is 0. 

_sources/user/inputs_Temperature_Sources.rst.txt

@@ -0,0 +1,35 @@
+.. _inputs_temperature_sources:
+
+Section: Temperature Sources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. input_param:: temperature.source_terms
+
+   **type:** String(s), optional
+
+   Activates source terms for the energy equations. These strings can be 
+   entered in any order with a space between
+   each. Please consult the :doc:`../doxygen/html/index` for a
+   comprehensive list of all energy source terms available. Note that the
+   following input arguments specific to each source term will only be active
+   if the corresponding source term (the root name) is listed in 
+   :input_param:`temperature.source_terms`.
+
+.. input_param:: DragTempForcing.drag_coefficient
+
+   **type:** Real, optional
+
+   This value specifies the coefficient for the forcing term in the immersed boundary forcing method. It is currently
+   recommended to use the default value to avoid initial numerical stability. 
+
+.. input_param:: DragTempForcing.reference_temperature
+
+   **type:** Real, optional 
+
+   Reference temperature :math:`\theta_\mathrm{ref}` in Kelvin.
+   Set the term to be equal to BoussinesqBuoyancy.reference_temperature. This term 
+   is currently a placeholder and will be updated in future for considering 
+   stratification effects. The default value is 300.0. 
+
+
+

_sources/user/inputs_incflo.rst.txt

@@ -14,6 +14,7 @@ as initial conditions and discretization options.
    Physics is additive and more than one type of physics may be used.
    Current implemented physics include FreeStream, SyntheticTurbulence, ABL, Actuator, RayleighTaylor, BoussinesqBubble, TaylorGreenVortex, and ScalarAdvection (which is an example of using a passive scalar advection).
    For multiphase simulations, the MultiPhase physics must be specified, and for forcing wave profiles into the domain, the OceanWaves physics must be specified as well.
+   For immersed boundary forcing method TerrainDrag must be specified and the folder should include a `terrain.amrwind` file. 
 
 .. input_param:: incflo.density
 

_sources/walkthrough/index.rst.txt

@@ -22,4 +22,5 @@ through precursor simulations, and then turbines are placed in the flow.
 
    compiling.rst
    precursor.rst
-   turbine.rst
+   turbine.rst
+   terrain.rst

_sources/walkthrough/terrain.rst.txt

@@ -0,0 +1,93 @@
+.. spelling:word-list::
+
+   xy
+
+.. _terrain:
+
+LES with Terrain 
+============================
+
+In this walkthrough, we discuss the steps to setup a terrain simulation using the newly implemented 
+immersed boundary forcing method (IBFM). The theory for the technique can be found at
+`this link <https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2020MS002141>`_.
+
+The setup for the terrain follows the typical simulation of the atmospheric boundary layer (ABL) using 
+large eddy simulation or Reynolds-averaged Navier Stokes turbulence models. The IBFM can be used with
+periodic or inflow-outflow boundary conditions with few modifications. 
+
+The first step in including the terrain is to set the terrain variables. This is accomplished 
+by modifying the ABL physics to include the ``TerrainDrag`` flow physics: ``incflo.physics = ABL TerrainDrag``.
+This looks for the ``terrain.amrwind`` text file in the case folder. The file contains the terrain height 
+in the format ``x y terrainHt``. 
+
+The second step is the inclusion of the terrain forcing in the momentum and energy equations. This is 
+accomplished by adding ``DragForcing`` and ``DragTempForcing`` terms to ``ICNS.source_terms`` and 
+``Temperature.source_terms``, respectively. The terrain simulations requires adding a sponge layer
+at the outflow and Rayleigh damping at top of the domain. Rayleigh damping is already available from 
+the existing forcing terms and can be used directly. The sponge-layer is implemented by specifying the boundary 
+and the span. For example, a sponge layer of size 1000 m at the east (+x) boundary, 
+we need to include ``DragForcing.sponge_east=1`` and ``DragForcing.sponge_distance_east=1000`` in the input file. 
+The sponge layer is not required for periodic boundary boundary conditions. The only input recommended for the 
+energy equation source term is the specification of the internal temperature of the terrain. This is 
+set as ``DragTempForcing.reference_temperature=300``. It is recommended that the reference_temperature be set 
+to the value of the reference temperature used in the Boussinesq term. The current terrain setup can only 
+be used for the simulation of neutral ABL. A future release will update this calculation to automatically use 
+the values from a precursor simulation for both neutral and  non-neutral stratification. 
+The terrain can be visualized by including ``io.int_outputs = terrain_blank`` in the input file. 
+
+It is recommended to use the ``ProbeSampler`` to create the terrain-aligned output planes. The easiest method
+to generate the text file for ``ProbeSampler`` is to write the STL as a text file and then use offsets in 
+postprocessing to write the planes at different heights above the terrain. The terrain-aware output can 
+also be used with FAST.Farm and FLORIS.
+
+An example paraview visualization of the terrain is shown below (with three levels of refinement): 
+
+.. image:: ./visualization/terrain_blank.png
+    :width: 100%
+
+Here is a sample content of precursor and inflow-outflow input files to drive terrain simulations: 
+
+.. literalinclude:: ./terrain_precursor_inp.txt
+   :linenos:
+
+.. literalinclude:: ./terrain_inp.txt
+   :linenos:
+
+Setup using Python Tools
+------------------------
+The setup of the terrain files can be cumbersome to do by hand. A set of python tools are made available at 
+`amrTerrain <https://github.com/hgopalan/amrTerrain/tree/main/src/backend>`_. A more comprehensive set of tools 
+will be available in future at: `windtools <https://github.com/rthedin/windtools>`_.
+
+The python code is executed as follows: 
+
+.. code-block:: console
+
+    python backendinterface.py nameofyamlfile.yaml 
+
+Sample input files are available in the GitHub repository. A typical sample file looks as follows: 
+
+.. literalinclude:: ./terrain_yaml.txt
+   :linenos:
+
+The variable ``caseType`` takes three kinds of inputs: ``precursor`` or ``terrain`` or ``terrainTurbine``. For
+running terrain simulations, it is recommended to use ``caseType:terrain``. The use of ``caseType:terrainTurbine``
+also creates turbines aligned with the terrain height using the turbine latitude and longitude in the file ``turbine.csv``. 
+
+The python code first reads the ``centerLat`` and ``centerLon`` and creates a domain of size specified by 
+``west``, ``east``, ``south``, and ``north``. For the example shown above, a domain size of 10 km is created
+around ``centerLat`` and ``centerLon``. The terrain module uses the SRTM 30 m database to create the terrain. 
+It is possible to add a user-defined file to define the terrain by modifying the python code. 
+
+The ``cellSize: 128`` sets a grid resolution of 128 m at level 0.The variable ``verticalAR: 4``  sets ``dz=4dx=4dy``. 
+You do not need ``Hypre`` to run the high aspect ratio simulations. User has to manually edit the 
+input file to create refinement regions in area of interest around the terrain. 
+
+All other inputs in the yaml file are for creating dummy inputs to the amr-wind simulations and user can 
+modify them manually to fit their needs. The inputs ``caseType: "terrainTurbine"`` and ``turbineType: "UniformCtDisk"``
+are useful for aligning the turbine vertically with the terrain. The file includes all the turbines within the continental 
+US and have to be modified for other locations. The turbine type information is ad-hoc and has to be manually modified by 
+the user for the specific turbine type. A future update to the code will include options to specify the turbine information 
+from a text file. 
+
+

_static/basic.css

@@ -1,12 +1,5 @@
 /*
- * basic.css
- * ~~~~~~~~~
- *
  * Sphinx stylesheet -- basic theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
@@ -115,15 +108,11 @@ img {
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {
-    margin: 10px 0 0 20px;
-    padding: 0;
+    margin-top: 10px;
 }
 
 ul.search li {
-    padding: 5px 0 5px 20px;
-    background-image: url(file.png);
-    background-repeat: no-repeat;
-    background-position: 0 7px;
+    padding: 5px 0;
 }
 
 ul.search li a {

_static/doctools.js

@@ -1,12 +1,5 @@
 /*
- * doctools.js
- * ~~~~~~~~~~~
- *
  * Base JavaScript utilities for all Sphinx HTML documentation.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 "use strict";
 

_static/language_data.js

@@ -1,13 +1,6 @@
 /*
- * language_data.js
- * ~~~~~~~~~~~~~~~~
- *
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];