refactor HSD docs

doc/UsersGuide/source/CAPE2020.rst

@@ -0,0 +1,90 @@
+.. role:: raw-html(raw)
+    :format: html
+
+.. _cape-2020:
+
+====================
+July 2020 CAPE Case
+====================
+
+The July 2020 CAPE case is an atmosphere-only forecast run at C48 resolution with 127 vertical levels. It is set to run a 24-hour forecast from 2020-07-23 at 0z using the `FV3_GFS_v16 <https://dtcenter.ucar.edu/GMTB/v7.0.0/sci_doc/_g_f_s_v16_page.html>`_ physics suite and default values from the WM's `default_vars.sh <https://github.com/ufs-community/ufs-weather-model/blob/develop/tests/default_vars.sh>`_ ``export_fv3_v16`` function.
+
+The original July 2020 CAPE case illustrated a shortcoming of the Global Forecast System (GFS) v16 --- low Convective Available Potential Energy (CAPE) predictions during summertime (:cite:t:`SunEtAl2024`). :cite:t:`SunEtAl2024` (2024) used this case study to investigate the low CAPE bias in the GFS and determined that "the GFS simulates smaller surface latent heat flux and larger surface sensible heat flux than the observations" due to "slightly drier-than-observed soil moisture" within the offline Global Data Assimilation System (GDAS) initial conditions used in the study. This resulted in less latent heat and moisture being fed back to the lower levels of the atmosphere and ultimately changed the overall vertical profile of the atmosphere, which lowered CAPE values relative to the older GFS v15.2. 
+
+The UFS WM and its subcomponents have undergone signficant changes since the original July 2020 CAPE case study was posted and since :cite:t:`SunEtAl2024`'s experiment, so the current GFS v16 CAPE bias may have shifted. However, users may still wish to run this case and then experiment with different (potentially user-generated) initial conditions, a coupled land surface model (LSM), or other factors to explore factors that improve or worsen CAPE bias. Additionally, :cite:t:`SunEtAl2024`'s findings only apply to this case study, so users may wish to expand their research to include other warm-season cases. 
+
+============================================
+Obtaining Data for the July 2020 CAPE Case
+============================================
+
+.. include:: ./doc-snippets/hsd_data.rst
+
+User-Generated Data
+---------------------
+
+Users can enable the WM to run using GFS initial conditions (ICs) from the UFS Case Studies page. 
+
+.. _run-cape:
+
+=================================
+Running the July 2020 CAPE Case
+=================================
+
+This section explains how to run the July 2020 CAPE case described above using the ``ufs-test.sh`` script.
+
+Clone the Repository
+--------------------
+
+.. include:: ./doc-snippets/clone_hsd.rst
+
+Machine Configuration
+-----------------------
+
+.. include:: ./doc-snippets/hsd_machine_config.rst
+
+.. _cape-config:
+
+Test Configuration
+----------------------
+
+The July 2020 CAPE case can be run as-is without adjusting the configuration. 
+
+Baseline Configuration
+----------------------
+
+.. include:: ./doc-snippets/hsd_baseline_config.rst
+
+Running Tests
+-------------
+
+.. include:: ./doc-snippets/hsd_run_tests.rst
+
+Examples
+^^^^^^^^^^
+
+A user with access to the ``epic`` account can run the ``2020_CAPE`` test case with the ``intel`` compiler on ``Hera``, ``Orion``, or ``Gaea`` using the following command:
+
+.. code-block:: console
+
+   ./ufs_test.sh -a epic -s -c -k -r -n "2020_CAPE intel"
+
+Running Multiple Cases
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: ./doc-snippets/hsd_run_multiple.rst
+
+.. _check-results:
+
+Checking Results
+-----------------
+
+.. include:: ./doc-snippets/hsd_check_results.rst
+
+For example, to monitor progress or check results for the ``2020_CAPE_intel`` case, run:
+
+.. code-block:: console
+
+   tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/err
+   tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/out
+
+.. include:: ./doc-snippets/hsd_notes.rst

doc/UsersGuide/source/HSD.rst

@@ -0,0 +1,33 @@
+.. role:: raw-html(raw)
+    :format: html
+
+.. _hsd:
+
+********************************************
+Hierarchical System Development (HSD) Cases
+********************************************
+
+Hierarchical System Development is the ability to engage in development and testing at multiple levels of complexity in numerical weather prediction (NWP) software (such as the :term:`UFS`). It typically includes multiple entry points into development (e.g., atmospheric physics, ocean and ice dynamics, or data assimilation for land models and other earth system components), and it can include both operationally relevant and idealized configurations. 
+
+Although the UFS Weather Model (WM) can be run in any of several configurations, from a single-component atmospheric 
+model to a fully coupled model with multiple earth system components (e.g., atmosphere, ocean, sea-ice, land, mediator), 
+this chapter documents just a few of the cases designed to support hierarchical system development (HSD) within the UFS. 
+
+.. toctree::
+   :maxdepth: 3
+
+   CAPE2020
+   baroclinic_wave
+
+Currently, users can find information on running the following HSD cases:
+
+   * The :ref:`July 2020 CAPE Case <cape-2020>`
+   * The :ref:`Baroclinic Instability Case <baroclinic-wave>`
+
+For a full list of supported WM configurations, view the `rt.conf <https://github.com/ufs-community/ufs-weather-model/blob/develop/tests/rt.conf>`_ file.
+
+.. attention::
+
+   This chapter is a work in progress. There are a multitude of options for configuring the UFS WM, 
+   and this chapter merely details a few supported configurations. It will be expanded over time
+   to include a wide variety of idealized test cases for use in research and testing.