Per #3, adding more tutorial files from the FastEddyTutorial repo

docs/Tutorial/cases/CBL.rst

@@ -0,0 +1,73 @@
+Dry convective boundary layer
+================================
+
+This is the convective boundary layer scenario described by Sauer and Munoz-Esparza (2020). This case represents the boundary layer conditions at the SWiFT facility near Lubbock, Texas at 4 July 2012 during the period of 18Z-20Z (12:00–14:00 local time), the strongest period of convection on the day.
+
+Input parameters
+----------------
+
+* Number of grid points: :math:`[N_x,N_y,N_z]=[600,594,122]`
+* Isotropic grid spacings in the horizontal directions: :math:`[dx,dy]=[20,20]` m, vertical grid is :math:`dz=20` m at the surface and stretched with verticalDeformFactor :math:`=0.80`
+* Domain size: :math:`[12.0 \times 11.9 \times 3.0]` km
+* Model time step: :math:`0.05` s
+* Geostrophic wind: :math:`[U_g,V_g]=[9,0]` m/s
+* Advection scheme: Hybrid 5th order upwind
+* Time scheme: 3rd-order Runge Kutta
+* Latitude: :math:`33.5^{\circ}` N
+* Surface potential temperature: :math:`309` K
+* Potential temperature profile:
+.. math::
+  \partial{\theta}/\partial z =
+    \begin{cases}
+      0 & \text{if $z$ $\le$ 600 m}\\
+      0.004 & \text{if $z$ > 600 m}
+    \end{cases}
+* Surface heat flux:  :math:`0.35` Km/s
+* Surface roughness length: :math:`z_0=0.05` m
+* Rayleigh damping layer: uppermost :math:`400` m of the domain
+* Initial perturbations: :math:`\pm 0.25` K 
+* Depth of perturbations: :math:`400` m
+* Top boundary condition: free slip
+* Lateral boundary conditions: periodic
+* Time period: :math:`4` h
+
+Execute FastEddy
+----------------
+
+Run FastEddy using the input parameters file /examples/Example02_CBL.in. To execute FastEddy, follow the instructions here: https://github.com/NCAR/FastEddy-model/blob/main/README.md.
+
+Visualize the output
+--------------------
+
+Open the Jupyter notebook entitled "MAKE_FE_TUTORIAL_PLOTS.ipynb" and execute it using setting: case = 'convective'.
+
+XY-plane views of instantaneous velocity components at :math:`t=4` h (FE_CBL.288000):
+
+.. image:: ../images/UVWTHETA-XY-convective.png
+  :width: 1200
+  :alt: Alternative text
+
+XZ-plane views of instantaneous velocity components at :math:`t=4` h (FE_CBL.288000):
+
+.. image:: ../images/UVWTHETA-XZ-convective.png
+  :width: 900
+  :alt: Alternative text
+
+Mean (domain horizontal average) vertical profiles of state variables at :math:`t=4` h (FE_CBL.288000):
+
+.. image:: ../images/MEAN-PROF-convective.png
+  :width: 750
+  :alt: Alternative text
+
+Horizontally-averaged vertical profiles of turbulence quantities :math:`t=3-4` h [perturbations are computed at each point relative to the previous 1-hour mean, and then horizontally averaged]:
+
+.. image:: ../images/TURB-PROF-convective.png
+  :width: 1200
+  :alt: Alternative text
+
+Analyze the output
+------------------
+
+* Using the XY and XZ cross sections, discuss the characteristics (scale and magnitude) of the resolved turbulence.
+* What is the boundary layer height in the convective case?
+* Using the vertical profile plots, explain why the boundary layer is unstable.

docs/Tutorial/cases/MBL.rst

@@ -0,0 +1,64 @@
+Moist cloud-topped boundary layer
+=================================
+
+This tutorial case is the BOMEX LES intercomparison study from Siebesma et al. (2003), corresponding to a non-precipitating shallow cumulus cloud case informed by the Barbados Oceanographic and Meteorological Experiment (BOMEX, Holland & Rasmusson, 1973). The forcing consists of two different sources including prescribed kinematic surface fluxes of sensible and latent heat and large-scale forcing (LSF) tendencies due to mesoscale horizontal advection of water vapor mixing ratio, liquid potential temperature and horizontal momentum. The LSF includes subsidence to compensate the integrated effect of surface fluxes and advection tendencies, formulated as a prescribed time-invariant subsidence profile multiplied by the vertical gradient of horizontally averaged fields accros the domain. The main settings of this case are listed below and are further detailed in Munoz-Esparza et al. (2022).
+
+Input parameters
+----------------
+
+* Number of grid points: :math:`[N_x,N_y,N_z]=[152,146,122]`
+* Isotropic grid spacings: :math:`[dx,dy,dz]=[100,100,40]` m
+* Domain size: :math:`[15.2 \times 14.6 \times 4.9]` km
+* Model time step: :math:`0.075` s
+* Geostrophic wind: :math:`[U_g,V_g]=[10,0]` m :math:`\mbox{s}^{-1}`
+* Advection schemes: 5th-order upwind (dry dynamics), 3rd-order upwind (water vapor), and 3rd-order WENO (liquid water)
+* Time scheme: 3rd-order Runge Kutta
+* Latitude: :math:`14.94^{\circ}` N
+* 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
+* Rayleigh damping layer: uppermost :math:`500` m of the domain
+* Initial perturbations: :math:`\pm 0.1` K
+* Depth of perturbations: :math:`1600` m
+* Top boundary condition: free slip
+* Lateral boundary conditions: periodic
+* Time period: :math:`6` h
+* Initital conditions: vertical profiles of :math:`u`, :math:`q_v`, and SGSTKE as specified in Siebesma et al. (2003)
+* Large-scale forcings: vertical profiles of subsidence and horizontal advection of potential temperature and water vapor as specified in Siebesma et al. (2003)
+
+Execute FastEddy
+----------------
+
+Run FastEddy using the input parameters file /examples/Example04_BOMEX.in. Note that the BOMEX case requires an initial condition provided in /datasets/BOMEX_IC/FE_BOMEX.0. To execute FastEddy, follow the instructions here: https://github.com/NCAR/FastEddy-model/blob/main/README.md.
+
+Visualize the output
+--------------------
+
+Open the Jupyter notebook entitled "FE_Postrocessing_Example04_BOMEX.ipynb" and execute it.
+
+Time evolution of domain averaged total cloud cover (:math:`\alpha_c`) and liquid water path (LWP):
+
+.. image:: ../images/TimeEvolution_cldthres0.01.png
+  :width: 1200
+  :alt: Alternative text
+
+Vertical profiles of potential temperature (:math:`\theta`), water vapor (:math:`q_v`), horizontal velocity components (:math:`u`, :math:`v`), and liquid content (:math:`q_l`). Thin black dashed lines correspond to the initial conditions. Profiles are averaged for the last 3 hr (:math:`t = 180-360` min) and over horizontal domain slabs:
+
+.. image:: ../images/VerticalProfiles.png
+  :width: 900
+  :alt: Alternative text
+
+Vertical profiles of turbulence kinetic energy (TKE), vertical velocity variance (:math:`\sigma^2_w`), and vertical turbulent fluxes of zonal momentum (:math:`\langle u'w' \rangle`), water vapor (:math:`\langle w'q_v' \rangle`), liquid cloud, and virtual potential temperature (:math:`\langle w'q_l' \rangle`). Profiles are averaged for the last 3 hr (:math:`t = 180–360` min) and perturbations are computed as the departure from horizontal slab averages. These turbulence quantities are the sum of resolved and subgrid-scale components.
+
+.. image:: ../images/VerticalProfilesTurb.png
+  :width: 1200
+  :alt: Alternative text
+
+Analyze the output
+------------------
+
+* Using the time series of cloud properties, could you identify when the simulated shallow cumulus cloud deck has reached quasi-eqilibrium?
+* What is the effect of boundary-layer turbulence to the mean profiles of momentum?
+* Identify the vertical extent of the cloud layer.
+* Which of the turbulent vertical transport terms is responsible for the resulting vertical liquid cloud distribution?

docs/Tutorial/cases/NBL.rst

@@ -0,0 +1,78 @@
+Dry neutral boundary layer
+===========================
+
+Background
+----------
+
+This is a canonical neutral boundary layer scenario. The case is broadly based upon Sauer and Munoz-Esparza (2020) but is not identical. A geostrophic wind is prescribed over ground with a set aerodynamic roughness length under a neutrally stratified boundary layer. The purpose of this test case is to visualize and analyze the resultant flow and turbulence characteristics that develop when the LES reaches statistical steady-state.
+
+Input parameters
+----------------
+
+* Number of grid points: :math:`[N_x,N_y,N_z]=[640,634,58]`
+* Isotropic grid spacings in the horizontal directions: :math:`[dx,dy]=[15,15]` m, vertical grid is :math:`dz=15` m at the surface and stretched with verticalDeformFactor :math:`=0.75`
+* Domain size: :math:`[9.6 \times 9.51 \times 1.08]` km
+* Model time step: :math:`0.04` s
+* Advection scheme: 5th-order upwind
+* Time scheme: 3rd-order Runge Kutta
+* Geostrophic wind: :math:`[U_g,V_g]=[10,0]` m/s
+* Latitude: :math:`54.0^{\circ}` N
+* Surface potential temperature: :math:`300` K
+* Potential temperature profile:
+.. math::
+  \partial{\theta}/\partial z =
+    \begin{cases}
+      0 & \text{if $z$ $\le$ 500 m}\\
+      0.08 & \text{if 500 m < $z$ $\le$ 650 m}\\
+      0.003 & \text{if $z$ > 650 m}
+    \end{cases} 
+* Surface heat flux:  :math:`0.0` Km/s
+* Surface roughness length: :math:`z_0=0.1` m
+* Rayleigh damping layer: uppermost :math:`400` m of the domain
+* Initial perturbations: :math:`\pm 0.25` K 
+* Depth of perturbations: :math:`375` m
+* Top boundary condition: free slip
+* Lateral boundary conditions: periodic
+* Time period: :math:`7` h
+
+Execute FastEddy
+----------------
+
+Run FastEddy using the input parameters file /examples/Example01_NBL.in. To execute FastEddy, follow the instructions here: https://github.com/NCAR/FastEddy-model/blob/main/README.md.
+
+Visualize the output
+--------------------
+
+Open the Jupyter notebook entitled "MAKE_FE_TUTORIAL_PLOTS.ipynb" and execute it using setting: case = 'neutral'.
+
+XY-plane views of instantaneous velocity components at :math:`t=7` h (FE_NBL.630000):
+
+.. image:: ../images/UVWTHETA-XY-neutral.png
+  :width: 1200
+  :alt: Alternative text
+
+XZ-plane views of instantaneous velocity components at :math:`t=7` h (FE_NBL.630000):
+
+.. image:: ../images/UVWTHETA-XZ-neutral.png
+  :width: 900
+  :alt: Alternative text
+
+Mean (domain horizontal average) vertical profiles of state variables at :math:`t=7` h (FE_NBL.630000):
+
+.. image:: ../images/MEAN-PROF-neutral.png
+  :width: 750
+  :alt: Alternative text
+
+Horizontally-averaged vertical profiles of turbulence quantities at :math:`t=6-7` h [perturbations are computed at each time instance from horizontal-slab means, then averaged horitontally and over the previous 1-hour mean]:
+
+.. image:: ../images/TURB-PROF-neutral.png
+  :width: 1200
+  :alt: Alternative text 
+
+Analyze the output
+------------------
+
+* Using the XY and XZ cross sections, discuss the characteristics (scale and magnitude) of the resolved turbulence.
+* What is the boundary layer height in the neutral case?
+* Using the vertical profile plots, explain why the boundary layer is neutral.
+

docs/Tutorial/cases/SBL.rst

@@ -0,0 +1,75 @@
+Dry stable boundary layer
+==========================
+
+Background
+------------------
+
+This is the stable boundary layer scenario described by Sauer and Munoz-Esparza (2020). This the stable boundary layer scenario outlined in Kosovic and Curry (2000).
+
+Input parameters
+----------------
+
+* Number of grid points: :math:`[N_x,N_y,N_z]=[128,126,122]`
+* Isotropic grid spacings: :math:`[dx,dy,dz]=[3.125,3.125,3.125]` m
+* Domain size: :math:`[0.40 \times 0.39 \times 0.38]` km
+* Model time step: :math:`0.005` s
+* Geostrophic wind: :math:`[U_g,V_g]=[8,0]` m/s
+* Advection scheme: 5th-order upwind
+* Time scheme: 3rd-order Runge Kutta
+* Latitude: :math:`73^{\circ}` N
+* Surface potential temperature: :math:`265` K
+* Potential temperature profile:
+.. math::
+  \partial{\theta}/\partial z =
+    \begin{cases}
+      0 & \text{if $z$ $\le$ 100 m}\\
+      0.01 & \text{if $z$ > 100 m}
+    \end{cases}   
+* Surface heat flux:  :math:`-0.25` K/h
+* Surface roughness length: :math:`z_0=0.1` m
+* Rayleigh damping layer: uppermost :math:`75` m of the domain
+* Initial perturbations: :math:`\pm 0.25` K 
+* Top boundary condition: free slip
+* Lateral boundary conditions: periodic
+* Time period: :math:`12` h
+
+Execute FastEddy
+----------------
+
+Run FastEddy using the input parameters file /examples/Example03_SBL.in. To execute FastEddy, follow the instructions here: https://github.com/NCAR/FastEddy-model/blob/main/README.md.
+
+Visualize the output
+--------------------
+
+Open the Jupyter notebook entitled "MAKE_FE_TUTORIAL_PLOTS.ipynb" and execute it using setting: case = 'stable'.
+
+XY-plane views of instantaneous velocity components at :math:`t=12` h (FE_SBL.8640000):
+
+.. image:: ../images/UVWTHETA-XY-stable.png
+  :width: 1200
+  :alt: Alternative text
+
+XZ-plane views of instantaneous velocity components at :math:`t=12` h (FE_SBL.8640000):
+
+.. image:: ../images/UVWTHETA-XZ-stable.png
+  :width: 600
+  :alt: Alternative text
+
+Mean (domain horizontal average) vertical profiles of state variables at :math:`t=12` h (FE_SBL.8640000):
+
+.. image:: ../images/MEAN-PROF-stable.png
+  :width: 750
+  :alt: Alternative text
+
+Horizontally-averaged vertical profiles of turbulence quantities at :math:`t=11-12` h (FE_TEST.8640000) [perturbations are computed at each point relative to the previous 1-hour mean, and then horizontally averaged]:
+
+.. image:: ../images/TURB-PROF-stable.png
+  :width: 1200
+  :alt: Alternative text
+
+Analyze the output
+------------------
+
+* Using the XY and XZ cross sections, discuss the characteristics (scale and magnitude) of the resolved turbulence.
+* What is the boundary layer height in the stable case?
+* Using the vertical profile plots, explain why the boundary layer is stable.

docs/Tutorial/index.rst

@@ -3,3 +3,28 @@
 
   introduction.rst
 
+.. toctree::
+  :caption: IDEAL TEST CASES 
+  :numbered:
+
+  cases/NBL.rst
+  cases/CBL.rst
+  cases/SBL.rst
+  cases/MBL.rst
+
+.. toctree::   
+  :caption: SENSITIVITY TESTS
+
+  sensitivity.rst
+
+.. only
+    
+  .. toctree::
+    :caption: QUESTIONS
+  
+    questions.rst
+   
+  .. toctree::
+    :caption: SENSITIVITY TESTS
+ 
+    sensitivity.rst

docs/Tutorial/questions.rst

@@ -0,0 +1,10 @@
+****************************
+Comparison of the four cases
+****************************
+
+(Here we can ask some questions about comparing and contrasting the results from all the cases. Some potential questions are given below...)
+
+* What are main differences in the scale and magnitude of the resolved turbulence among the dry cases? 
+* How do the statistically steady-state boundary layers differ among the dry cases?
+* How does the TKE vary among the dry cases? Which case has the highest TKE and why? 
+* Other... 

docs/Tutorial/sensitivity.rst

@@ -0,0 +1,23 @@
+************
+Instructions
+************
+
+* Re-run the neutral case with :math:`[N_x,N_y,N_z]=[400,400,122]` and isotropic grid spacings of :math:`[dx,dy,dz]=[10,10,10]`. Adjust the model time step accordingly. Re-make all plots and discuss the differences between the control case. How much longer did it take to complete the simulation? 
+* Re-run the convective case with a surface heat flux of :math:`=+0.70` Km/s. Re-make all plots and discuss the differences between the control case. 
+* Re-run the neutral case with :math:`z_0=0.3` m. Re-make all plots and discuss the differences between the control case. 
+* Re-run the neutral case with the first order upwind advection scheme. Re-make all plots and discuss the differences between the control case. Why is the first order scheme a bad choice? 
+* Re-run the stable case with a surface cooling rate of :math:`-0.5` K/h. Re-make all plots and discuss the differences between the control case. 
+* Re-run the stable case using half of the GPUs used in the control simulation. How much slower does the case run?
+
+* Re-run the BOMEX case with a higher-order advection for water vapor (moistureAdvSelectorQv = 3). What is the impact of the increased effective resolution on dynamical, thermodynamical and microphysical quantities, along with turbulence variability and fluxes? How does that change influce the comparison to the other BOMEX LES models?
+
+.. only
+
+    (Here, the user will make some modifications to the default parameters such as changing the grid spacing, stretching, model time step, advection     
+
+    scheme,    number of grid points, domain decomposition and number of GPUs, etc, etc. Here, the user will execute the sensitivity test, and visualize 
+    and analyze the     output)
+
+     x^2+y^2=z^2
+
+      frac{ sum_{t=0}^{N}f(t,k) }{N}