Feature update tutorial instructions (#47)

* Modifying wording

* Updating text

* Fixing formatting

* Fixing formatting and updating text

* Updating formatting and modifying text

* Fixed typo in filename and updated text

* Corrected path

* Updated figure directory name

* Updated text

* Updating instructions

* Updating text

* Updating

* Removing loose close parenthesis

* Updating instructions

* Updating instructions.

* Removed duplicated text.

* Updating instructions

* Updating instructions for clarity

* Updating instructions

* Commented out some values for the initial run of 1 timestep

* Updating instructions

* Adding missing word

* Fixing typos

* Updated instructions

* Updating instructions

* Changing numProcsX from 8 to 4

* Added detail

* Resolving error

* Added binry-to-netcdf scripts, parameters files and documentation content associated with demostraition through the DISPERSION CBL case. Made a couple other minor documentation content modifications to fix typos and remove an uneccesary flag from the two FastEddy batch submission scripts.

* A few more wording adjustments and typo corrections for the DISPERSION case

* Adjustments to Idealized cases overview content and case titles.

* Fixed underline length warning from documentation builds.

---------

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

docs/Tutorials/cases.rst

@@ -8,6 +8,9 @@ Seven test cases are described:
 * Dry convective boundary layer
 * Dry stable boundary layer
 * Moist cloud-topped boundary layer
+* Canopy inclusive boundary layer
+* Offshore boundary layer
+* Passive scalar transport and dispersion over an idealized hill
 
 Required tutorial resources including python utilities and Jupyter Notebooks are provided in the tutorials directory of the `FastEddy-model GitHub repository <https://github.com/NCAR/FastEddy-model>`_ with required data for the moist dynamics example available at this `Zenodo record <https://zenodo.org/records/10982246>`_. All test cases are idealized setups over flat terrain. For each case, the user will set up the input parameter file, execute FastEddy, visualize the output using a Jupyter notebook, and perform some basic analysis of the output. After examining the test cases, the user will carry out some sensitivity tests by changing various input parameters. The purpose of these tests are for the user to become more familiar with the input parameters, and how changes to those parameters affect the output. After the tutorial, the user is expected to have basic knowledge to carry out LES using FastEddy.
 

docs/Tutorials/cases/CANOPY.rst

@@ -1,5 +1,5 @@
 =================================================
-Boundary layer in the presence of resolved canopy
+Canopy inclusive boundary layer
 =================================================
 
 Background
@@ -41,22 +41,33 @@ Input parameters
 Execute FastEddy
 ----------------
 
-Note that this example requires specification of a leaf area density (LAD) profile. A Jupyer notebook is provided in **/tutorial/notebooks/Canopy_Prep.ipynb** that reads in an LAD profile in .csv format (*LAD_profile.csv* at `Zenodo record <https://zenodo.org/records/12610511>`_) and uses a FastEddy initial condition file to create a new initial condition file that includes de LAD information (CanopyLAD array). The notebook expects a canopy height value to be specified (:math:`h_c`), and that is currently set to 30.0 m.
+Note that this example requires specification of a leaf area density (LAD) profile. A Jupyter notebook is provided in **tutorial/notebooks/Canopy_Prep.ipynb** that reads in an LAD profile in .csv format. The *LAD_profile.csv* file can be obtained at this `Zenodo record <https://zenodo.org/records/12610511>`_. The notebook also uses a FastEddy initial condition file to create a new initial condition file, *FE_CANOPY.0*, that includes de LAD information (CanopyLAD array). The notebook expects a canopy height value to be specified (:math:`h_c`), and that is currently set to 30.0 m. 
 
-Run FastEddy using the input parameters file **/tutorials/examples/Example05_CANOPY.in** first for 1 timestep to create the *FE_CANOPY.0* file.  To run for 1 timestep, the following values need to be changed in the **/tutorials/examples/Example05_CANOPY.in** file:
+1. Create a working directory to run the FastEddy tutorials and change to that directory.
+2. Create a **Example05_CANOPY** subdirectory and change to that directory.
+3. The FastEddy code will write its output to an **output** subdirectory. Create an **output** directory, if one does not already exist.   
+4. Download the *LAD_profile.csv* and place it in an *initial* subdirectory at the same level as the **output** subdirectory.
+5. First, run FastEddy using the input parameters file **tutorials/examples/Example05_CANOPY.in** for 1 timestep to create the *FE_CANOPY.0* file.  To run for 1 timestep, the following values need to be changed in the **tutorials/examples/Example05_CANOPY.in** file:
 
-  * Change :code:`frqOutput` from 30000 to 1
-  * Change :code:`Nt` from 1440000 to 1
-  * Change :code:`NtBatch` from 30000 to 1
+   * Change :code:`frqOutput` from 30000 to 1
+   * Change :code:`Nt` from 1440000 to 1
+   * Change :code:`NtBatch` from 30000 to 1
 
-After running for 1 timestep, then run the Jupyter notebook to modify the CanopyLAD array to include the LAD profile instead of the initialized all zeros. Do this by modifying :code:`inPath` and :code:`inFile` to point to the initial condition *FE_CANOPY.0* file. Then, run FastEddy for the :math:`4` h of the simulation by changing :code:`frqOutput`, :code:`Nt`, and :code:`NtBatch` back to their original values.
+6. After running for 1 timestep, run the Jupyter notebook *Canopy_Prep.ipynb* file modifying the CanopyLAD array to include the LAD profile instead of the initialized all zeros. Modify `path_base` in this notebook file, specifying the path to the **initial/** directory that contains the *LAD_profile.csv* file. Be sure to including the trailing slash :code:`/` in :code:`path_base`. Note that this run of the Jupyter notebook will write a *FE_CANOPY.0* in the **initial** subdirectory.
+7. Then, run FastEddy for the :math:`4` h of the simulation by changing :code:`frqOutput`, :code:`Nt`, and :code:`NtBatch` back to their original values in **tutorials/examples/Example05_CANOPY.in**, and modify :code:`inPath` and :code:`inFile` in **tutorials/examples/Example05_CANOPY.in**, specifying the path and the filename, respectively, for the newly written initial condition *FE_CANOPY.0* file in the **initial** directory. Be sure to including the	trailing slash :code:`/` in the :code:`inPath`.
 
 See :ref:`run_fasteddy` for instructions on how to build and run FastEddy on NSF NCAR's High Performance Computing machines.
 
 Visualize the output
 --------------------
 
-Open the Jupyter notebook entitled *MAKE_FE_TUTORIAL_PLOTS.ipynb* and execute it using setting: :code:`case = 'canopy'`.
+1. Open the Jupyter notebook entitled *MAKE_FE_TUTORIAL_PLOTS.ipynb*.
+2. Under the "Define parameters" section, modify :code:`path_base`, specifying the full path to the **Example05_CANOPY** subdirectory, but don't include **Example05_CANOPY** subdirectory. Be sure to include a trailing slash :code:`/`).
+3. Under the "Define parameters" section, modify :code:`case` to set its value to :code:`canopy`.
+4. Run the Jupyter notebook.
+5. The resulting XY cross section png plots will be placed in a **FIGS** subdirectory of the **Example05_CANOPY** directory.
+
+
 
 XY-plane views of instantaneous velocity components at :math:`t=4` h (FE_CANOPY.1440000):
 

docs/Tutorials/cases/CBL.rst

@@ -37,14 +37,21 @@ Input parameters
 Execute FastEddy
 ----------------
 
-Run FastEddy using the input parameters file **/tutorials/examples/Example02_CBL.in**.
+1. Create a working directory to run the FastEddy tutorials and change to that directory.
+2. Create a **Example02_CBL** subdirectory and change to that directory.
+3. The FastEddy code will write its output to an **output** subdirectory. Create an **output** directory, if one does not already exist.   
+4. Run FastEddy using the input parameters file *Example02_CBL.in* located in the **tutorials/examples/** subdirectory of the FastEddy repository. 
 
 See :ref:`run_fasteddy` for instructions on how to build and run FastEddy on NSF NCAR's High Performance Computing machines.
 
 Visualize the output
 --------------------
 
-Open the Jupyter notebook entitled *MAKE_FE_TUTORIAL_PLOTS.ipynb* and execute it using setting: :code:`case = 'convective'`.
+1. Open the Jupyter notebook entitled *MAKE_FE_TUTORIAL_PLOTS.ipynb*.
+2. Under the "Define parameters" section, modify :code:`path_base`, specifying the full path to the **Example02_CBL** subdirectory, but don't include the **Example02_CBL** subdirectory. Be sure to include a trailing slash :code:`/`).
+3. Under the "Define parameters" section, modify :code:`case` to set its value to :code:`convective`.
+4. Run the Jupyter notebook.
+5. The resulting XY cross section png plots will be placed in a **FIGS** subdirectory of the **Example02_CBL** directory.
 
 XY-plane views of instantaneous velocity components at :math:`t=4` h (FE_CBL.288000):
 

docs/Tutorials/cases/DISPERSION.rst

@@ -1,6 +1,6 @@
-==================================================
-Transport and dispersion over idealized topography
-==================================================
+==============================================================
+Passive scalar transport and dispersion over an idealized hill
+==============================================================
 
 Background
 ----------
@@ -38,23 +38,32 @@ Input parameters
 Execute FastEddy
 ----------------
 
+See :ref:`run_fasteddy` for general instructions on how to build and run FastEddy on NSF NCAR's High Performance Computing machines.
+
 Note that this example requires customization of the initial condition file. Follow the sequence of steps below.
 
-#. Exectue the Jupyer notebook provided in **/tutorial/notebooks/Dispersion_Prep1.ipynb** to create the topography file *Topography_504x498.dat*. 
-#. Run FastEddy for 1 timestep using the default state of the (*Example07_DISPERSION_SBL.in*) and required binary terrain file generated in the previous step, specified as input through the FastEddy parameter file (:code:`topoFile`). This step creates an output file *FE_DISPERSION.0* that includes the topography and establishes a terrain-following vertical coordinate grid. 
-#. Exectute the Jupyer notebook provided in **/tutorial/notebooks/Dispersion_Prep2.ipynb** to modify the surface roughness distribution over the hill. 
-#. Execute the Jupyer notebook provided in **/tutorial/notebooks/Dispersion_Prep3.ipynb** to create the source specification input file. 
-#. Adjust the (*Example07_DISPERSION_SBL.in*) file to specify the targeted initial condition file (:code:`inPath`, :code:`inFile`) by removing the (:code:`#`) just to the right of the equal sign ito uncomment these parameters values. Uncomment the pre-formed passive tracer source file (:code:`srcAuxScFile`). Remove the value of :math:`0` and uncomment the value of :math:`2` for the number of source emissions (:code:`NhydroAuxScalars`).
-#. Run FastEddy for :math:`1` h of the simulation by changing :code:`frqOutput`, :code:`Nt`, and :code:`NtBatch` removing the values of :math:`1` for each and the (:code:`#`) to uncomment appropriate full-simulation parameters values. 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 initial condition and terrain preparation steps only need to be carried out once for the stable case, then can be reused directly in the convective stability case.
+1. Create a working directory to run the FastEddy tutorials and change to that directory.
+2. Create a **Example07_DISPERSION_SBL** subdirectory and change to that directory.
+3. Copy the **tutorials/examples/Example07_DISPERSION_SBL.in** file into the **Example07_DISPERSION_SBL** subdirectory.
+4. Execute the Jupyter notebook provided in **tutorials/notebooks/Dispersion_Prep1.ipynb** to create the topography file *Topography_504x498.dat*, which will be written to the **Example07_DISPERSION_SBL** subdirectory. Users will need to set code:`path_case` in the "Generate the WOA hill terrain file" section to specify the full path to and including the **Example07_DISPERSION_SBL** subdirectory. Be sure to include the trailing slash :code:`/`.
+5. The FastEddy code will write its output to an **output** subdirectory. Create an **output** directory, if one does not already exist.
+6. Run FastEddy for 1 timestep using the default state of the (*Example07_DISPERSION_SBL.in*) and required binary terrain file generated in the previous step, specified as input through the FastEddy parameter file (:code:`topoFile`). This step creates an output file *FE_DISPERSION.0* that includes the topography and establishes a terrain-following vertical coordinate grid. 
+7. Create an **initial** subdirectory under **Example07_DISPERSION_SBL**, if one does not already exist. Execute the Jupyter notebook provided in **tutorial/notebooks/Dispersion_Prep2.ipynb** to modify the surface roughness distribution over the hill. Running this Jupyter notebook will create a new *FE_DISPERSION.0* file in the **initial** subdirectory. Users will need to set code:`path_case` in the "Modify z0 after terrain has been incorporated" section to specify the full path to and including the **Example07_DISPERSION_SBL** directory. Be sure to include the trailing slash :code:`/`.
+8. Execute the Jupyter notebook provided in **/tutorial/notebooks/Dispersion_Prep3.ipynb** to create the source specification input file. Users will need to set :code:`path_base` in the "Create the input file with AuxScalar information" section to specify the full path to and including the **Example07_DISPERSION_SBL** subdirectory. Be sure to include the trailing slash :code:`/`. Executing this notebook will produce a *Example07_sources.nc* file in the **Example07_DISPERSION_SBL** subdirectory.
+9. Adjust the *Example07_DISPERSION_SBL.in* file to specify the targeted initial condition file (:code:`inPath`, :code:`inFile`) by removing the :code:`#` just to the right of the equal sign to uncomment these parameters values. Uncomment the pre-formed passive tracer source file (:code:`srcAuxScFile`). Remove the value of :math:`0` and uncomment the value of :math:`2` for the number of source emissions (:code:`NhydroAuxScalars`). Run FastEddy for :math:`1` h of the simulation by changing :code:`frqOutput`, :code:`Nt`, and :code:`NtBatch` removing the values of :math:`1` for each and the (:code:`#`) to uncomment appropriate full-simulation parameters values. The emissions begin :math:`45` min into the simulation.  
 
-See :ref:`run_fasteddy` for instructions on how to build and run FastEddy on NSF NCAR's High Performance Computing machines.
+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 initial condition and terrain preparation steps only need to be carried out once for the stable case, then can be reused directly in the convective stability case. 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. 
+To run the convective case and exercise the binary output functionality, create a **Example07_DISPERSION_CBL** subdirectory and change to that directory. Create an **initial** subdirectory and copy the initial condition file from **Example07_DISPERSION_SBL/initial/** into the **Example07_DISPERSION_CBL/initial/** subdirectory. Create an **output_binary** subdirectory where binary files will be written during the simulation. Then 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.  
 
 Visualize the output
 --------------------
 
-Open the Jupyter notebook entitled *MAKE_FE_TUTORIAL_PLOTS.ipynb* and execute it using setting: :code:`case = 'dispersion'`.
+1. Open the Jupyter notebook entitled *MAKE_FE_TUTORIAL_PLOTS.ipynb*.
+2. Under the "Define parameters" section, modify :code:`path_base`, specifying the full path to the **Example07_DISPERSION_SBL** subdirectory, but don't include **Example07_DISPERSION_SBL** subdirectory. Be sure to include a trailing slash :code:`/`).
+3. Under the "Define parameters" section, modify :code:`case` to set its value to :code:`dispersion`.
+4. Run the Jupyter notebook.
+5. The resulting XY cross section png plots will be placed in a **FIGS** subdirectory of the **Example07_DISPERSION_SBL** directory.
+
 
 XY-plane views of instantaneous velocity components and potential temperature for the SBL case at :math:`t=1` h (FE_DISPERSION.360000). The contour lines in the :math:`u` panel display terrain elevation:
 

docs/Tutorials/cases/MBL.rst

@@ -31,10 +31,15 @@ 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 at `Zenodo record <https://zenodo.org/records/10982246>`_. The contents of the archive include an initial conditions file **BOMEX_IC/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 under **BOMEX_Siebesma2003_models/\*.nc**. Run FastEddy using the input parameters file **/tutorials/examples/Example04_BOMEX.in**. Be sure to copy the extracted initial conditions file from the archived dataset into the subdirectory where you will run this case. 
+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.
 
-See :ref:`run_fasteddy` for instructions on how to build and run FastEddy on NSF NCAR's High Performance Computing machines.
+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.
+3. Download and unpack *Moist_BOMEX.tar.gz*, which will create a **BOMEX_IC/** subdirectory containing *FE_BOMEX.0* and a **BOMEX_Siebesma2003_models/** subdirectory creating the above referenced NetCDF files.
+4. Modify the **tutorials/examples/Example04_BOMEX.in** file to update the value of :code:`inPath` providing the full path to the *FE_BOMEX.0* file in the **BOMEX_IC/** subdirectory. Be sure to including the trailing slash :code:`/`.
+5. Run FastEddy using the input parameters file **tutorials/examples/Example04_BOMEX.in**. 
 
+See :ref:`run_fasteddy` for instructions on how to build and run FastEddy on NSF NCAR's High Performance Computing machines.
 
 Note that running this case requires using only 1 GPU instead of 4 GPUs. This requires modification of two lines in the scripts provided in :ref:`run_fasteddy`.
 The following:
@@ -55,6 +60,16 @@ And, any values of *4* in the last line of the script (the :code:`mpirun` line f
 Visualize the output
 --------------------
 
+1. Open the Jupyter notebook entitled *FE_Postprocessing_Example04_BOMEX.ipynb*.
+2. Under the "Define parameters" section:
+
+   * Modify :code:`path_root`, specifying the full path up to and including the **Example04_BOMEX** subdirectory. Be sure to include the trailing slash :code:`/`.
+   * Modify :code:`path_ini` changing **initial/** to **BOMEX_IC/**. For example, :code:`path_ini = path_root +  'BOMEX_IC/'`.
+   * Modify :code:`path_sieb` changing its value to **BOMEX_Siebesma2003_models/**, if you unpacked the *Moist_BOMEX.tar.gz* file into the **Example04_BOMEX** subdirectory.  For example, :code:`path_sieb = path_root + 'BOMEX_Siebesma2003_models/'`.
+
+3. Run the Jupyter notebook.
+4. The resulting XY cross section png plots will be placed in a **Figures_BOMEX** subdirectory of the **Example04_BOMEX** directory.
+
 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):