Feature dev v5.0 doc (#127)

* SHFR tutorial section. Updates to publications and documentation contributors

* Fix to publications section

* Another small fix to the publications section

* Another small fix to the publications section

* Changing nlcd_name to landcover_table in the documentation

* Mods to stabilityScheme parameter

* Fix to stabilityScheme parameter mods

* Updated Zenodo links for BOMEX and GAD data

* Updating documentation to include the Addendum for Using MPAS Forecasts as Input Data

* Fixing warning for duplicate explicit target name for Zenodo record text by adding MPAS to the second reference

* LES-to-LES section.

* Adding page about code contributions to FastEddy

* Adding customization for the pre-processing parameters

* Adding RST documentaiton for pre-procession parameters

* Adding csv files for pre-processing parameters

* Adding pre-processing workflow image

* Adding preprocessing image

* Adding a reference to the workflow figure for referencing elsewhere.

* Attempt to move source for figure to a different location

* Modified naming and formatting

* Adding feedback and updates page

* Adding feedback and updates page

* Adding to feedback and updates to index

* Added Share Feedback or Ideas section with link to feedback form

* Attempting to fix formatting

* Attempt #2 to fix formatting

* Updating links for feedback and updates forms

* Efficient output (part 1)

* Efficient output (part 2)

* A couple fixes to the efficient output section

* Updated figures for tutorials 02,04,06,08 and some small adjustments

* virtual towers entries for the model reference guide

* Small adjustment to towerIOSelector description

* Attempting to modify formatting for tables in Efficient Output Modes

* Attempting to resolve warnings

* Updated figure for tutorial 10 (urban extension)

* Updated figures following v5.0 developments from Examples 1,3,5,7 & 9.

* Updating Zenodo record for BOMEX data

* Minor formatting updates

* Attempting to modify table widths

* Attempting to modify table widths for pre-processing

* Adjustment of z0 to the new 0.001 m value in the BOMEX tutorial documentation.

* renamed the binary_output.rst file to efficient_oiutput.rst to be consistent with the section title. Also added a few minor modifications to the content in that new section.

* Fixed a formatting typo in efficient_output.rst.

---------

Co-authored-by: domingom <domingom@ucar.edu>
Co-authored-by: Jeremy Sauer <jsauer@ucar.edu>

Author: 3 people

docs/Tutorials/cases/DISPERSION.rst

@@ -45,11 +45,7 @@ Note that this example requires creation of a terrain and source specification f
 1. Execute the Jupyter notebook provided in **tutorials/notebooks/Dispersion_PrepTerrain.ipynb** to create the topography file *Topography_504x498.dat* that corresponds to a Witch of Agnesi hill of 15 m height.
 2. Execute the Jupyter notebook provided in **/tutorial/notebooks/Dispersion_PrepAuxSrc.ipynb** to create the source specification input file. This example will add two sources at the first vertical grid levels upstream (*x* = 930 m) and downstream (*x* = 1082 m) of the hill. The emissions begin :math:`45` min into the simulation.
 
-Two FastEddy simulation setups are provided for this tutorial, corresponding to weakly stable (*Example07_DISPERSION_SBL.in*) and convective conditions (*Example07_DISPERSION_CBL.in*). The terrain preparation and source input file steps only need to be carried out once. Additionally, the CBL case is set up to demonstrate the use of a rank-wise binary output mode in FastEddy for efficient dumping of the model state to file. Personalize and use the batch submission script **/scripts/batch_jobs/fasteddy_convert_pbs_script_casper.sh** which will invoke a python script (**/scripts/python_utilities/post-processing/FEbinaryToNetCDF.py**) to convert the rank-wise binary files from each output timestep into a single aggregate NetCDF output file per timestep analogous to those resulting from the SBL case. Users can run the following `conda activate` command if running on Casper:
-
-.. code::
-
-   conda activate /glade/u/fehelp/casper/conda-envs/mpi4py-casper-oneapi-2024.2.1-openmpi-5.0.6
+Two FastEddy simulation setups are provided for this tutorial, corresponding to weakly stable (*Example07_DISPERSION_SBL.in*) and convective conditions (*Example07_DISPERSION_CBL.in*). The terrain preparation and source input file steps only need to be carried out once.
 
 Visualize the output
 --------------------

docs/Tutorials/cases/MBL.rst

@@ -18,7 +18,7 @@ Input parameters
 * Surface potential temperature: :math:`299.1` K
 * Surface sensible heat flux: :math:`8 \times 10^{-3}` K m :math:`\mbox{s}^{-1}`
 * Surface latent heat flux: :math:`5.2 \times 10^{-5}` m :math:`\mbox{s}^{-1}`
-* Surface roughness length: :math:`z_0=0.0002` m
+* Surface roughness length: :math:`z_0=0.001` m
 * Rayleigh damping layer: uppermost :math:`500` m of the domain
 * Initial perturbations: :math:`\pm 0.1` K
 * Depth of perturbations: :math:`1600` m
@@ -31,7 +31,7 @@ Input parameters
 Execute FastEddy
 ----------------
 
-Note that this example moist dynamics validation case example requires an additional dataset available as a gzip compressed tape archive file, *Moist_BOMEX.tar.gz*, at this `Zenodo record <https://zenodo.org/records/10982246>`_. The contents of the archive include an initial conditions file *FE_BOMEX.0*, which is needed to run FastEddy for this case. The archive dataset also contains results from the 11 models that participated in the original Siebesma et al. 2003 model intercomparison as NetCDF files.  The FastEddy code will write its output to an *output* subdirectory. Please create an *output* directory, if one does not already exist.
+Note that this example moist dynamics validation case example requires an additional dataset available as a gzip compressed tape archive file, *Moist_BOMEX.tar.gz*, at this `Zenodo record <https://zenodo.org/records/20273966>`_. The contents of the archive include an initial conditions file *FE_BOMEX.0*, which is needed to run FastEddy for this case. The archive dataset also contains results from the 11 models that participated in the original Siebesma et al. 2003 model intercomparison as NetCDF files.  The FastEddy code will write its output to an *output* subdirectory. Please create an *output* directory, if one does not already exist.
 
 1. Create a working directory to run the FastEddy tutorials and change to that directory.
 2. Create a **Example04_BOMEX** subdirectory and change to that directory.

docs/Tutorials/cases_extensions/GAD.rst

@@ -2,7 +2,7 @@
 Turbine array flow with the GAD model
 =====================================
 
-This is an idealized scenario of wind farm (3 x 3 turbine array) flow in neutrally stratified boundary layer with an evolving wind direction spanning 90 degrees of clockwise turning over 40 minutes. This idealized scenario demonstrates the generalized actuator disk (GAD) implementation in FastEddy (*Sanchez Gomez et al., 2024*), with the inclusion of a turbine yawing capability to align with the meteorological wind direction at the turbine's nacelle. The initial and boundary conditions for this idealized case are derived from a horizontally averaged LES run of a neutral ABL with a geostrophic wind aligned in the zonal direction (:math:`[U_g,V_g]=[10.0,0.0]` m/s) with and a latitude of :math:`40.0^{\circ}` N. The required datasets to run this tutorial are provided at this `Zenodo record <https://zenodo.org/records/17400464>`_.
+This is an idealized scenario of wind farm (3 x 3 turbine array) flow in neutrally stratified boundary layer with an evolving wind direction spanning 90 degrees of clockwise turning over 40 minutes. This idealized scenario demonstrates the generalized actuator disk (GAD) implementation in FastEddy (*Sanchez Gomez et al., 2024*), with the inclusion of a turbine yawing capability to align with the meteorological wind direction at the turbine's nacelle. The initial and boundary conditions for this idealized case are derived from a horizontally averaged LES run of a neutral ABL with a geostrophic wind aligned in the zonal direction (:math:`[U_g,V_g]=[10.0,0.0]` m/s) with and a latitude of :math:`40.0^{\circ}` N. The required datasets to run this tutorial are provided at this `Zenodo record <https://zenodo.org/records/19462617>`_.
 
 The GAD model is activated by the selector (:code:`GADSelector = 1`) in the parameters file. This case uses the parameters file **tutorials/examples/Example09_GAD.in**. The lines below correspond to additions to the FastEddy parameters file necessary for turbine-inclusive LES runs. These correspond to the turbine specification file (:code:`turbineSpecsFile`) and a parameter to choose whether or not to write GAD forces to output files (:code:`GADoutputForces`).
 

docs/Tutorials/cases_extensions/WRF_coupling_case0_FE_urban.rst

@@ -12,7 +12,7 @@ In the *GeoSpec* preprocessing step, and additional 2d field describing building
 
 This tutorial provides an example georeference input file with building heights for downtown Dallas, TX (:code:`Dallas_input_Oct2025_lod13.nc`). The *geospec.json* parameter file option :code:`urban_opt : 1` needs to be selected for building height information to be ingested in the reference standard-format NetCDF output file upon execution of **GeoSpec.py**.
 
-The same :code:`urban_opt : 1` option needs must be included in the subsequent *SimGrid* and *GenICBCs* stages, where building information is used for the creation of a :code:`BuildingMask` array containing gridded information of building presence, and ensuring that winds, subgrid-scale TKE and hydrometeors are set to zero within buildings for both initial and boundary conditions.
+The same :code:`urban_opt : 1` option needs must be included in the subsequent *SimGrid* and *GenICBCs* stages, where building information is used for the creation of a :code:`BuildingMask` array containing gridded information of building presence, and ensuring that winds, subgrid-scale TKE and hydrometeors are set to zero within buildings for both initial and boundary conditions. In this example *center_lat* and *center_lon* are (32.7835, -96.8092), required by **simgrid.json**.
 
 After initial and boundary conditions have been created, a building-resolving FastEddy simulation can be undertaken by activating the urban model capability in the parameters file (see **tutorials/examples/Example10_REALCASE_Dallas_urban.in**).
 
@@ -34,3 +34,30 @@ The model used to represent buildings follows the immersed body force approach d
   :alt: Alternative text
 
 Full citation references can be found in the :doc:`Publications <../../publications>` section.
+
+Surface Heat Flux Redistribution
+--------------------------------
+
+The Surface Heat Flux Redistribution (SHFR) option is included in the FastEddy URBAN module and therefore requires the urban capability enabled (:code:`urban_opt : 1`). When buildings are explicitly represented in FastEddy, surface sensible and latent heat fluxes are masked to zero over building-covered grid cells. This masking can reduce the total heat input in densely built areas.
+
+The SHFR option compensates for this effect by redistributing the suppressed surface heat flux over the surrounding non-building grid cells. The redistribution is computed during the preprocessing stage with **SimGrid.py** and stored as a 2d field named :code:`UrbanHeatRedis`. During the FastEddy simulation, this factor is applied multiplicatively to the surface heat fluxes.
+
+When buildings are explicitly resolved, using conventional urban roughness lengths derived for unresolved urban canopies may lead to a double counting of building-induced drag. To avoid this issue, SHFR is designed to operate together with a modified "street-like" roughness length for urban land-cover categories. This reduced roughness represents the aerodynamic properties of streets and open urban surfaces. The modified roughness values must therefore be used during the execution of **GeoSpec.py** (see section 3.1.1).
+
+The SHFR algorithm accounts for the difference between fluxes computed with the original land-cover roughness and those computed with the modified street-like roughness. For this reason, SHFR requires a land-cover table with both values: *z0* and *z0urbanLES*. *z0urbanLES* must be set to 0.0 for non-urban categories.
+
+To create the :code:`UrbanHeatRedis` field, add the following entries to the **simgrid.json** file:
+
+.. code-block:: none
+
+        "urban_heatRedis_opt": 1,
+        "landcover_table": "/path_to_landcover_table/landcover_table.csv"
+
+Note that `landcover_table` entry is the same as the landcover table specified in **geospec.json**. If :code:`urban_heatRedis_opt : 0`, no redistribution is applied and the :code:`landcover_table` entry can be left empty.
+
+To run a building-resolving FastEddy simulation with SHFR, the capability must also be activated in the FastEddy parameters file:
+
+.. code-block:: none
+
+        #-- URBAN
+        urban_heatRedis = 1 # selector to activate surface heat redistribution

docs/Tutorials/cases_real.rst

@@ -8,9 +8,21 @@ Real cases are performed by dynamically downscaling from a mesoscale model such
 * Step 2: **SimGrid**. Simulation grid definition step. Defines a FastEddy gridded domain at a specificed grid spacing, location and extent using the file resulting from ther previous GeoSpec step and a FastEddy input parameters file (with targeted domain configuration parameters) as inputs.
 * Step 3: **GenICBCs**. Generate initial conditions/boundary (ICBCs) conditions step. Creates ICBCs for a targeted FastEddy domain (defined in the SimGrid step) from a set of mesoscale model results. 
 
+.. figure:: /_static/FastEddy_Pre-Processing_Workflow_Gemini.png
+   :alt: FastEddy Pre-Processing Workflow Diagram
+   :align: center
+   :width: 100%
+   :name: pre-processing_workflow_diagram	   
+
+   FastEddy Pre-Processing Workflow Diagram\ *
+   
 The following tutorial provides a practical example of performing these preprocessing steps followed by a corresponding weather-driven FastEddy simulation for a real-world downscaled scenario. 
 
 .. toctree::
 
    cases_real/WRF_coupling_case0.rst
    cases_real/WRF_coupling_case0_FE.rst
+
+.. rst-class:: footnote-source
+
+   \* Source: Google. (2026). Gemini (Version 3 Flash) [Large language model]. https://gemini.google.com	       

docs/Tutorials/cases_real/WRF_coupling_case0.rst

@@ -56,7 +56,7 @@ If the JSON file option *save_plot_opt* is set to 1, then a plot will be produce
 
 SimGrid
 -------
-The second preprocessing step is **SimGrid.py**. The purpose of this step is to set up a FastEddy grid over a domain located within the area covered by the GIS file generated with *GeoSpec.py*. The location of the center of the FastEddy domain is specified in the **simgrid.json** file by the parameters *center_lat* and *center_lon*. The number of points in each direction (:code:`Nx`, :code:`Ny`, :code:`Nz`), grid spacings (:code:`d_xi`, :code:`d_eta`, :code:`d_zeta`), and vertical stretching parameters (:code:`verticalDeformFactor`, :code:`verticalDeformQuadCoeff`) required to set up a grid are read in from a FastEddy parameters file (*FE_params_file*). *SimGrid.py* performs decimation or interpolation between the *GeoSpec.py* output reference resolution and the parameter-specified grid spacing of the target FastEddy domain for surface fields, in addition to establishing a terrain following vertical coordinate grid. Once all the required input files are ready, **SimGrid.py** can be executed:
+The second preprocessing step is **SimGrid.py**. The purpose of this step is to set up a FastEddy grid over a domain located within the area covered by the GIS file generated with *GeoSpec.py*. The location of the center of the FastEddy domain is specified in the **simgrid.json** file by the parameters *center_lat* and *center_lon* (40.5948 and -105.1380 for this example). The number of points in each direction (:code:`Nx`, :code:`Ny`, :code:`Nz`), grid spacings (:code:`d_xi`, :code:`d_eta`, :code:`d_zeta`), and vertical stretching parameters (:code:`verticalDeformFactor`, :code:`verticalDeformQuadCoeff`) required to set up a grid are read in from a FastEddy parameters file (*FE_params_file*). *SimGrid.py* performs decimation or interpolation between the *GeoSpec.py* output reference resolution and the parameter-specified grid spacing of the target FastEddy domain for surface fields, in addition to establishing a terrain following vertical coordinate grid. Once all the required input files are ready, **SimGrid.py** can be executed:
 
 .. code-block:: none
 
@@ -118,3 +118,31 @@ With these additions, WRF will generate a set of timestamped *wrf_fasteddy_* fil
    python ./GenICBCs.py -f genicbcs.json
 
 Successful completion will create an initial condition file (*FE_interp_170000UTC.0*) and a set of boundary condition files (*FE_Bndys.**) where the index indicates the number of second increments from the initial time (frequency in seconds is specified by the parameter :code:`secInc` in **genicbcs.json**).
+
+Nested LES-to-LES with FastEddy input data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**GenICBCs.py** has been extended to allow nesting within FastEddy LES model data. In order to enable that option, *parent_model* variable in **genicbcs.json** needs to be set to 1. In the case of using an idealized FastEddy simulation as the source input data (i.e., constant latitude and longitude throughout the domain), the variable *ideal_opt* needs to be activated, in order for the horizontal coordinates to be used as reference to locate the domain instead of geographic coordinates used for real cases. 
+
+.. note::
+
+   * The *parent_model* option needs to be set to 0 for WRF nesting and to 1 for nesting within FastEddy model data.
+   * The *nest_tke_opt* option allows for using TKE from the parent model as initial and boundary conditions. If not activated, a uniform value of 1.0e-10 m2/s2 is used (initial versions of the coupling capabilities preceding FastEddy v5.0).
+
+Addendum: Using MPAS model data as input
+----------------------------------------
+If one wishes to use MPAS model files as inputs to FastEddy, a series of steps may be performed to prepare the data for use before the **GenICBCs.py** preprocessing step. The required data from MPAS forecasts are the **history.YYYY-MM-DD_HH.mm.ss.nc**, **diag.YYYY-MM-DD_HH.mm.ss.nc**, and **init.nc** files. These files must first be converted from the MPAS unstructured grid to match the WRF lat-lon grid. Various tools are available to perform the interpolation, including `MPASSIT <https://github.com/NOAA-GSL/MPASSIT>`_. An example batch submission script, **run_mpassit.sh**, and variable lists, **varlists_mpassit_fasteddy**, are available in **scripts/batch_jobs/**, which can be configured with paths to MPAS outputs, a build of MPASSIT, and a set of run parameters to determine the date and time corresponding to input data. This batch submission script is run with
+
+.. code-block:: none
+
+   qsub run_mpassit.sh
+
+The resulting output will be named **proc.YYYY-MM-DD_HH.mm.ss.nc**. The proc files required to run this addendum are provided at this `MPAS Zenodo record <https://zenodo.org/records/19410452>`_.
+
+A further conversion step must then be performed in order to ensure that the variables output by MPAS match the requirements of **GenICBCs.py** and FastEddy. In this step, density and geopotential heights not provided in the standard MPAS output are derived and appended to the WRF-like output files created by MPASSIT. A conversion script is available in **scripts/python_utilities/coupler/**. You may configure **mpassit_to_fasteddy.py** with the input file **mpassit_to_fasteddy.json**, similar to the configuration of **genicbcs.json** by setting file name prefixes and date and time information for the ICBC data. The conversion script is run with 
+
+.. code-block:: none
+
+   python ./mpassit_to_fasteddy.py -f mpassit_to_fasteddy.json
+
+
+Once completed, the resulting output files should appear with a naming scheme that matches the WRF filename date formatting and can then be used as input to **GenICBCs.py** to generate FastEddy input data.